Skip to main content

System context

This page shows AgentForge at two C4 levels: the system context (who and what AgentForge talks to) and the containers (the separately deployed processes and stores). Hosts are described by role ("the core host", "a fleet host", "the sandbox host"), never by name or address.

Level 1: system context​

External systemWho talks to itEvidence
Model provider APIapps/gateway only. UPSTREAM_BASE_URL must equal https://api.anthropic.com unless GATEWAY_TEST_UPSTREAM=1 and NODE_ENV=testapps/gateway/src/config.ts (ANTHROPIC_UPSTREAM, superRefine)
GitHubThe factory worker, with two GitHub Apps (read-PR and push)apps/worker/src/factory/config.ts (GITHUB_APP_READ_PR_*, GITHUB_APP_PUSH_*, GITHUB_API_URL, GITHUB_GIT_URL)
Identity providerThe gateway, for on-behalf-of exchange; all three GATEWAY_IDP_* or none; none means every exchange is deniedapps/gateway/src/config.ts
Upstream MCP serversThe gateway (POST /mcp), from YAML files in GATEWAY_REGISTRY_DIRapps/gateway/src/config.ts, packages/agent-mcp/src/loader.ts
Alert webhookAPI, session worker, factory worker (budget alerts at 50% and 80% of the global daily limit)packages/agent-core/src/config.ts (globalDailyLimitUsd comment)

Level 2: containers​

Which processes share a host is a deployment choice, not a code rule. The grouping above follows the roles in docs/deploy-quality.md, docs/deploy-sandbox.md and docs/design-worker-fleet.md; see Deployment topology for what is actually deployed. CodeCrucible exec hosts are Unverified: docs/deploy-quality.md states it was built and tested locally only.

Container responsibilities​

ContainerResponsibilityTalks to
APIAuthenticates clients (API_KEYS), validates strict JSON, rate limits, runs synchronous agent calls through the decorated runtime, starts and signals workflows, serves views from PostgresPostgres, Temporal (lazy; unset TEMPORAL_ADDRESS makes session routes answer 503), gateway control port
Session workerRuns agentSessionWorkflow, the turn activities (prepareTurn, finishTurn, failTurn, closeSession), the -exec-core fallback queue, optionally the -exec fleet queue (WORKER_ALSO_EXEC, default true) and, with QUALITY_ENABLED, the quality workflows and core activitiesPostgres, Temporal, gateway control and data ports
Exec workerRuns only executeTurn (the CLI turn) with a job token minted by prepareTurnTemporal, gateway data port
Factory workerRuns factoryJobWorkflow: plan, code, test, review steps in per-job sandbox containers, approvals, PRPostgres, Temporal, Docker, gateway control port, GitHub
Sandbox runnerRuns one role profile inside the container with the Claude Agent SDK; reaches only the gatewayGateway data port
Quality exec workerprepareWorkspace on the shared queue, everything else on its identity queue agentforge-quality-exec-<identity>; runs the quality image by digestTemporal, Docker, local bare mirror
GatewayModel proxy (POST /v1/messages), MCP proxy (POST /mcp), GET /health on the data port; job and subject registration on the control port; metering debits; audit rowsPostgres, model provider, IdP, upstream MCP servers

Gateway routes by listener​

ListenerDefault portRoutes
Data (GATEWAY_DATA_HOST, GATEWAY_DATA_PORT)8787POST /v1/messages, POST /mcp, GET /health; anything else is refused before authentication
Control (GATEWAY_CONTROL_HOST or GATEWAY_CONTROL_BIND_CIDR, GATEWAY_CONTROL_PORT)8788POST /control/v1/subjects, POST /control/v1/jobs, DELETE /control/v1/jobs/:requestId, GET /control/v1/health

The two listeners must differ: either different hosts, or (with GATEWAY_CONTROL_BIND_ANY=private-network-only) different ports. See Gateway for request handling.

Trust boundaries​

The role refusals that enforce the secret-holder column are listed on Configuration. The threat analysis is on Threat model.

Temporal namespaces and task queues​

NameKindDefined in
agentforge-prodDefault TEMPORAL_NAMESPACE of api, session worker, exec worker, factory workerthe respective config.ts
agentforge-qualityDefault TEMPORAL_NAMESPACE of the quality exec workerapps/worker/src/quality/exec-config.ts
agentforge-sessionsSESSION_TASK_QUEUEpackages/agent-workflows/src/workflows/shared.ts
agentforge-sessions-execexecTaskQueue(SESSION_TASK_QUEUE), the fleet queuesame
agentforge-sessions-exec-coreexecCoreTaskQueue(...), the core fallbacksame
agentforge-factoryFACTORY_TASK_QUEUEpackages/agent-workflows/src/workflows/factory-shared.ts
agentforge-qualityQUALITY_TASK_QUEUEpackages/agent-workflows/src/workflows/quality-shared.ts
agentforge-quality-exec, agentforge-quality-exec-<identity>QUALITY_EXEC_TASK_QUEUE, qualityExecIdentityQueue(identity)same

Workflow ids: session-<sessionId>, factory-<jobId>, quality-<runId>. Workflow types: agentSessionWorkflow, factoryJobWorkflow, qualityAssessmentWorkflow, qualityVerifyWorkflow. See Sessions and workflows.

Note: the session worker registers the agentforge-quality task queue in its own TEMPORAL_NAMESPACE (apps/worker/src/worker.ts), while the API can start quality workflows in QUALITY_TEMPORAL_NAMESPACE. How a separate quality namespace is served by a core worker is not shown in the code read for this page (Unverified).

Sources​

  • apps/gateway/src/config.ts (ANTHROPIC_UPSTREAM, GatewayEnv, controlHostFromCidr, loadConfig)
  • apps/gateway/src/proxy.ts (ROUTES), apps/gateway/src/control.ts (route registrations)
  • apps/api/src/config.ts, apps/worker/src/config.ts, apps/worker/src/exec-config.ts, apps/worker/src/factory/config.ts, apps/worker/src/quality/exec-config.ts
  • apps/worker/src/worker.ts (runWorker), apps/worker/src/quality-exec-main.ts
  • packages/agent-workflows/src/workflows/shared.ts, factory-shared.ts, quality-shared.ts
  • packages/agent-core/src/config.ts
  • docs/deploy-quality.md, docs/deploy-sandbox.md, docs/design-worker-fleet.md, docs/design-gateway-fleet-exposure.md