Skip to main content

​
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

VariableRequiredWhat it controls
DATABASE_URLYesPostgres connection string for product state.
OPENAI_API_KEYYesDefault LLM provider key when a project does not use BYOK.
QODECLAW_SECRET_KEYYesEncrypts BYOK keys, OAuth tokens, and sensitive auth credentials at rest.
JWT_SECRETYesSigns sessions and OAuth state values.
PORTNoHTTP 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.
VariableWhat it controls
NODE_ENVSet to production for production behavior.
APP_URLPublic base URL used in emails, callbacks, and OAuth redirects.
APP_VERSIONRelease identifier for logs and error reporting.
DATABASE_SSLForces Postgres SSL on or off.
DB_POOL_MAXMaximum Postgres pool size.
BUGSNAG_API_KEYEnables Bugsnag error reporting when set.

​
Storage

VariableWhat it controls
STORAGE_BACKENDlocal or s3. Production should use durable storage.
QODECLAW_STATE_DIRBase directory for local state. Defaults to /data in Docker.
STORAGE_LOCAL_DIRExplicit local artifact directory override.
S3_BUCKETS3 bucket for artifacts.
AWS_REGIONAWS region for S3.
AWS_ENDPOINT_URLEndpoint for S3-compatible services such as MinIO or R2.
AWS_ACCESS_KEY_IDAccess key for S3-compatible storage when not using IAM role credentials.
AWS_SECRET_ACCESS_KEYSecret key for S3-compatible storage when not using IAM role credentials.
See Storage backends before choosing local disk for production.

​
Model provider keys

VariableWhat it controls
OPENAI_API_KEYDefault OpenAI key. Required for platform fallback usage.
ANTHROPIC_API_KEYDefault Anthropic key for projects configured to use Anthropic.
GOOGLE_API_KEYDefault Google key for projects configured to use Google.
GEMINI_API_KEYAlternative Google key name used by some code paths.
Project-level BYOK keys can override the platform default for that project.

​
Model selection

VariableWhat it controls
QODECLAW_MODELDefault coordinator model.
QODECLAW_CRITIC_MODELScenario critic model.
QODECLAW_REFLECTOR_MODELPost-scan reflection model.
API_ASSERTION_PICKER_MODELAPI assertion picker model.
API_SCENARIO_REVIEW_MODELAPI scenario review model.
UI_ASSERTION_PICKER_MODELUI assertion picker model.
UI_INTENT_RECOVERY_MODELUI intent recovery model.
UI_SCENARIO_REVIEWER_MODELUI scenario review model.
Most deployments leave these unset and use the platform defaults.

​
Queue and concurrency

VariableWhat it controls
REDIS_URLEnables queue mode with BullMQ when set.
AGENT_WORKER_CONCURRENCYAgent worker concurrency in queue mode.
BROWSER_POOL_SIZENumber of concurrent Playwright browser sessions.
QODECLAW_TEST_RUN_CONCURRENCYMaximum concurrent test runs.
SCENARIO_ITERATION_CONCURRENCYScenario concurrency within a test run.
GITHUB_CLONE_CONCURRENCYConcurrent 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

VariableWhat it controls
SKIP_AUTHDisables auth for local development. Do not use in production.
PROJECT_NAMEName for the first auto-created project.
ORG_NAMEName for the first auto-created organization.
QODECLAW_PROJECT_DIROptional read-only source repo mount for agent context.

​
GitHub App

Set these when using GitHub PR review in a self-hosted deployment:
VariableWhat it controls
GITHUB_INTEGRATION_ENABLEDEnables the GitHub integration.
GITHUB_APP_IDGitHub App numeric id.
GITHUB_APP_SLUGGitHub App URL slug.
GITHUB_APP_CLIENT_IDGitHub App OAuth client id.
GITHUB_APP_CLIENT_SECRETGitHub App OAuth client secret.
GITHUB_APP_PRIVATE_KEY_PATHPath to the GitHub App PEM private key.
GITHUB_APP_PRIVATE_KEYInline PEM private key when a path is not practical.
GITHUB_APP_WEBHOOK_SECRETWebhook HMAC secret.
GITHUB_WEBHOOK_SECRETLegacy alias for the webhook secret.

​
Microsoft SSO

VariableWhat it controls
MICROSOFT_CLIENT_IDAzure app registration client id.
MICROSOFT_CLIENT_SECRETAzure app registration client secret.
MICROSOFT_REDIRECT_URIRedirect URI registered in Azure.

​
Email and notifications

VariableWhat it controls
SMTP_HOSTSMTP host.
SMTP_PORTSMTP port.
SMTP_USERSMTP username.
SMTP_PASSSMTP password.
SMTP_FROMSender address for Qodex emails.
OPS_SLACK_WEBHOOK_URLInternal operational Slack notifications. Leave blank locally.

​
Uploads, load runner, and Playwright

VariableWhat it controls
BLOB_UPLOAD_SECRETSigns internal local-storage upload URLs.
ATTACHMENT_SIGN_SECRETSigns chat attachment upload tokens.
LOAD_RUN_DISPATCHERDispatches load runs inline or through ECS.
LOAD_RUN_REGIONRegion tag for ECS-dispatched load runs.
LOAD_CALLBACK_SECRETSigns load-run callbacks.
PLAYWRIGHT_BROWSERS_PATHBrowser binary path inside the image.
PLAYWRIGHT_CHROMIUM_SANDBOXChromium 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.