Skip to main content

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.

PathEntryRuns inDurablePage
Synchronous runPOST /v1/agent, POST /v1/agent/streamthe API process, per requestNoREST API
Session turnPOST /v1/sessions/:id/messagesTemporal workflow agentSessionWorkflow, activities on worker processesYes (Postgres + Temporal)Sessions and workflows
Factory stepPOST /v1/factory/jobsTemporal workflow factoryJobWorkflow, per-step Docker sandboxesYesFactory

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. loadConfig in apps/api/src/config.ts throws when ANTHROPIC_API_KEY is 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 temporary HOME. 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​

SettingSync API runSession turnFactory step
Per-request cap (PER_REQUEST_CAP_USD)API default 0.5worker default 2factory worker default 0.5 (must be at least every role cap)
Sonnet minimum reservation (SONNET_MIN_RESERVATION_USD)API default 0.5worker default 0.5factory worker default 0.05
Turnsrequest maxTurns 1..10, default 5agent-core default 5FACTORY_MAX_TURNS default 30, max 50
Timeoutrequest timeoutMs 1000..300000, default 120 sagent-core default 120 sFACTORY_STEP_TIMEOUT_MS default 600 s, max 840 s
Profilereadonlyreadonlyfactory-planner, factory-coder, factory-reviewer
ToolsRead, Glob, GrepRead, Glob, Grepplanner and reviewer: read tools; coder: Bash, Read, Glob, Grep, Edit, Write

Lifecycle of a synchronous run​

Section map​

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.ts
  • apps/worker/src/runtime.ts, apps/worker/src/config.ts, apps/worker/src/factory/config.ts
  • apps/worker/src/main.ts, apps/worker/src/factory-main.ts, apps/worker/src/exec-main.ts
  • docs/design-worker-fleet.md