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.

Get started

Concepts

PR review

API testing

UI testing

Security testing

Run tests

Findings

Memory

Skills

Integrations

Self-hosted

Account

Environment variables

Environment variables

Required for production

Recommended for production

Storage

Model provider keys

Model selection

Queue and concurrency

Authentication and workspace defaults

GitHub App

Microsoft SSO

Email and notifications

Uploads, load runner, and Playwright

Minimal Docker example

Next steps

Single-container deploy

Docker Compose

Storage backends

Secret management

​Environment variables

​Required for production

​Recommended for production

​Storage

​Model provider keys

​Model selection

​Queue and concurrency

​Authentication and workspace defaults

​GitHub App

​Microsoft SSO

​Email and notifications

​Uploads, load runner, and Playwright

​Minimal Docker example

​Next steps

Single-container deploy

Docker Compose

Storage backends

Secret management

Environment variables

Required for production

Recommended for production

Storage

Model provider keys

Model selection

Queue and concurrency

Authentication and workspace defaults

GitHub App

Microsoft SSO

Email and notifications

Uploads, load runner, and Playwright

Minimal Docker example

Next steps