Architecture
Fleet combines cloud-based workflow authoring and governance with a self-hosted Go worker that executes against your repositories.
System flow
Fleet dashboard
builder · approvals · run history · artifacts
│
│ saved definition / queued run
▼
Control plane API and run queue
│
│ authenticated pull + lease
▼
Self-hosted Fleet watcher
sync · triggers · schedules · one worker per repo
│
▼
internal/genflow engine
typed steps · routes · retries · suspension · provenance
│ │ │
▼ ▼ ▼
Claude Code agents human approvals artifacts / PRs
│ │ │
└──────────── report result / resume ────┘Authoring and execution boundary
Dashboard owns
- Workflow definitions and revisions
- Manual, label, and schedule trigger configuration
- Run queue, statuses, history, and intervention
- Approval evidence and human decisions
- Artifact views and public sharing
Worker owns
- Repository working trees and source files
- Claude Code and tmux agent execution
- Corpus resolution and connector snapshots
- Step routing, cache, retries, and failure handlers
- PR creation, review inputs, merge, and local artifacts
Run lifecycle
- 1A trigger enqueues a run with an immutable workflow definition snapshot.
- 2A worker for the selected repo acquires a lease and fetches the current run record.
- 3The engine validates the graph before any step produces a side effect.
- 4Agent-running steps compose rules, prompt, corpus, and upstream inputs before execution.
- 5Code and approval steps report a suspension and leave the run off the pending queue.
- 6A PR result or human decision requeues the same run with its persisted context.
- 7The worker reports done, failed, or rejected with step results and governance metadata.
Watcher responsibilities
The watcher is the long-running runtime host, not a subscription brain. Its active loops depend on configuration and can include:
Fabric events remain available for decisions, notifications, tasks, and audit. They do not match agent subscriptions to launch work. Coding agents are dispatched directly by workflow code steps.
Package map
| cmd/fleet | CLI router, onboarding, watchers, worker hosting, and local commands. |
| internal/genflow | Typed DAG execution, routing, retries, suspension, step semantics, and provenance. |
| internal/controlplane | Authenticated sync, definition pull, run claim, completion, and resume client. |
| internal/actions | Agent lifecycle, task dispatch, prompt assembly, and worktree launch. |
| internal/artifact | Content-addressed artifact registration and metadata. |
| internal/project | Repo/org discovery plus agents, types, corpus, and connector configuration. |
| internal/store | Local SQLite state for agents, events, tasks, artifacts, rules, and operations. |
| internal/fabric | Events, inbox, tasks, claims, and audit coordination—not subscription execution. |
| internal/brain | Agent evaluation, risk, alerts, quarantine, and evolution. |
| control-plane | Workflow builder, run queue, approvals, artifacts, history, and administration. |
Isolation and identity
tmux sessions: each launched agent has an inspectable, persistent process boundary.
Git worktrees: agents configured with isolation: worktree can run concurrently without changing the shared checkout.
Project scope: agents are unique by name and project, so the same logical role can exist in multiple repositories.
Rules snapshot: workflow steps pin house rules at run start and retain them across suspension and resume.
MCP and local control
fleet mcp serveexposes the registered local operator tools over JSON-RPC 2.0 on stdio. MCP controls local Fleet state and agents; the dashboard's workflow API owns saved definitions, approvals, and run history. Clients should discover MCP tools with tools/listinstead of depending on a hard-coded count.