Fleetctl architecture
Fleetctl combines cloud-based workflow authoring and governance with a locally installed binary 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
▼
Locally installed Fleet binary
sync · triggers · schedules · one runtime per repo
│
▼
internal/genflow engine
typed steps · routes · retries · suspension · provenance
│ │ │
▼ ▼ ▼
Claude Code / OpenCode human approvals artifacts / PRs
Claude, Codex, Grok, … │ │
│ │ │
└──────────── report result / resume ────┘How Fleetctl runs coding agents
Fleetctl is not a coding model. Coding work runs through Claude Code or OpenCode. The model can be Claude, Codex, Grok, or any other model those harnesses support. Fleetctl starts the harness, supplies the workflow step prompt, enforces budgets and house rules, and records the audit trail.
MCP clients are the same set: Claude Code, Codex, OpenCode, or any other MCP-compatible assistant can talk to Fleetctl over hosted Streamable HTTP or local stdio. Fleetctl does not require a particular chat product.
Claude Code's agent view (the claude agents command, sometimes called FleetView) lists sessions. Fleetctl is a separate control plane: saved multi-step workflows, retries, approvals, artifacts, and merge gates. You can use both.
Model routing stays with the harness you configure: Anthropic, Bedrock, Vertex, or the provider OpenCode is pointed at. Source code goes to that model backend and GitHub, not to Fleetctl. Operational metadata syncs to app.fleetctl.ai after registration.
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
Local binary owns
- Repository working trees and source files
- Claude Code or OpenCode sessions, plus tmux
- 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.
- 2The locally installed binary 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 local binary 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. Workflow definitions control 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.