Payne configuration reference
Every variable on this page is server-only and must never use a NEXT_PUBLIC_
prefix. None is returned to the browser. Example-file values are local formatting
examples, not production-safe defaults.
| Variable | Applies to | Required when | Default | Secret | Boundary | Validation | Defined in |
|---|---|---|---|---|---|---|---|
| PAYNE_MODE | web, worker, build | production process | simulation in development; none in production | No | Server-only | simulation, local-live, or test | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_APP_VERSION | web, worker | never | none | No | Server-only | trimmed non-empty value when set | src/server/runtime-config-core.ts |
| PAYNE_WORKER_HEALTH_URL | web | when web should report worker reachability | none | No | Server-only | absolute HTTP(S) URL | src/server/runtime-config-core.ts, .env.example |
| PAYNE_WORKER_HOST | worker | never | 127.0.0.1 | No | Server-only | host string consumed by the Node listener | worker/index.ts, compose.local-live.yaml |
| PAYNE_WORKER_PORT | worker | never | 4310 | No | Server-only | base-10 integer consumed by the Node listener | worker/index.ts |
| PAYNE_DATAHUB_GMS_URL | local-live web and worker | PAYNE_MODE=local-live | none; Compose injects http://datahub-gms:8080 | No | Server-only | absolute HTTP(S) URL | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_DATAHUB_TOKEN | local-live web and worker | PAYNE_MODE=local-live | none | Yes | Server-only | trimmed non-empty token | src/server/runtime-config-core.ts, .env.local-live.example, compose.local-live.yaml |
| PAYNE_DATAHUB_WRITE_TOKEN | local-live worker | allowlisted DataHub write-back | none; Compose supplies the provisioned bootstrap token | Yes | Server-only | trimmed non-empty token when set | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_DATAHUB_MCP_COMMAND | local-live adapters | never | mcp-server-datahub | No | Server-only | trimmed executable name | src/server/runtime-config-core.ts |
| PAYNE_BOOTSTRAP_STATUS_PATH | local-live web and worker | PAYNE_MODE=local-live | none; Compose injects /var/run/payne/bootstrap-status.json | No | Server-only | trimmed non-empty path | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_BOOTSTRAP_DATAHUB_TOKEN | local-live provisioning | after the application token is provisioned | none | Yes | Server-only | token written by the provisioning script | scripts/local-live-provision-token.mjs, .env.local-live.example, compose.local-live.yaml |
| PAYNE_DATABASE_URL | local-live web and worker | PAYNE_MODE=local-live | none; Compose constructs it | Yes | Server-only | postgres: or postgresql: URL | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_MIGRATION_DATABASE_URL | database migrations | running migrations | none | Yes | Server-only | postgres: or postgresql: URL | src/server/runtime-config-core.ts, src/server/db/client.ts, compose.local-live.yaml |
| PAYNE_ARTIFACT_ROOT | local-live web and worker | artifact preparation or inspection | none; Compose sets /var/lib/payne/artifacts | No | Server-only | absolute path without NUL bytes | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_SANDBOX_ROOT | local-live web and worker | official sandbox application | none; Compose sets /var/lib/payne/sandbox | No | Server-only | absolute path without NUL bytes | src/server/runtime-config-core.ts, compose.local-live.yaml |
| PAYNE_INFERENCE_PROVIDER | local-live web and worker | bounded inference is enabled | none | No | Server-only | gemini or ollama | src/server/runtime-config-core.ts, .env.local-live.example |
| PAYNE_INFERENCE_MODEL | local-live web and worker | PAYNE_INFERENCE_PROVIDER is set | none | No | Server-only | 1–200 characters matching the supported model-identifier pattern | src/server/runtime-config-core.ts, .env.local-live.example |
| GEMINI_API_KEY | Gemini inference | provider is gemini and a model is configured | none | Yes | Server-only | trimmed non-empty credential | src/server/runtime-config-core.ts, .env.local-live.example |
| PAYNE_OLLAMA_BASE_URL | Ollama inference | never | http://127.0.0.1:11434; Compose uses the host bridge | No | Server-only | absolute HTTP(S) URL | src/server/runtime-config-core.ts, .env.local-live.example, compose.local-live.yaml |
| PAYNE_AGENT_MAX_STEPS | inference | never | 6 | No | Server-only | integer from 1 through 10 | src/server/runtime-config-core.ts, src/domain/agent.ts |
| PAYNE_AGENT_MAX_WALL_TIME_MS | inference | never | 90000 | No | Server-only | integer from 1000 through 120000 | src/server/runtime-config-core.ts, src/domain/agent.ts |
| PAYNE_AGENT_MAX_INPUT_TOKENS | inference | never | 16000 | No | Server-only | integer from 1000 through 32000 | src/server/runtime-config-core.ts, src/domain/agent.ts, .env.local-live.example |
| PAYNE_AGENT_MAX_OUTPUT_TOKENS | inference | never | 4000 | No | Server-only | integer from 256 through 8000 | src/server/runtime-config-core.ts, src/domain/agent.ts |
| PAYNE_AGENT_MAX_TOOL_RESULT_BYTES | inference | never | 65536 | No | Server-only | integer from 1024 through 131072 | src/server/runtime-config-core.ts, src/domain/agent.ts |
| PAYNE_AGENT_MAX_TOOL_CALLS | inference | never | 20 | No | Server-only | integer from 1 through 40 | src/server/runtime-config-core.ts, src/domain/agent.ts |
| PAYNE_TEST_DATABASE_URL | PostgreSQL integration tests | running pnpm test:integration | none | Yes | Server-only | PostgreSQL connection URL used by tests | src/server/shutdown-gates/module5-postgres.integration.test.ts |
| DATAHUB_BOOTSTRAP_USERNAME | local-live provisioning | minting local DataHub tokens | none; example uses datahub | No | Server-only | non-empty native local account name | scripts/local-live-provision-token.mjs, .env.local-live.example |
| DATAHUB_BOOTSTRAP_PASSWORD | local-live provisioning | minting local DataHub tokens | none | Yes | Server-only | non-empty native local account password | scripts/local-live-provision-token.mjs, .env.local-live.example |
| PAYNE_POSTGRES_PASSWORD | local-live Compose | starting local-live | none | Yes | Server-only | required by Compose interpolation | .env.local-live.example, compose.local-live.yaml |
| PAYNE_APP_DATABASE_PASSWORD | local-live Compose | starting local-live | none | Yes | Server-only | required by Compose interpolation | .env.local-live.example, compose.local-live.yaml |
| DATAHUB_MYSQL_PASSWORD | local DataHub Compose | starting local-live | none | Yes | Server-only | required by Compose interpolation | .env.local-live.example, compose.local-live.yaml |
| DATAHUB_MYSQL_ROOT_PASSWORD | local DataHub Compose | starting local-live | none | Yes | Server-only | required by Compose interpolation | .env.local-live.example, compose.local-live.yaml |
| DATAHUB_TOKEN_SERVICE_SIGNING_KEY | local DataHub Compose | starting local-live | none | Yes | Server-only | required by Compose interpolation; replace the example value | .env.local-live.example, compose.local-live.yaml |
| DATAHUB_TOKEN_SERVICE_SALT | local DataHub Compose | starting local-live | none | Yes | Server-only | required by Compose interpolation; replace the example value | .env.local-live.example, compose.local-live.yaml |
| DATAHUB_SECRET | local DataHub frontend | starting local-live | none | Yes | Server-only | required by Compose interpolation; replace the example value | .env.local-live.example, compose.local-live.yaml |
Definition ownership
PAYNE_* runtime parsing and validation are defined in
src/server/runtime-config-core.ts and src/server/runtime-config.ts. Worker
listener inputs are also consumed by worker/index.ts. Local DataHub,
PostgreSQL, bootstrap, and token-service inputs are wired by
compose.local-live.yaml; .env.local-live.example shows safe formatting only.
PAYNE_TEST_DATABASE_URL is consumed by the PostgreSQL integration tests.
Last updated on