Handbook
Agent orchestrator
The orchestrator (orchestrator/) is human-gated ops tooling that maintains the agent registry, bridges Matrix lifecycle (register/deregister bot users), and maps desired agent state to Fleet container-services.
Updated
Autonomy ceiling: A1_supervised — register, deregister, and Fleet start/stop require explicit operator or policy gate.
Registry
The registry tracks desired vs actual state per agent id:
| Field | Meaning |
|---|---|
agent_id |
Stable catalog id (communication, cursor_bridge, …) |
desired_state |
registered, running, stopped, deregistered |
actual_state |
Observed from Fleet health + Matrix presence |
fleet_ref |
Fleet job or container-service id when running |
matrix_user |
@bot:matrix.forgedc.net when registered |
Persistence: SQLite or YAML on Granite (operator choice at install). Records conform to forge.agent_registry.v1.
API (v1)
| Endpoint | Method | Purpose |
|---|---|---|
/v1/agents |
GET | List registry entries + health |
/v1/agents/{id} |
GET | Single agent detail |
/v1/agents/{id}/register |
POST | Register Matrix user + desired state |
/v1/agents/{id}/deregister |
POST | Remove Matrix user + stop Fleet service |
/v1/agents/{id}/start |
POST | Start Fleet container-service |
/v1/agents/{id}/stop |
POST | Stop Fleet container-service |
/health |
GET | Orchestrator liveness |
Register and deregister wrap Synapse admin (register_new_matrix_user) via matrix_admin.py. Manual fallback is documented in the Granite runbook when admin API is unavailable.
Matrix lifecycle
- Operator calls
POST /v1/agents/communication/register - Orchestrator creates
@commbot:matrix.forgedc.net(example) via Synapse admin - Orchestrator invites bot to
#communication(unencrypted) - Fleet starts communication container-service
- Bot connects and serves
!commcommands
Deregister reverses: stop Fleet → leave rooms → deactivate Matrix user.
cursor_bridge hybrid: when headless Cursor CLI auth fails inside a container, the orchestrator documents laptop fallback — host worker via SSH tunnel + NATS, same as pre-migration forge-cursor-bridge flow.
Fleet integration
fleet_client.py maps registry actions to existing Fleet API:
| Registry action | Fleet call |
|---|---|
start |
POST /v1/jobs or container-service create with docker_argv template from packaging |
stop |
Container-service stop / job cancel |
health |
Poll Fleet job summary + container exit code |
Templates come from agent.package.v1 manifests built by the packaging CLI. Orchestrator does not fork Fleet or introduce a second job plane.
Compose fragment: orchestrator/compose.fragment.yaml — merged into Granite stack by install-granite.sh.
Web UI and chat proxy
The orchestrator serves a minimal web UI and /api/chat proxy (phase A10) for browser access alongside Matrix. Exposure options:
- FAEP:
/admin/apps/forge-agents/(authenticated admin path) - Caddy: optional
/agents/route per Granite runbook
Chat proxy forwards to registered agent backends; it does not replace Matrix for mobile ops.
Lenses boundary
The orchestrator emits projections only. Lenses remains the ForgeRun system of record. Channel agent activity may link to forge.chat_intent.v1 / forge.agent_event.v1 envelopes but does not write ForgeRun final state.