Environment variables

Configure database access, model keys, storage, authentication, integrations, and runtime behavior for self-hosted Qodex.

Environment variables

Self-hosted Qodex reads configuration from environment variables at boot.

Use your platform’s secret mechanism for production: Docker Compose .env, ECS task secrets, Kubernetes Secrets, AWS Secrets Manager, Vault, Doppler, or another managed store. Do not bake secrets into the image.

The boot log reports whether critical variables are present, but it does not print their values.

[boot] env presence: REDIS_URL=true DATABASE_URL=true OPENAI_API_KEY=true JWT_SECRET=true S3_BUCKET=true BUGSNAG_API_KEY=true

Required for production

Variable	Required	What it controls
DATABASE_URL	Yes	Postgres connection string for product state.
OPENAI_API_KEY	Yes	Default LLM provider key when a project does not use BYOK.
QODECLAW_SECRET_KEY	Yes	Encrypts BYOK keys, OAuth tokens, and sensitive auth credentials at rest.
JWT_SECRET	Yes	Signs sessions and OAuth state values.
PORT	No	HTTP and WebSocket port. Defaults to 3000.

QODECLAW_SECRET_KEY must be at least 32 characters. Rotating it invalidates existing encrypted credentials unless you re-enter or re-encrypt them.

Recommended for production

Variable	What it controls
NODE_ENV	Set to production for production behavior.
APP_URL	Public base URL used in emails, callbacks, and OAuth redirects.
APP_VERSION	Release identifier for logs and error reporting.
DATABASE_SSL	Forces Postgres SSL on or off.
DB_POOL_MAX	Maximum Postgres pool size.
BUGSNAG_API_KEY	Enables Bugsnag error reporting when set.

Storage

Variable	What it controls
STORAGE_BACKEND	local or s3. Production should use durable storage.
QODECLAW_STATE_DIR	Base directory for local state. Defaults to /data in Docker.
STORAGE_LOCAL_DIR	Explicit local artifact directory override.
S3_BUCKET	S3 bucket for artifacts.
AWS_REGION	AWS region for S3.
AWS_ENDPOINT_URL	Endpoint for S3-compatible services such as MinIO or R2.
AWS_ACCESS_KEY_ID	Access key for S3-compatible storage when not using IAM role credentials.
AWS_SECRET_ACCESS_KEY	Secret key for S3-compatible storage when not using IAM role credentials.

See Storage backends before choosing local disk for production.

Model provider keys

Variable	What it controls
OPENAI_API_KEY	Default OpenAI key. Required for platform fallback usage.
ANTHROPIC_API_KEY	Default Anthropic key for projects configured to use Anthropic.
GOOGLE_API_KEY	Default Google key for projects configured to use Google.
GEMINI_API_KEY	Alternative Google key name used by some code paths.

Project-level BYOK keys can override the platform default for that project.

Model selection

Variable	What it controls
QODECLAW_MODEL	Default coordinator model.
QODECLAW_CRITIC_MODEL	Scenario critic model.
QODECLAW_REFLECTOR_MODEL	Post-scan reflection model.
API_ASSERTION_PICKER_MODEL	API assertion picker model.
API_SCENARIO_REVIEW_MODEL	API scenario review model.
UI_ASSERTION_PICKER_MODEL	UI assertion picker model.
UI_INTENT_RECOVERY_MODEL	UI intent recovery model.
UI_SCENARIO_REVIEWER_MODEL	UI scenario review model.

Most deployments leave these unset and use the platform defaults.

Queue and concurrency

Variable	What it controls
REDIS_URL	Enables queue mode with BullMQ when set.
AGENT_WORKER_CONCURRENCY	Agent worker concurrency in queue mode.
BROWSER_POOL_SIZE	Number of concurrent Playwright browser sessions.
QODECLAW_TEST_RUN_CONCURRENCY	Maximum concurrent test runs.
SCENARIO_ITERATION_CONCURRENCY	Scenario concurrency within a test run.
GITHUB_CLONE_CONCURRENCY	Concurrent repo clones for PR review.

Without REDIS_URL, Qodex runs scheduler and agent work in-process. That is fine for smaller deployments.

Authentication and workspace defaults

Variable	What it controls
SKIP_AUTH	Disables auth for local development. Do not use in production.
PROJECT_NAME	Name for the first auto-created project.
ORG_NAME	Name for the first auto-created organization.
QODECLAW_PROJECT_DIR	Optional read-only source repo mount for agent context.

GitHub App

Set these when using GitHub PR review in a self-hosted deployment:

Variable	What it controls
GITHUB_INTEGRATION_ENABLED	Enables the GitHub integration.
GITHUB_APP_ID	GitHub App numeric id.
GITHUB_APP_SLUG	GitHub App URL slug.
GITHUB_APP_CLIENT_ID	GitHub App OAuth client id.
GITHUB_APP_CLIENT_SECRET	GitHub App OAuth client secret.
GITHUB_APP_PRIVATE_KEY_PATH	Path to the GitHub App PEM private key.
GITHUB_APP_PRIVATE_KEY	Inline PEM private key when a path is not practical.
GITHUB_APP_WEBHOOK_SECRET	Webhook HMAC secret.
GITHUB_WEBHOOK_SECRET	Legacy alias for the webhook secret.

Microsoft SSO

Variable	What it controls
MICROSOFT_CLIENT_ID	Azure app registration client id.
MICROSOFT_CLIENT_SECRET	Azure app registration client secret.
MICROSOFT_REDIRECT_URI	Redirect URI registered in Azure.

Email and notifications

Variable	What it controls
SMTP_HOST	SMTP host.
SMTP_PORT	SMTP port.
SMTP_USER	SMTP username.
SMTP_PASS	SMTP password.
SMTP_FROM	Sender address for Qodex emails.
OPS_SLACK_WEBHOOK_URL	Internal operational Slack notifications. Leave blank locally.

Uploads, load runner, and Playwright

Variable	What it controls
BLOB_UPLOAD_SECRET	Signs internal local-storage upload URLs.
ATTACHMENT_SIGN_SECRET	Signs chat attachment upload tokens.
LOAD_RUN_DISPATCHER	Dispatches load runs inline or through ECS.
LOAD_RUN_REGION	Region tag for ECS-dispatched load runs.
LOAD_CALLBACK_SECRET	Signs load-run callbacks.
PLAYWRIGHT_BROWSERS_PATH	Browser binary path inside the image.
PLAYWRIGHT_CHROMIUM_SANDBOX	Chromium sandbox setting used by the Docker image.

Minimal Docker example

docker run -d \
  --name qodex \
  -p 3000:3000 \
  -e OPENAI_API_KEY=sk-... \
  -e DATABASE_URL=postgres://qodeclaw:password@db:5432/qodeclaw \
  -e QODECLAW_SECRET_KEY=<random-32-plus-chars> \
  -e JWT_SECRET=<random-string> \
  -e NODE_ENV=production \
  -e APP_URL=https://qodex.your-domain.com \
  -v qodex-data:/data \
  ghcr.io/flinket/qodeclaw:latest

Next steps

Single-container deploy

Use the smallest working set of variables.

Docker Compose

Wire these variables into a one-host stack.

Storage backends

Configure local disk, S3, or S3-compatible storage.

Secret management

Understand QODECLAW_SECRET_KEY before production.