Security model overview
AgentForge treats every model-driven component as untrusted and puts the controls outside it. Three facts carry most of the design:
- One key holder. The governance gateway (
apps/gateway) is the only process that holds the model provider key (ANTHROPIC_API_KEY). The api, the session worker, the factory worker and the exec worker refuse to start when that variable is set (FL-CFG1,FX-CFG1,FL-3). See Secrets and keys. - Per-turn job tokens. A runtime (the Claude CLI in a worker or in a sandbox container) authenticates to the
gateway only with a short-lived
afj_job token. The gateway mints it on its control listener, binds it to one ledger row and one compiled policy, and drops it on revoke, expiry or settlement. See Job tokens and policies. - Controls live outside the agent. The sandbox runner has no hook (with
Bashpresent a path hook confines nothing), so containment comes from the container contract (no network except a per-job link to the gateway, read-only root,--cap-drop ALL, non-root uid 10001) and from host-side validation of everything that comes back. See Sandbox.
Trust boundaries
Each arrow that crosses a subgraph is a boundary with its own check:
| Boundary | Credential | Enforced by | Page |
|---|---|---|---|
| Client to API | API key (configured by API_KEYS) | apps/api (see the runtime section) | REST API |
| API or worker to gateway control | route-scoped control token (min 32 chars), constant-time compare | apps/gateway/src/control.ts | Gateway |
| Runtime to gateway data | afj_ job token, hash lookup in memory | apps/gateway/src/proxy.ts authenticate | Gateway |
| Gateway to model provider | the real key, fixed upstream URL | apps/gateway/src/config.ts, proxy.ts step 9 | Gateway |
| Gateway to MCP servers | OBO-exchanged or service bearer, never the job token | apps/gateway/src/mcp/route.ts, mcp/upstream.ts | MCP registry |
| Worker to sandbox | argv contract, stdin job spec, 0600 env file | apps/worker/src/sandbox/contract.ts assertSafeArgv | Sandbox |
| Sandbox output to host | NDJSON caps, exit code, tar validation | sandbox-runtime.ts readEvents, extract.ts | Sandbox |
| Any process to Temporal | tailnet ACL; payloads AES-256-GCM | packages/agent-workflows/src/codec.ts | Secrets and keys |
Layers of defence for one model call
Fail-closed defaults
| Situation | Behaviour | Source |
|---|---|---|
No org policy in GATEWAY_POLICY_DIR | gateway refuses to start (PolicyError missing_org) | packages/agent-governance/src/loader.ts |
| Invalid policy or registry file | refuses to start, no partial policy | loader.ts in both packages |
| Kill switch read fails | treated as disabled (503 disabled) | proxy.ts step 2, mcp/route.ts |
| Ledger debit fails | 503 ledger_error, nothing sent upstream | proxy.ts step 8 |
| No IdP configured | every OBO exchange and service token is denied | apps/gateway/src/app.ts denyAll |
| Gateway restart | all registrations are lost (in memory only); callers re-register on retry | registrations.ts, plan 6.2 |
| Usage missing from a response | charged at the worst case | proxy.ts priced |
| Kill switch unreadable 3 times in a sandbox job | job ends as disabled | sandbox-runtime.ts KILL_SWITCH_MAX_ERRORS |
What is not built or not verified
- Real IdP. OBO exchange (RFC 8693) and client credentials are tested against a fake IdP only; real Zitadel
parameter names are UNVERIFIED (
apps/gateway/src/identity/token-exchanger.ts). - MCP registry in production. The org policy grants no tools (
tools.allow: []) and the registry directory is empty in the image, so no MCP tool reaches any catalog today. - Approval of
requireApprovaltools. Not implemented; such tools are never listed and every call is refused (M4). runsc(gVisor). Supported as--runtime runscin the argv contract but not available on the local OrbStack VM (probe 0m); the VPS probe is UNVERIFIED.- Control bind by CIDR.
GATEWAY_CONTROL_BIND_CIDRis onmain, not released or deployed (ADR 0008). - Temporal transport. Plaintext on the tailnet; the tailnet ACL is the only network control; payloads are encrypted at the application level (ADR 0003 of the 2026-11-13 session).
Read the rest of this section in order: Threat model, Gateway, Job tokens and policies, MCP registry, Sandbox, Secrets and keys.
Sources
apps/gateway/src/app.ts(buildGateway,denyAll),apps/gateway/src/serve.ts,apps/gateway/src/proxy.ts,apps/gateway/src/control.ts,apps/gateway/src/registrations.tsapps/worker/src/config.ts,apps/worker/src/exec-config.ts(EXEC_FORBIDDEN),apps/worker/src/factory/config.ts,apps/api/src/config.tsapps/worker/src/sandbox/contract.ts,apps/worker/src/sandbox/sandbox-runtime.ts,apps/sandbox-runner/src/runner.tspackages/agent-governance/src/loader.ts,packages/agent-workflows/src/codec.tsapps/gateway/policies/README.md,docs/design-gateway-fleet-exposure.md,docs/deploy-sandbox.mddocs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0001-all-model-calls-through-the-gateway.md,docs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0003-temporal-acl-only-and-baked-gateway-policy.md,docs/sessions/2026-11-16-codecrucible-and-gateway-cidr/adr/0008-gateway-control-bind-cidr.md