Configuration reference

The gateway is configured entirely through environment variables — there is no config file and no command-line flags on the server binary. It reads them once at boot; changing one means restarting the process.

Generated, not hand-written

The table below is emitted by make -C gateway docs directly from the gateway’s config manifest (gateway/internal/config/reference.go). A CI check (make -C gateway check) fails if the gateway starts reading a new variable that isn’t documented here, so this reference can’t silently fall behind the code.

The two ZERKER_OIDC_* required variables have no default — the gateway refuses to start without them (see Install and Auth & multi-tenancy). Everything else has a safe default or a dev-only fallback; the Deployment, Postgres, and KMS & secrets pages cover the production-relevant ones in context.

Server

Variable	Required	Default	Description
ZERKER_ADDR	No	:8080	TCP address the gateway’s HTTP server listens on.

Storage

Variable	Required	Default	Description
ZERKER_DATABASE_URL or DATABASE_URL	No	—	PostgreSQL connection string (pgx DSN). When unset, the gateway falls back to a non-durable in-memory store — development only; all state is lost on restart. DATABASE_URL is honored as a fallback. Migrations are applied automatically on boot.

Authentication (OIDC)

Variable	Required	Default	Description
ZERKER_OIDC_ISSUER	Yes	—	OIDC issuer base URL used for provider discovery. The gateway refuses to start without it — there is no unauthenticated path to bring it up.
ZERKER_OIDC_AUDIENCE	Yes	—	Expected value of the JWT aud claim. The gateway refuses to start without it.
ZERKER_OIDC_TENANT_CLAIM	Yes	—	JWT claim carrying the tenant/client identifier. Provider-specific, so there is no default — the gateway refuses to start without it.
ZERKER_OIDC_USER_CLAIM	No	sub	JWT claim carrying the acting user’s subject. sub is the OIDC standard.
ZERKER_OIDC_SCOPE_CLAIM	No	scope	JWT claim carrying the token’s OAuth scopes (a space-separated string or a JSON array). Leave empty to disable scope extraction. scp is common on Microsoft/Auth0.

Action authorization

Variable	Required	Default	Description
ZERKER_REASON_BINARY	No	—	Path or executable name for the Reason CLI. When set, MCP tools/call requests must use the transactional exact-call authorization envelope, bind the verified mission principal/tenant/agent to the authenticated request, and MCP streaming is rejected; startup fails if the executable cannot be resolved. Each verification is capped at 1 MiB input, 64 KiB output, and two seconds. A request digest is consumed once durable invocation creation succeeds, even if the upstream later times out or fails. When unset, Reason enforcement is disabled.

Secrets & KMS

Variable	Required	Default	Description
ZERKER_KMS_KEY	No	—	Hex-encoded 32-byte (64 hex chars) master key for the local KMS provider, which envelope-encrypts stored credentials. When unset, a random ephemeral key is generated that does not survive a restart — never run production without setting it.

Local onboarding

Variable	Required	Default	Description
ZERKER_TOKEN	No	—	Bearer token used by zerker-onboard --observe-all. When unset, the command reads the file selected by --token-file, which defaults to /tmp/zerker-dev-token. The token is never printed.

Trust receipts (Treeship)

Variable	Required	Default	Description
ZERKER_TREESHIP_BIN	No	—	Absolute path to the treeship binary. Setting it enables trust receipts: after each proxied invocation for an agent with receipts enabled, the gateway signs a Treeship action.v1 artifact binding that invocation’s ID, status and shape. Unset (the default) disables receipts entirely — no attestation is attempted and proxy behavior is unchanged. Emission is fail-open and off the request path, so an unreachable or broken binary never affects a proxied call.
ZERKER_TREESHIP_ACTOR	No	agent://zerker-gateway	Actor URI recorded as the signer of gateway trust receipts. Only read when ZERKER_TREESHIP_BIN is set.

Secrets (ZERKER_DATABASE_URL, ZERKER_KMS_KEY, and any provider credentials) should come from your platform’s secret store or an injected environment, never from a committed file — see KMS & secrets.