Skip to main content

Security model overview

AgentForge treats every model-driven component as untrusted and puts the controls outside it. Three facts carry most of the design:

  1. 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.
  2. 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.
  3. Controls live outside the agent. The sandbox runner has no hook (with Bash present 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:

BoundaryCredentialEnforced byPage
Client to APIAPI key (configured by API_KEYS)apps/api (see the runtime section)REST API
API or worker to gateway controlroute-scoped control token (min 32 chars), constant-time compareapps/gateway/src/control.tsGateway
Runtime to gateway dataafj_ job token, hash lookup in memoryapps/gateway/src/proxy.ts authenticateGateway
Gateway to model providerthe real key, fixed upstream URLapps/gateway/src/config.ts, proxy.ts step 9Gateway
Gateway to MCP serversOBO-exchanged or service bearer, never the job tokenapps/gateway/src/mcp/route.ts, mcp/upstream.tsMCP registry
Worker to sandboxargv contract, stdin job spec, 0600 env fileapps/worker/src/sandbox/contract.ts assertSafeArgvSandbox
Sandbox output to hostNDJSON caps, exit code, tar validationsandbox-runtime.ts readEvents, extract.tsSandbox
Any process to Temporaltailnet ACL; payloads AES-256-GCMpackages/agent-workflows/src/codec.tsSecrets and keys

Layers of defence for one model call​

Fail-closed defaults​

SituationBehaviourSource
No org policy in GATEWAY_POLICY_DIRgateway refuses to start (PolicyError missing_org)packages/agent-governance/src/loader.ts
Invalid policy or registry filerefuses to start, no partial policyloader.ts in both packages
Kill switch read failstreated as disabled (503 disabled)proxy.ts step 2, mcp/route.ts
Ledger debit fails503 ledger_error, nothing sent upstreamproxy.ts step 8
No IdP configuredevery OBO exchange and service token is deniedapps/gateway/src/app.ts denyAll
Gateway restartall registrations are lost (in memory only); callers re-register on retryregistrations.ts, plan 6.2
Usage missing from a responsecharged at the worst caseproxy.ts priced
Kill switch unreadable 3 times in a sandbox jobjob ends as disabledsandbox-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 requireApproval tools. Not implemented; such tools are never listed and every call is refused (M4).
  • runsc (gVisor). Supported as --runtime runsc in 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_CIDR is on main, 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.ts
  • apps/worker/src/config.ts, apps/worker/src/exec-config.ts (EXEC_FORBIDDEN), apps/worker/src/factory/config.ts, apps/api/src/config.ts
  • apps/worker/src/sandbox/contract.ts, apps/worker/src/sandbox/sandbox-runtime.ts, apps/sandbox-runner/src/runner.ts
  • packages/agent-governance/src/loader.ts, packages/agent-workflows/src/codec.ts
  • apps/gateway/policies/README.md, docs/design-gateway-fleet-exposure.md, docs/deploy-sandbox.md
  • docs/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