Configuration
Every deployable reads its configuration from environment variables through a Zod schema in its own config.ts, and
fails fast: a parse error or a refused combination throws at startup, before any listener or Temporal worker
starts. agent-core itself never reads env; the apps map variables into AgentCoreConfig.
Rules shared by all parsers:
- Blank values count as unset (
present()drops values that are empty aftertrim()), soVAR=behaves like a missing variable and takes the default. - Integers use
int(min, default, max)(z.coerce.number().int()), money usesusd(default)(positive number). - Boolean switches differ by variable; the parse rule is given per row below.
AGENTS_DISABLEDis fail closed: any value other than0orfalse(case-insensitive) disables agents. - Lists are comma-separated, trimmed, blanks dropped.
The _FILE secret convention
Secrets that grant control or write access are passed as paths to mounted files, not as values. The deploy docs
specify mode 0400 files.
| Variable | Read by | Behaviour |
|---|---|---|
GATEWAY_CONTROL_TOKEN_API_FILE | API (apps/api/src/runtime.ts) | required; content trimmed; empty file is a startup error |
GATEWAY_CONTROL_TOKEN_WORKER_FILE | session worker (required), factory worker (direct control shape) | content trimmed; empty file is a startup error |
GITHUB_APP_READ_PR_PRIVATE_KEY_FILE, GITHUB_APP_PUSH_PRIVATE_KEY_FILE | factory worker | exactly one of the inline variable and its _FILE variant (appKey()), else set exactly one of X and X_FILE; production uses _FILE |
TEMPORAL_TLS_CERT, TEMPORAL_TLS_KEY, TEMPORAL_TLS_CA | api, all worker roles | file paths; all three or none (set all of TEMPORAL_TLS_CERT, TEMPORAL_TLS_KEY, TEMPORAL_TLS_CA or none); none means plaintext |
The gateway is the exception: it takes ANTHROPIC_API_KEY, GATEWAY_CONTROL_TOKEN_API and
GATEWAY_CONTROL_TOKEN_WORKER as values (each control token at least 32 characters, and the two must differ). How the
values reach the hosts is described in Secrets flow and Secrets and keys.
Refused variables
Each role refuses credentials it must never hold. The check runs on the present (non-blank) variable names before parsing.
| Role | Refuses | Error cites |
|---|---|---|
| API | ANTHROPIC_API_KEY, GATEWAY_CONTROL_TOKEN_WORKER_FILE | FL-CFG1 |
| Session worker | any GITHUB_APP_*, ANTHROPIC_API_KEY | FX-CFG1, FL-CFG1 |
| Exec worker | DATABASE_URL, ANTHROPIC_API_KEY, any GATEWAY_CONTROL_*, any GITHUB_APP_* | FL-3 |
| Factory worker | ANTHROPIC_API_KEY | FX-CFG1 |
| Quality exec worker | DATABASE_URL, ANTHROPIC_API_KEY, any GATEWAY_CONTROL_*, any GITHUB_APP_PUSH_* | AC17 |
| Gateway | NODE_TLS_REJECT_UNAUTHORIZED=0, any NODE_USE_ENV_PROXY; NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR unless GATEWAY_ALLOW_EXTRA_CA=1; NODE_OPTIONS unless GATEWAY_ALLOW_NODE_OPTIONS=1 | plan 6.1 (SSRF/MITM hardening) |
Gateway URL rule (L4, FL-4)
GATEWAY_URL and GATEWAY_CONTROL_URL (api, session worker, exec worker) pass assertSafeGatewayUrl: the URL must be
https:, or http: to a loopback host (the IPv4 loopback, localhost or [::1]) or a host in
GATEWAY_HTTP_ALLOWED_HOSTS.
GATEWAY_HTTP_ALLOWED_HOSTS is a comma list of exact hostnames (lowercased, ^[a-z0-9.-]+$, no wildcards), empty by
default, intended for an encrypted private overlay. The factory worker applies the stricter loopback-only rule to
GATEWAY_CONTROL_URL, GITHUB_API_URL and GITHUB_GIT_URL.
API (apps/api/src/config.ts)
Required, no default: API_KEYS, MODELS, DATABASE_URL, GATEWAY_URL, GATEWAY_CONTROL_URL,
GATEWAY_CONTROL_TOKEN_API_FILE.
| Variable | Default | Rule |
|---|---|---|
API_KEYS | none | JSON object client to key; client names ^[a-z0-9-]{1,64}$, keys at least 32 chars, at least one client, no duplicate key values |
API_ADMIN_CLIENTS | empty | list; each must be in API_KEYS |
MODELS | none | non-empty list |
DATABASE_URL | none | |
GATEWAY_URL, GATEWAY_CONTROL_URL | none | URL, gateway URL rule |
GATEWAY_CONTROL_TOKEN_API_FILE | none | path |
GATEWAY_MAX_OUTPUT_TOKENS | 8192 | int at least 1 |
GATEWAY_HTTP_ALLOWED_HOSTS | empty | exact hostnames |
HOST | the IPv4 any-address (all interfaces) | |
PORT | 3000 | 0 to 65535 |
TRUST_PROXY_HOPS | 0 | 0 to 5 |
MAX_CONCURRENCY | 2 | at least 1 |
RATE_LIMIT_PER_MIN | 30 | at least 1 |
AUTH_FAIL_LIMIT_PER_MIN | 10 | at least 1 |
SHUTDOWN_GRACE_MS | 8000 | at least 0 |
WORKSPACE_DIR | /workspace | must be an existing directory |
STALE_RESERVATION_SEC | 900 | at least 600 |
STALE_CHECK_INTERVAL_MS | 300000 | at least 1000 |
SSE_PING_MS | 15000 | at least 1000 |
AGENTS_DISABLED | enabled | fail closed |
ALERT_WEBHOOK_URL | unset | URL |
CLIENT_DAILY_LIMIT_USD | 1 | |
GLOBAL_DAILY_LIMIT_USD | 2 | |
PER_REQUEST_CAP_USD | 0.5 | |
BUDGET_FLOOR_USD | 0.02 | |
SONNET_MIN_RESERVATION_USD | 0.5 | |
BUDGET_MARGIN | 0.2 | at least 0, below 1 |
SESSION_MAX_TURNS | 50 | at least 1 |
SESSION_IDLE_TIMEOUT_MS | 86400000 | at least 1000 |
SESSION_TURN_HEARTBEAT_TIMEOUT_MS | 30000 | at least 300 |
SESSION_TURN_HEARTBEAT_INTERVAL_MS | timeout / 3 (floored) | at least 100 and at most timeout / 3 |
SESSION_EXEC_SCHEDULE_TO_START_MS | 60000 | at least 1000 |
SESSION_MAX_OPEN_PER_CLIENT | 5 | at least 1 |
SESSION_RESIGNAL_AFTER_MS | 30000 | at least 0 |
TEMPORAL_ADDRESS | unset | unset makes session routes answer 503; set requires TEMPORAL_PAYLOAD_KEYS and TEMPORAL_PAYLOAD_KEY_ID |
TEMPORAL_NAMESPACE | agentforge-prod | |
TEMPORAL_TASK_QUEUE | agentforge-sessions | |
TEMPORAL_TLS_CERT, _KEY, _CA, _SERVER_NAME | unset | all three paths or none |
TEMPORAL_CALL_TIMEOUT_MS | 5000 | at least 100 |
TEMPORAL_PAYLOAD_KEYS, TEMPORAL_PAYLOAD_KEY_ID | unset | parsed by parsePayloadKeys |
FACTORY_ENABLED | off | on only for 1 or true; needs FACTORY_REPOS; off means the routes are not registered (404) |
FACTORY_REPOS | empty | list of FactoryRepo |
FACTORY_CLIENTS, FACTORY_APPROVERS | empty | each in API_KEYS |
FACTORY_MAX_JOB_USD | 0.5 | positive, at most 2 |
FACTORY_MAX_ACTIVE_PER_CLIENT | 2 | 1 to 100 |
FACTORY_TASK_QUEUE | agentforge-factory | |
QUALITY_ENABLED | off | on only for 1 or true; needs FACTORY_REPOS; off means 404 |
QUALITY_CLIENTS | empty | each in API_KEYS |
QUALITY_DAILY_SANDBOX_SECONDS_PER_CLIENT | 14400 | at least 1 |
QUALITY_DAILY_SANDBOX_SECONDS_GLOBAL | 28800 | at least 1 |
QUALITY_CONCURRENCY | 1 | at least 1 (no upper bound in the API schema) |
QUALITY_MAX_PENDING_PER_CLIENT | 4 | 1 to 100 |
QUALITY_PENDING_TTL_SEC | 86400 | at least 60 |
QUALITY_TEMPORAL_NAMESPACE | TEMPORAL_NAMESPACE | if different, needs its own payload keys |
QUALITY_TEMPORAL_PAYLOAD_KEYS, QUALITY_TEMPORAL_PAYLOAD_KEY_ID | the main keys | both or neither; on a separate namespace the map must not hold the main TEMPORAL_PAYLOAD_KEY_ID |
node dist/migrate.js uses loadMigrateConfig, which reads only DATABASE_URL.
Session worker (apps/worker/src/config.ts)
Required: DATABASE_URL, GATEWAY_URL, GATEWAY_CONTROL_URL, GATEWAY_CONTROL_TOKEN_WORKER_FILE, TEMPORAL_ADDRESS,
TEMPORAL_PAYLOAD_KEYS, TEMPORAL_PAYLOAD_KEY_ID.
| Variable | Default | Rule |
|---|---|---|
GATEWAY_MAX_OUTPUT_TOKENS | 8192 | becomes CLAUDE_CODE_MAX_OUTPUT_TOKENS; must not exceed the gateway's GATEWAY_MAX_TOKENS_CAP |
GATEWAY_HTTP_ALLOWED_HOSTS | empty | |
WORKER_IDENTITY | SDK default (pid@host) | |
WORKSPACE_DIR | /workspace | existing directory |
SESSION_MAX_PROMPT_CHARS | 80000 | a longer rendered transcript fails the turn with agent_limit before the runtime |
SESSION_TURN_HEARTBEAT_INTERVAL_MS | 10000 | at least 100; must equal the API's value |
WORKER_CONCURRENCY | 2 | at least 1 |
WORKER_ALSO_EXEC | true | one of true, false, 1, 0; also poll the fleet -exec queue |
WORKER_SHUTDOWN_GRACE_MS | 5000 | |
TEMPORAL_NAMESPACE | agentforge-prod | |
TEMPORAL_TASK_QUEUE | agentforge-sessions | |
TEMPORAL_TLS_* | unset | all or none; plaintext in production only logs a warning |
AGENTS_DISABLED, ALERT_WEBHOOK_URL, CLIENT_DAILY_LIMIT_USD (1), GLOBAL_DAILY_LIMIT_USD (2), BUDGET_FLOOR_USD (0.02), SONNET_MIN_RESERVATION_USD (0.5), BUDGET_MARGIN (0.2) | as API | |
PER_REQUEST_CAP_USD | 2 | per session turn (owner decision 2026-11-13); the API's synchronous cap stays 0.5 |
QUALITY_ENABLED | false | one of true, false, 1, 0; needs FACTORY_REPOS |
QUALITY_CONCURRENCY | 1 | exactly 1 (min 1, max 1) |
QUALITY_DAILY_SANDBOX_SECONDS_PER_CLIENT, _GLOBAL | 14400, 28800 | |
FACTORY_REPOS | empty | list of FactoryRepo |
FACTORY_POLICY_DIR | unset | <dir>/<repo name>.json, strict FactoryRepoPolicy |
Exec worker (apps/worker/src/exec-config.ts)
Required: GATEWAY_URL, TEMPORAL_ADDRESS, TEMPORAL_PAYLOAD_KEYS, TEMPORAL_PAYLOAD_KEY_ID.
| Variable | Default | Rule |
|---|---|---|
GATEWAY_MAX_OUTPUT_TOKENS | 8192 | |
GATEWAY_HTTP_ALLOWED_HOSTS | empty | |
WORKER_IDENTITY | <hostname>-exec | |
WORKSPACE_DIR | /workspace | existing directory |
SESSION_TURN_HEARTBEAT_INTERVAL_MS | 10000 | |
WORKER_CONCURRENCY | 1 | |
WORKER_SHUTDOWN_GRACE_MS | 5000 | |
TEMPORAL_NAMESPACE | agentforge-prod | |
TEMPORAL_TASK_QUEUE | agentforge-sessions-exec | |
TEMPORAL_TLS_* | unset | in production, unset TLS throws unless TEMPORAL_ALLOW_PLAINTEXT=tailnet-only (the only accepted value) |
Factory worker (apps/worker/src/factory/config.ts)
Required: DATABASE_URL, TEMPORAL_ADDRESS, TEMPORAL_PAYLOAD_KEYS, TEMPORAL_PAYLOAD_KEY_ID, FACTORY_REPOS
(at least one), FACTORY_FORK_OWNER, FACTORY_WORK_DIR, GITHUB_APP_READ_PR_ID,
GITHUB_APP_READ_PR_INSTALLATION_ID, GITHUB_APP_PUSH_ID, GITHUB_APP_PUSH_INSTALLATION_ID, one key form per App.
| Variable | Default | Rule |
|---|---|---|
TEMPORAL_NAMESPACE, TEMPORAL_TASK_QUEUE | agentforge-prod, agentforge-factory | |
GLOBAL_DAILY_LIMIT_USD, CLIENT_DAILY_LIMIT_USD, PER_REQUEST_CAP_USD | 2, 1, 0.5 | PER_REQUEST_CAP_USD must be at least every role cap |
SONNET_MIN_RESERVATION_USD | 0.05 | |
BUDGET_MARGIN | 0.2 | |
FACTORY_FORK_OWNER | none | ^[A-Za-z0-9-]{1,39}$ |
FACTORY_FORK_SUFFIX | -fork | ^[A-Za-z0-9._-]{1,32}$; a fork may never equal an allowlisted base repo |
FACTORY_WORK_DIR | none | existing directory |
FACTORY_POLICY_DIR | unset | a repo without a file gets the default policy (factory.pr gate only) |
FACTORY_MODEL | claude-haiku-5-5 | full model id ^claude-[a-z0-9.-]{1,64}$, no aliases |
FACTORY_ROLE_CAP_PLANNER_USD, _CODER_USD, _REVIEWER_USD | 0.1, 0.25, 0.1 | |
FACTORY_STEP_FLOOR_USD | 0.02 | at most every role cap |
FACTORY_STEP_TIMEOUT_MS | 600000 | 60000 to 840000 (gateway token TTL is 900 s) |
FACTORY_MAX_TURNS | 30 | 1 to 50 |
FACTORY_WORKSPACE_OUT_TIMEOUT_MS | 60000 | 1000 to 300000 |
FACTORY_HEARTBEAT_INTERVAL_MS, FACTORY_HEARTBEAT_TIMEOUT_MS | 10000, 30000 | interval at most timeout / 3 |
FACTORY_APPROVAL_TTL_MS | 259200000 (72 h) | 1000 to 604800000 (7 days) |
FACTORY_CONCURRENCY | 2 | 1 to 8 |
SANDBOX_IMAGE, SANDBOX_GATEWAY_CONTAINER, SANDBOX_OWNER | unset | main refuses to start without them |
SANDBOX_MAX_OUTPUT_TOKENS | 8192 | 1 to 128000 |
SANDBOX_RUNTIME | runc | runc or runsc; runc needs FACTORY_ALLOW_RUNC=throwaway-repo-only |
SANDBOX_CONTROL_HOST | unset | IPv4; local shape (control calls through docker exec into the gateway container) |
GATEWAY_CONTROL_URL, GATEWAY_CONTROL_TOKEN_WORKER_FILE | unset | direct shape |
GITHUB_API_URL, GITHUB_GIT_URL | https://api.github.com, https://github.com | https or loopback http |
GITHUB_APP_READ_PR_ID, GITHUB_APP_PUSH_ID | none | digits |
GITHUB_APP_*_INSTALLATION_ID | none | positive int |
GITHUB_APP_*_PRIVATE_KEY or _FILE | none | exactly one per App |
Other startup checks: FACTORY_REPOS must not contain two repos with the same name (forks and policy files key on it).
The git version floor is checked in factory-main.ts. Details: Sandbox roles.
Quality exec worker (apps/worker/src/quality/exec-config.ts)
Required: TEMPORAL_ADDRESS, TEMPORAL_PAYLOAD_KEYS, TEMPORAL_PAYLOAD_KEY_ID, QUALITY_REPO_SOURCE, QUALITY_IMAGE,
and at least one FACTORY_REPOS entry with a policy that has quality in FACTORY_POLICY_DIR.
| Variable | Default | Rule |
|---|---|---|
WORKER_IDENTITY | <hostname>-exec | ^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,99}$; also the docker agentforge.owner label and the identity queue suffix |
TEMPORAL_NAMESPACE | agentforge-quality | on any namespace other than agentforge-prod, QUALITY_PROD_PAYLOAD_KEY_ID is required and the key map must not contain it |
TEMPORAL_TLS_*, TEMPORAL_ALLOW_PLAINTEXT | unset | as exec worker |
QUALITY_PROD_PAYLOAD_KEY_ID | unset | see above |
QUALITY_REPO_SOURCE | none | only local:<absolute dir> (bare mirrors <dir>/<owner>/<name>.git); anything else throws GitHubSourceUnavailable (github_source_unavailable) |
QUALITY_IMAGE | none | digest form only (SandboxImageRef) |
QUALITY_RUNTIME | runsc | runc needs QUALITY_ALLOW_RUNC=own-repo-only |
QUALITY_WORK_DIR | /var/lib/agentforge-quality | existing directory |
FACTORY_REPOS, FACTORY_POLICY_DIR | empty, unset | repos without a quality policy are not served |
Gateway (apps/gateway/src/config.ts)
Required: ANTHROPIC_API_KEY, DATABASE_URL, GATEWAY_MODELS, GATEWAY_POLICY_DIR, GATEWAY_REGISTRY_DIR,
GATEWAY_DATA_HOST, GATEWAY_CONTROL_HOST (or GATEWAY_CONTROL_BIND_CIDR), GATEWAY_CONTROL_TOKEN_API,
GATEWAY_CONTROL_TOKEN_WORKER.
| Variable | Default | Rule |
|---|---|---|
UPSTREAM_BASE_URL | https://api.anthropic.com | must equal the default unless GATEWAY_TEST_UPSTREAM=1 and NODE_ENV=test (then plain http to the IPv4 loopback with a port) |
GATEWAY_MODELS | none | non-empty subset of the priced models (PRICED_MODELS) |
GATEWAY_MAX_TOKENS_CAP | 8192 | |
GATEWAY_ALLOWED_BETAS, GATEWAY_ALLOWED_FIELDS | compiled defaults | subsets of the compiled known sets |
GATEWAY_ALLOWED_QUERIES | empty | subset of known queries |
GATEWAY_MAX_BODY_BYTES | 8388608 (8 MiB) | |
GATEWAY_POLICY_DIR, GATEWAY_REGISTRY_DIR | none | loaded at startup; any error refuses to start; an empty registry dir is an empty registry |
GATEWAY_IDP_TOKEN_URL, _CLIENT_ID, _CLIENT_SECRET | unset | all three or none; https (loopback http only in test mode) |
GATEWAY_MCP_TIMEOUT_MS | 60000 | 100 to 60000 |
GATEWAY_DATA_HOST | none | one explicit IP |
GATEWAY_DATA_PORT | 8787 | |
GATEWAY_CONTROL_HOST | none | one explicit IP, different from the data host; the IPv4 or IPv6 any-address only with GATEWAY_CONTROL_BIND_ANY=private-network-only (then the ports must differ) |
GATEWAY_CONTROL_BIND_CIDR | unset | IPv4 CIDR /8 to /32; derives the control host from exactly one matching local address; exclusive with GATEWAY_CONTROL_BIND_ANY and GATEWAY_CONTROL_HOST |
GATEWAY_CONTROL_PORT | 8788 | |
GATEWAY_CONTROL_TOKEN_API, GATEWAY_CONTROL_TOKEN_WORKER | none | at least 32 chars each, must differ |
GATEWAY_PREAUTH_PER_SEC | 20 | |
GATEWAY_JOB_CONCURRENCY | 4 | |
GATEWAY_JOB_PER_MIN | 120 | |
GATEWAY_GLOBAL_CONCURRENCY | 32 | |
GATEWAY_HEADER_TIMEOUT_MS | 10000 | |
GATEWAY_BODY_TIMEOUT_MS | 30000 | |
GATEWAY_UPSTREAM_TIMEOUT_MS | 600000 | |
GATEWAY_STREAM_IDLE_MS | 120000 | |
GATEWAY_STREAM_TOTAL_MS | 900000 | |
GATEWAY_MAX_JOBS | 1000 | |
GATEWAY_CONTROL_PER_SEC | 60 | |
GATEWAY_SHUTDOWN_GRACE_MS | 10000 | |
GATEWAY_OVERHEAD_TOKENS | 2000 |
Listener binding details: Gateway and docs/design-gateway-fleet-exposure.md.
Smoke harness (apps/smoke/src/config.ts)
Not a deployable, listed for completeness: DATABASE_URL and ANTHROPIC_API_KEY optional, RUN_REAL (1 enables a
real run), the P1 caps with the API defaults, SMOKE_CLIENT_CAP_USD (1) and SMOKE_GLOBAL_CAP_USD (2).
Sources
apps/api/src/config.ts(ApiEnv,loadConfig,loadMigrateConfig,tlsConfig),apps/api/src/runtime.tsapps/worker/src/env.ts(int,present,tlsConfig),apps/worker/src/config.ts(WorkerEnv,loadConfig),apps/worker/src/runtime.tsapps/worker/src/exec-config.ts(ExecEnv,EXEC_FORBIDDEN,loadExecConfig)apps/worker/src/factory/config.ts(FactoryEnv,appKey,loadPolicies,loadFactoryConfig)apps/worker/src/quality/exec-config.ts(QualityExecEnv,FORBIDDEN,parseRepoSource,loadQualityExecConfig)apps/gateway/src/config.ts(GatewayEnv,controlHostFromCidr,loadConfig)apps/smoke/src/config.tspackages/agent-types/src/gateway-control.ts(assertSafeGatewayUrl,parseHttpAllowedHosts)packages/agent-core/src/config.ts(AgentCoreConfig,DEFAULT_CONFIG)docs/deploy-api-coolify.md,docs/deploy-worker-coolify.md,docs/deploy-factory.md,docs/deploy-quality.md