Skip to main content

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 after trim()), so VAR= behaves like a missing variable and takes the default.
  • Integers use int(min, default, max) (z.coerce.number().int()), money uses usd(default) (positive number).
  • Boolean switches differ by variable; the parse rule is given per row below. AGENTS_DISABLED is fail closed: any value other than 0 or false (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.

VariableRead byBehaviour
GATEWAY_CONTROL_TOKEN_API_FILEAPI (apps/api/src/runtime.ts)required; content trimmed; empty file is a startup error
GATEWAY_CONTROL_TOKEN_WORKER_FILEsession 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_FILEfactory workerexactly 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_CAapi, all worker rolesfile 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.

RoleRefusesError cites
APIANTHROPIC_API_KEY, GATEWAY_CONTROL_TOKEN_WORKER_FILEFL-CFG1
Session workerany GITHUB_APP_*, ANTHROPIC_API_KEYFX-CFG1, FL-CFG1
Exec workerDATABASE_URL, ANTHROPIC_API_KEY, any GATEWAY_CONTROL_*, any GITHUB_APP_*FL-3
Factory workerANTHROPIC_API_KEYFX-CFG1
Quality exec workerDATABASE_URL, ANTHROPIC_API_KEY, any GATEWAY_CONTROL_*, any GITHUB_APP_PUSH_*AC17
GatewayNODE_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=1plan 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.

VariableDefaultRule
API_KEYSnoneJSON 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_CLIENTSemptylist; each must be in API_KEYS
MODELSnonenon-empty list
DATABASE_URLnone
GATEWAY_URL, GATEWAY_CONTROL_URLnoneURL, gateway URL rule
GATEWAY_CONTROL_TOKEN_API_FILEnonepath
GATEWAY_MAX_OUTPUT_TOKENS8192int at least 1
GATEWAY_HTTP_ALLOWED_HOSTSemptyexact hostnames
HOSTthe IPv4 any-address (all interfaces)
PORT30000 to 65535
TRUST_PROXY_HOPS00 to 5
MAX_CONCURRENCY2at least 1
RATE_LIMIT_PER_MIN30at least 1
AUTH_FAIL_LIMIT_PER_MIN10at least 1
SHUTDOWN_GRACE_MS8000at least 0
WORKSPACE_DIR/workspacemust be an existing directory
STALE_RESERVATION_SEC900at least 600
STALE_CHECK_INTERVAL_MS300000at least 1000
SSE_PING_MS15000at least 1000
AGENTS_DISABLEDenabledfail closed
ALERT_WEBHOOK_URLunsetURL
CLIENT_DAILY_LIMIT_USD1
GLOBAL_DAILY_LIMIT_USD2
PER_REQUEST_CAP_USD0.5
BUDGET_FLOOR_USD0.02
SONNET_MIN_RESERVATION_USD0.5
BUDGET_MARGIN0.2at least 0, below 1
SESSION_MAX_TURNS50at least 1
SESSION_IDLE_TIMEOUT_MS86400000at least 1000
SESSION_TURN_HEARTBEAT_TIMEOUT_MS30000at least 300
SESSION_TURN_HEARTBEAT_INTERVAL_MStimeout / 3 (floored)at least 100 and at most timeout / 3
SESSION_EXEC_SCHEDULE_TO_START_MS60000at least 1000
SESSION_MAX_OPEN_PER_CLIENT5at least 1
SESSION_RESIGNAL_AFTER_MS30000at least 0
TEMPORAL_ADDRESSunsetunset makes session routes answer 503; set requires TEMPORAL_PAYLOAD_KEYS and TEMPORAL_PAYLOAD_KEY_ID
TEMPORAL_NAMESPACEagentforge-prod
TEMPORAL_TASK_QUEUEagentforge-sessions
TEMPORAL_TLS_CERT, _KEY, _CA, _SERVER_NAMEunsetall three paths or none
TEMPORAL_CALL_TIMEOUT_MS5000at least 100
TEMPORAL_PAYLOAD_KEYS, TEMPORAL_PAYLOAD_KEY_IDunsetparsed by parsePayloadKeys
FACTORY_ENABLEDoffon only for 1 or true; needs FACTORY_REPOS; off means the routes are not registered (404)
FACTORY_REPOSemptylist of FactoryRepo
FACTORY_CLIENTS, FACTORY_APPROVERSemptyeach in API_KEYS
FACTORY_MAX_JOB_USD0.5positive, at most 2
FACTORY_MAX_ACTIVE_PER_CLIENT21 to 100
FACTORY_TASK_QUEUEagentforge-factory
QUALITY_ENABLEDoffon only for 1 or true; needs FACTORY_REPOS; off means 404
QUALITY_CLIENTSemptyeach in API_KEYS
QUALITY_DAILY_SANDBOX_SECONDS_PER_CLIENT14400at least 1
QUALITY_DAILY_SANDBOX_SECONDS_GLOBAL28800at least 1
QUALITY_CONCURRENCY1at least 1 (no upper bound in the API schema)
QUALITY_MAX_PENDING_PER_CLIENT41 to 100
QUALITY_PENDING_TTL_SEC86400at least 60
QUALITY_TEMPORAL_NAMESPACETEMPORAL_NAMESPACEif different, needs its own payload keys
QUALITY_TEMPORAL_PAYLOAD_KEYS, QUALITY_TEMPORAL_PAYLOAD_KEY_IDthe main keysboth 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.

VariableDefaultRule
GATEWAY_MAX_OUTPUT_TOKENS8192becomes CLAUDE_CODE_MAX_OUTPUT_TOKENS; must not exceed the gateway's GATEWAY_MAX_TOKENS_CAP
GATEWAY_HTTP_ALLOWED_HOSTSempty
WORKER_IDENTITYSDK default (pid@host)
WORKSPACE_DIR/workspaceexisting directory
SESSION_MAX_PROMPT_CHARS80000a longer rendered transcript fails the turn with agent_limit before the runtime
SESSION_TURN_HEARTBEAT_INTERVAL_MS10000at least 100; must equal the API's value
WORKER_CONCURRENCY2at least 1
WORKER_ALSO_EXECtrueone of true, false, 1, 0; also poll the fleet -exec queue
WORKER_SHUTDOWN_GRACE_MS5000
TEMPORAL_NAMESPACEagentforge-prod
TEMPORAL_TASK_QUEUEagentforge-sessions
TEMPORAL_TLS_*unsetall 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_USD2per session turn (owner decision 2026-11-13); the API's synchronous cap stays 0.5
QUALITY_ENABLEDfalseone of true, false, 1, 0; needs FACTORY_REPOS
QUALITY_CONCURRENCY1exactly 1 (min 1, max 1)
QUALITY_DAILY_SANDBOX_SECONDS_PER_CLIENT, _GLOBAL14400, 28800
FACTORY_REPOSemptylist of FactoryRepo
FACTORY_POLICY_DIRunset<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.

VariableDefaultRule
GATEWAY_MAX_OUTPUT_TOKENS8192
GATEWAY_HTTP_ALLOWED_HOSTSempty
WORKER_IDENTITY<hostname>-exec
WORKSPACE_DIR/workspaceexisting directory
SESSION_TURN_HEARTBEAT_INTERVAL_MS10000
WORKER_CONCURRENCY1
WORKER_SHUTDOWN_GRACE_MS5000
TEMPORAL_NAMESPACEagentforge-prod
TEMPORAL_TASK_QUEUEagentforge-sessions-exec
TEMPORAL_TLS_*unsetin 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.

VariableDefaultRule
TEMPORAL_NAMESPACE, TEMPORAL_TASK_QUEUEagentforge-prod, agentforge-factory
GLOBAL_DAILY_LIMIT_USD, CLIENT_DAILY_LIMIT_USD, PER_REQUEST_CAP_USD2, 1, 0.5PER_REQUEST_CAP_USD must be at least every role cap
SONNET_MIN_RESERVATION_USD0.05
BUDGET_MARGIN0.2
FACTORY_FORK_OWNERnone^[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_DIRnoneexisting directory
FACTORY_POLICY_DIRunseta repo without a file gets the default policy (factory.pr gate only)
FACTORY_MODELclaude-haiku-5-5full model id ^claude-[a-z0-9.-]{1,64}$, no aliases
FACTORY_ROLE_CAP_PLANNER_USD, _CODER_USD, _REVIEWER_USD0.1, 0.25, 0.1
FACTORY_STEP_FLOOR_USD0.02at most every role cap
FACTORY_STEP_TIMEOUT_MS60000060000 to 840000 (gateway token TTL is 900 s)
FACTORY_MAX_TURNS301 to 50
FACTORY_WORKSPACE_OUT_TIMEOUT_MS600001000 to 300000
FACTORY_HEARTBEAT_INTERVAL_MS, FACTORY_HEARTBEAT_TIMEOUT_MS10000, 30000interval at most timeout / 3
FACTORY_APPROVAL_TTL_MS259200000 (72 h)1000 to 604800000 (7 days)
FACTORY_CONCURRENCY21 to 8
SANDBOX_IMAGE, SANDBOX_GATEWAY_CONTAINER, SANDBOX_OWNERunsetmain refuses to start without them
SANDBOX_MAX_OUTPUT_TOKENS81921 to 128000
SANDBOX_RUNTIMEruncrunc or runsc; runc needs FACTORY_ALLOW_RUNC=throwaway-repo-only
SANDBOX_CONTROL_HOSTunsetIPv4; local shape (control calls through docker exec into the gateway container)
GATEWAY_CONTROL_URL, GATEWAY_CONTROL_TOKEN_WORKER_FILEunsetdirect shape
GITHUB_API_URL, GITHUB_GIT_URLhttps://api.github.com, https://github.comhttps or loopback http
GITHUB_APP_READ_PR_ID, GITHUB_APP_PUSH_IDnonedigits
GITHUB_APP_*_INSTALLATION_IDnonepositive int
GITHUB_APP_*_PRIVATE_KEY or _FILEnoneexactly 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.

VariableDefaultRule
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_NAMESPACEagentforge-qualityon 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_PLAINTEXTunsetas exec worker
QUALITY_PROD_PAYLOAD_KEY_IDunsetsee above
QUALITY_REPO_SOURCEnoneonly local:<absolute dir> (bare mirrors <dir>/<owner>/<name>.git); anything else throws GitHubSourceUnavailable (github_source_unavailable)
QUALITY_IMAGEnonedigest form only (SandboxImageRef)
QUALITY_RUNTIMErunscrunc needs QUALITY_ALLOW_RUNC=own-repo-only
QUALITY_WORK_DIR/var/lib/agentforge-qualityexisting directory
FACTORY_REPOS, FACTORY_POLICY_DIRempty, unsetrepos 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.

VariableDefaultRule
UPSTREAM_BASE_URLhttps://api.anthropic.commust equal the default unless GATEWAY_TEST_UPSTREAM=1 and NODE_ENV=test (then plain http to the IPv4 loopback with a port)
GATEWAY_MODELSnonenon-empty subset of the priced models (PRICED_MODELS)
GATEWAY_MAX_TOKENS_CAP8192
GATEWAY_ALLOWED_BETAS, GATEWAY_ALLOWED_FIELDScompiled defaultssubsets of the compiled known sets
GATEWAY_ALLOWED_QUERIESemptysubset of known queries
GATEWAY_MAX_BODY_BYTES8388608 (8 MiB)
GATEWAY_POLICY_DIR, GATEWAY_REGISTRY_DIRnoneloaded at startup; any error refuses to start; an empty registry dir is an empty registry
GATEWAY_IDP_TOKEN_URL, _CLIENT_ID, _CLIENT_SECRETunsetall three or none; https (loopback http only in test mode)
GATEWAY_MCP_TIMEOUT_MS60000100 to 60000
GATEWAY_DATA_HOSTnoneone explicit IP
GATEWAY_DATA_PORT8787
GATEWAY_CONTROL_HOSTnoneone 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_CIDRunsetIPv4 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_PORT8788
GATEWAY_CONTROL_TOKEN_API, GATEWAY_CONTROL_TOKEN_WORKERnoneat least 32 chars each, must differ
GATEWAY_PREAUTH_PER_SEC20
GATEWAY_JOB_CONCURRENCY4
GATEWAY_JOB_PER_MIN120
GATEWAY_GLOBAL_CONCURRENCY32
GATEWAY_HEADER_TIMEOUT_MS10000
GATEWAY_BODY_TIMEOUT_MS30000
GATEWAY_UPSTREAM_TIMEOUT_MS600000
GATEWAY_STREAM_IDLE_MS120000
GATEWAY_STREAM_TOTAL_MS900000
GATEWAY_MAX_JOBS1000
GATEWAY_CONTROL_PER_SEC60
GATEWAY_SHUTDOWN_GRACE_MS10000
GATEWAY_OVERHEAD_TOKENS2000

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.ts
  • apps/worker/src/env.ts (int, present, tlsConfig), apps/worker/src/config.ts (WorkerEnv, loadConfig), apps/worker/src/runtime.ts
  • apps/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.ts
  • packages/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