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 system | Who talks to it | Evidence |
|---|---|---|
| Model provider API | apps/gateway only. UPSTREAM_BASE_URL must equal https://api.anthropic.com unless GATEWAY_TEST_UPSTREAM=1 and NODE_ENV=test | apps/gateway/src/config.ts (ANTHROPIC_UPSTREAM, superRefine) |
| GitHub | The 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 provider | The gateway, for on-behalf-of exchange; all three GATEWAY_IDP_* or none; none means every exchange is denied | apps/gateway/src/config.ts |
| Upstream MCP servers | The gateway (POST /mcp), from YAML files in GATEWAY_REGISTRY_DIR | apps/gateway/src/config.ts, packages/agent-mcp/src/loader.ts |
| Alert webhook | API, 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
| Container | Responsibility | Talks to |
|---|---|---|
| API | Authenticates clients (API_KEYS), validates strict JSON, rate limits, runs synchronous agent calls through the decorated runtime, starts and signals workflows, serves views from Postgres | Postgres, Temporal (lazy; unset TEMPORAL_ADDRESS makes session routes answer 503), gateway control port |
| Session worker | Runs 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 activities | Postgres, Temporal, gateway control and data ports |
| Exec worker | Runs only executeTurn (the CLI turn) with a job token minted by prepareTurn | Temporal, gateway data port |
| Factory worker | Runs factoryJobWorkflow: plan, code, test, review steps in per-job sandbox containers, approvals, PR | Postgres, Temporal, Docker, gateway control port, GitHub |
| Sandbox runner | Runs one role profile inside the container with the Claude Agent SDK; reaches only the gateway | Gateway data port |
| Quality exec worker | prepareWorkspace on the shared queue, everything else on its identity queue agentforge-quality-exec-<identity>; runs the quality image by digest | Temporal, Docker, local bare mirror |
| Gateway | Model 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 rows | Postgres, model provider, IdP, upstream MCP servers |
Gateway routes by listener
| Listener | Default port | Routes |
|---|---|---|
Data (GATEWAY_DATA_HOST, GATEWAY_DATA_PORT) | 8787 | POST /v1/messages, POST /mcp, GET /health; anything else is refused before authentication |
Control (GATEWAY_CONTROL_HOST or GATEWAY_CONTROL_BIND_CIDR, GATEWAY_CONTROL_PORT) | 8788 | POST /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
| Name | Kind | Defined in |
|---|---|---|
agentforge-prod | Default TEMPORAL_NAMESPACE of api, session worker, exec worker, factory worker | the respective config.ts |
agentforge-quality | Default TEMPORAL_NAMESPACE of the quality exec worker | apps/worker/src/quality/exec-config.ts |
agentforge-sessions | SESSION_TASK_QUEUE | packages/agent-workflows/src/workflows/shared.ts |
agentforge-sessions-exec | execTaskQueue(SESSION_TASK_QUEUE), the fleet queue | same |
agentforge-sessions-exec-core | execCoreTaskQueue(...), the core fallback | same |
agentforge-factory | FACTORY_TASK_QUEUE | packages/agent-workflows/src/workflows/factory-shared.ts |
agentforge-quality | QUALITY_TASK_QUEUE | packages/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.tsapps/worker/src/worker.ts(runWorker),apps/worker/src/quality-exec-main.tspackages/agent-workflows/src/workflows/shared.ts,factory-shared.ts,quality-shared.tspackages/agent-core/src/config.tsdocs/deploy-quality.md,docs/deploy-sandbox.md,docs/design-worker-fleet.md,docs/design-gateway-fleet-exposure.md