> ## Documentation Index > Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```text theme={null} [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](/self-hosted-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 ```bash theme={null} 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= \ -e JWT_SECRET= \ -e NODE_ENV=production \ -e APP_URL=https://qodex.your-domain.com \ -v qodex-data:/data \ ghcr.io/flinket/qodeclaw:latest ``` ## Next steps Use the smallest working set of variables. Wire these variables into a one-host stack. Configure local disk, S3, or S3-compatible storage. Understand `QODECLAW_SECRET_KEY` before production.