D 2026-10-13T02:27:53.200
L Leaf\sAgent
N text/x-markdown
U dmestas
W 2071
# Leaf Agent
A Go daemon that sits next to a Fossil repo and keeps it synced over NATS.
## Data Flow
``` pikchr
right
R: cylinder "repo.fossil" color white fill 0x3a3a3a width 1.2 height 0.5 rad 3px
move 0.2
arrow color white thick <->
move 0.1
A: box "Leaf Agent" color white fill 0x2a6b3a width 1.5 height 0.5 rad 5px
move 0.2
arrow color white thick "sync request" above
move 0.1
N: cylinder "NATS" color white fill 0x2a4a6b width 1.0 height 0.5 rad 5px
move 0.2
arrow color white thick
move 0.1
B: box "Bridge" color white fill 0x6b5a2a width 1.2 height 0.5 rad 5px
move 0.2
arrow color white thick "HTTP" above
move 0.1
F: box "Fossil" color white fill 0x6b2a2a width 1.2 height 0.5 rad 5px
```
## How It Works
1. Opens a `.fossil` repo — reads project/server codes from SQLite
2. Connects to NATS
3. Polls every 5s (configurable):
- Checks `unsent`/`unclustered` tables
- If new artifacts found, calls `sync.Sync()` via NATS transport
4. `SIGUSR1` triggers immediate sync
5. `SIGINT`/`SIGTERM` graceful shutdown
## Usage
```
leaf-agent --repo /path/to/repo.fossil \
--nats nats://localhost:4222 \
--poll 5s \
--push --pull
```
| Flag | Env Var | Default | Description |
|------|---------|---------|-------------|
| `--repo` | `LEAF_REPO` | (required) | Path to `.fossil` file |
| `--nats` | `LEAF_NATS_URL` | `nats://localhost:4222` | NATS server URL |
| `--poll` | — | `5s` | Poll interval |
| `--user` | `LEAF_USER` | `anonymous` | Sync user |
| `--password` | `LEAF_PASSWORD` | — | Sync password |
| `--push` | — | `true` | Push local artifacts |
| `--pull` | — | `true` | Pull remote artifacts |
| `--prefix` | — | `fossil` | NATS subject prefix |
## Concurrency
The poll goroutine is the sole executor of sync. `SyncNow()` sends on a buffered channel — it never calls sync directly. This avoids concurrent SQLite access.
## See Also
- [Bridge](wiki:Bridge) — the other half
- [Home](wiki:index) — architecture overview
Z 566e7eccd75703e3315e7e8bdb9d4a98