Runtime overview
The runtime section describes how AgentForge runs one agent call, from the HTTP request to the Claude CLI subprocess and back. There are three ways a model call is made, and they share one decorator stack and one ledger.
| Path | Entry | Runs in | Durable | Page |
|---|---|---|---|---|
| Synchronous run | POST /v1/agent, POST /v1/agent/stream | the API process, per request | No | REST API |
| Session turn | POST /v1/sessions/:id/messages | Temporal workflow agentSessionWorkflow, activities on worker processes | Yes (Postgres + Temporal) | Sessions and workflows |
| Factory step | POST /v1/factory/jobs | Temporal workflow factoryJobWorkflow, per-step Docker sandboxes | Yes | Factory |
CodeCrucible runs (/v1/quality/*) use model-less sandboxes and are documented in the quality section.
Building blocks
Key points:
- The API and the workers never hold an Anthropic API key.
loadConfiginapps/api/src/config.tsthrows whenANTHROPIC_API_KEYis set; the factory and exec roles refuse it too. Every model call goes through the gateway with a per-turn job token (see Gateway and Job tokens and policies). - Postgres decides every terminal outcome. Temporal carries ids and, since the worker-fleet split, AES-256-GCM encrypted prompts and replies.
- The Claude CLI runs as a subprocess of the process that calls
ClaudeRuntime.run, with a closed environment and a temporaryHOME. See Runtimes and CLI.
The decorator stack
Every runtime call, in the API and in the workers, goes through createAgentRuntime in packages/agent-core. It wraps the inner runtime in this order, outermost first:
The details, invariants and constants are on Agent core decorators.
Where each run mode gets its numbers
| Setting | Sync API run | Session turn | Factory step |
|---|---|---|---|
Per-request cap (PER_REQUEST_CAP_USD) | API default 0.5 | worker default 2 | factory worker default 0.5 (must be at least every role cap) |
Sonnet minimum reservation (SONNET_MIN_RESERVATION_USD) | API default 0.5 | worker default 0.5 | factory worker default 0.05 |
| Turns | request maxTurns 1..10, default 5 | agent-core default 5 | FACTORY_MAX_TURNS default 30, max 50 |
| Timeout | request timeoutMs 1000..300000, default 120 s | agent-core default 120 s | FACTORY_STEP_TIMEOUT_MS default 600 s, max 840 s |
| Profile | readonly | readonly | factory-planner, factory-coder, factory-reviewer |
| Tools | Read, Glob, Grep | Read, Glob, Grep | planner and reviewer: read tools; coder: Bash, Read, Glob, Grep, Edit, Write |
Lifecycle of a synchronous run
Section map
- REST API: every route, auth, rate limits, idempotency, status codes.
- Sessions and workflows: the durable session workflow and its activities.
- Agent core decorators: guard, limits, budget, kill switch, redaction, alerts.
- Runtimes and CLI: the runtime port, the Claude adapter, the sandbox adapter, the conformance suite.
- Worker fleet: exec workers, queues, fleet exposure design.
Sources
packages/agent-core/src/index.ts(createAgentRuntime,collectResult)packages/agent-types/src/index.ts(AgentRuntime,RuntimeEvent,RuntimeStatus,ErrorCode,ProfileName)apps/api/src/app.ts,apps/api/src/runtime.ts,apps/api/src/config.tsapps/worker/src/runtime.ts,apps/worker/src/config.ts,apps/worker/src/factory/config.tsapps/worker/src/main.ts,apps/worker/src/factory-main.ts,apps/worker/src/exec-main.tsdocs/design-worker-fleet.md