Environment variables¶
Copy .env.example to .env (Docker Compose / checkout) or set the same keys during keprix setup (CLI). Never commit .env.
Install minimum (CLI and Docker)¶
Set at least one of OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY before first useful agent run.
| Variable | Purpose | Default / notes |
|---|---|---|
KEPRIX_HOME | CLI data/config/state home (curl installer) | $HOME/.keprix when unset |
OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY | LLM access (need one) | empty; set at least one |
AUTH_ENABLED | Require login for the web UI / API | true |
KEPRIX_MULTI_USER | Allow extra accounts beyond the bootstrap admin | false |
KEPRIX_ALLOWED_ORIGINS | Browser CORS origins (comma-separated) | http://localhost:3000 |
KEPRIX_INSTANCE_URL | Public HTTPS origin (links, Stripe returns, CORS companion) | http://localhost:3000 |
KEPRIX_JWT_SECRET / KEPRIX_SESSION_SECRET | Session secrets (required on public hosts) | replace GENERATE_RANDOM_* via scripts/generate-production-env.sh |
Docker also needs strong POSTGRES_PASSWORD / REDIS_PASSWORD (no changeme / placeholder values on a public host). See Quickstart and First run.
Full reference (from .env.example)¶
Regenerated at docs build time. Empty defaults are optional unless noted in Install minimum above.
| Variable | Description | Default | Required |
|---|---|---|---|
KEPRIX_HOME | CLI data/config/state home (curl installer; see Install minimum) | $HOME/.keprix | no |
KEPRIX_VERSION | Product | 0.16.0 | no |
KEPRIX_DEVELOPER_MODE | Do not set manually. | false | no |
KEPRIX_DEFAULT_PROVIDER | Minimum for first run: set at least one of OPENAI_API_KEY, ANTHROPIC_API_KEY, or GEMINI_API_KEY | auto | no |
KEPRIX_CODEBASE_AWARENESS | Web chat: inject read-only codebase map + docs into the system prompt (true/false). | true | no |
KEPRIX_SELF_KNOWLEDGE_BOOTSTRAP | Indexed under user_id keprix_self (override with KEPRIX_SELF_KNOWLEDGE_USER_ID). | true | no |
KEPRIX_AUTO_MCP_SPAWN | When unset, falls back to mcp.auto_spawn_enabled in config.yaml (toggle via /admin/mcp). | false | no |
OPENAI_API_KEY | LLM Providers | (empty) | no |
ANTHROPIC_API_KEY | LLM Providers | (empty) | no |
DEEPSEEK_API_KEY | LLM Providers | (empty) | no |
GROQ_API_KEY | LLM Providers | (empty) | no |
OPENROUTER_API_KEY | LLM Providers | (empty) | no |
TOGETHER_API_KEY | LLM Providers | (empty) | no |
MISTRAL_API_KEY | LLM Providers | (empty) | no |
GEMINI_API_KEY | LLM Providers | (empty) | no |
GOOGLE_API_KEY | LLM Providers | (empty) | no |
OLLAMA_BASE_URL | LLM Providers | http://host.docker.internal:11434/v1 | no |
LM_STUDIO_URL | LLM Providers | http://host.docker.internal:1234/v1 | no |
CUSTOM_LLM_BASE_URL | LLM Providers | (empty) | no |
CUSTOM_LLM_API_KEY | LLM Providers | (empty) | no |
KEPRIX_DATABASE_URL | bash scripts/generate-production-env.sh | postgresql+asyncpg://keprix:REPLACE_ME_POSTGRES@localhost:5432/keprix | no |
POSTGRES_PASSWORD | AWS_SNS_TOPIC_ARN= | REPLACE_ME_POSTGRES | no |
POSTGRES_BIND | Optional ESP (leave empty unless configured; never invent secrets) | 127.0.0.1 | no |
POSTGRES_HOST_PORT | Optional ESP (leave empty unless configured; never invent secrets) | 5432 | no |
KEPRIX_REDIS_URL | Redis Cache | redis://:REPLACE_ME_REDIS@localhost:6379 | no |
REDIS_PASSWORD | Redis Cache | REPLACE_ME_REDIS | no |
REDIS_BIND | Redis Cache | 127.0.0.1 | no |
REDIS_HOST_PORT | Redis Cache | 6379 | no |
SEARXNG_BIND | Then set SEARXNG_URL in Settings -> Web search (or here for non-UI setups). | 127.0.0.1 | no |
SEARXNG_PORT | Web Search (SearXNG - self-hosted) | 8080 | no |
SEARXNG_URL | Web Search (SearXNG - self-hosted) | http://localhost:8080 | no |
KEPRIX_SEARXNG_URL | Web Search (SearXNG - self-hosted) | http://localhost:8080 | no |
SEARXNG_API_TOKEN | Web Search (SearXNG - self-hosted) | (empty) | no |
SEARXNG_SECRET | Web Search (SearXNG - self-hosted) | (empty) | no |
KEPRIX_TENANT_HOME_ISOLATION | Enable per-tenant filesystem namespaces after tenant data cutover. | 0 | no |
BACKEND_BIND | Server Binding | 127.0.0.1 | no |
BACKEND_PORT | Server Binding | 3333 | no |
FRONTEND_BIND | Server Binding | 127.0.0.1 | no |
FRONTEND_PORT | Server Binding | 3000 | no |
AUTH_ENABLED | Auth on by default. Set false only for locked-down local/dev experiments. | true | no |
KEPRIX_MULTI_USER | Multi-user off by default (single-operator). Set true to allow additional accounts. | false | no |
KEPRIX_JWT_SECRET | Do not leave GENERATE_RANDOM_* or changeme values on a public host. | GENERATE_RANDOM_64_CHARS_HERE | no |
KEPRIX_SESSION_SECRET | Auth and Sessions | GENERATE_RANDOM_64_CHARS_HERE | no |
KEPRIX_TOTP_ISSUER | Auth and Sessions | Keprix | no |
KEPRIX_ALLOWED_ORIGINS | Comma-separated browser origins (include https://your.domain) | http://localhost:3000 | no |
KEPRIX_SESSION_TTL_DAYS | Comma-separated browser origins (include https://your.domain) | 7 | no |
KEPRIX_HANDOFF_SECRET | Shared HMAC secret for Carina Agent Studio -> Keprix Visual Playbook Studio handoff JWTs | GENERATE_RANDOM_32_CHARS_HERE | no |
CARINA_KEPRIX_SHARED_TOKEN | Shared bearer token for Carina/Aiva -> Keprix agent contract (POST /carina/agent/run) | (empty) | no |
KEPRIX_REQUIRE_2FA | CARINA_KEPRIX_FALLBACK_MODELS=openai:gpt-4.1-mini,openrouter:openrouter/auto | false | no |
KEPRIX_IP_HASH_SALT | Set automatically by keprix init if not present | (empty) | no |
KEPRIX_CSP_EXTRA | Set automatically by keprix init if not present | (empty) | no |
KEPRIX_REDACT_PRIVATE_IPS | Set automatically by keprix init if not present | false | no |
KEPRIX_AUDIT_FAIL_ON_HIGH | Set automatically by keprix init if not present | false | no |
KEPRIX_SHOW_ADMIN_PASSWORD | Never print admin password on shared hosts (install.sh honors this; default off) | 0 | no |
KEPRIX_TRUSTED_PROXIES | (Caddy/nginx on the same host: 127.0.0.1,::1; Cloudflare: use tunnel/origin IPs) | 127.0.0.1,::1 | no |
KEPRIX_LOG_LEVEL | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | info | no |
KEPRIX_SMTP_HOST | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | (empty) | no |
KEPRIX_SMTP_PORT | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | 587 | no |
KEPRIX_SMTP_USER | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | (empty) | no |
KEPRIX_SMTP_PASS | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | (empty) | no |
KEPRIX_EMAIL_FROM | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | (empty) | no |
KEPRIX_RESEND_API_KEY | Optional KEPRIX_ADMIN_EMAIL (example: [email protected]) | (empty) | no |
KEPRIX_CHROMADB_HOST | Memory and RAG | localhost | no |
KEPRIX_CHROMADB_PORT | Memory and RAG | 8100 | no |
KEPRIX_EMBEDDING_URL | Memory and RAG | (empty) | no |
KEPRIX_EMBEDDING_API_KEY | Memory and RAG | (empty) | no |
KEPRIX_EMBEDDING_MODEL | Memory and RAG | text-embedding-3-small | no |
KEPRIX_FASTEMBED_MODEL | Memory and RAG | sentence-transformers/all-MiniLM-L6-v2 | no |
KEPRIX_FASTEMBED_CACHE_PATH | Memory and RAG | (empty) | no |
KEPRIX_NOTION_TOKEN | Notion integration token for RAG ingestion (optional if using MCP OAuth only) | (empty) | no |
COMPANIES_HOUSE_API_KEY | Companies House Public Data API (search + company profiles) | (empty) | no |
KEPRIX_COMPANIES_HOUSE_ENABLED | Memory and RAG | 1 | no |
TELEGRAM_BOT_TOKEN | Messaging Channels | (empty) | no |
TELEGRAM_WEBHOOK_URL | Messaging Channels | (empty) | no |
DISCORD_BOT_TOKEN | Messaging Channels | (empty) | no |
DISCORD_APPLICATION_ID | Messaging Channels | (empty) | no |
KEPRIX_GOOGLE_CLIENT_ID | Calendar | (empty) | no |
KEPRIX_GOOGLE_CLIENT_SECRET | Calendar | (empty) | no |
KEPRIX_GOOGLE_REDIRECT_URI | Calendar | http://localhost:3000/oauth/google/callback | no |
KEPRIX_GWS_ENABLED | Google Workspace connector (OAuth desktop app, token stored outside repo) | 0 | no |
GOOGLE_WORKSPACE_CREDENTIALS_PATH | Calendar | (empty) | no |
GOOGLE_WORKSPACE_TOKEN_PATH | Calendar | (empty) | no |
GOOGLE_WORKSPACE_BRIDGE_CMD | Calendar | (empty) | no |
GOOGLE_WORKSPACE_USE_GWS_CLI | Calendar | 0 | no |
GOOGLE_WORKSPACE_SERVICE_ACCOUNT_MODE | Calendar | 0 | no |
KEPRIX_GITHUB_CLIENT_ID | Calendar | (empty) | no |
KEPRIX_GITHUB_CLIENT_SECRET | Calendar | (empty) | no |
KEPRIX_OIDC_CLIENT_ID | SYNCTHING_SYNC_PORT=22000 | (empty) | no |
KEPRIX_OIDC_CLIENT_SECRET | Syncthing Obsidian vault (optional bootstrap only) | (empty) | no |
KEPRIX_OIDC_ISSUER | Syncthing Obsidian vault (optional bootstrap only) | (empty) | no |
KEPRIX_OIDC_NAME | Syncthing Obsidian vault (optional bootstrap only) | (empty) | no |
KEPRIX_SSO_REDIRECT_URI | Syncthing Obsidian vault (optional bootstrap only) | http://localhost:3333/api/auth/sso/callback | no |
KEPRIX_FRONTEND_URL | Syncthing Obsidian vault (optional bootstrap only) | http://127.0.0.1:3000 | no |
KEPRIX_CALDAV_URL | Syncthing Obsidian vault (optional bootstrap only) | (empty) | no |
KEPRIX_CALDAV_USERNAME | Syncthing Obsidian vault (optional bootstrap only) | (empty) | no |
KEPRIX_CALDAV_PASSWORD | Syncthing Obsidian vault (optional bootstrap only) | (empty) | no |
KEPRIX_VAULT_KEY | Generate: openssl rand -base64 32 (or use scripts/generate-production-env.sh) | GENERATE_RANDOM_32_CHARS_HERE | no |
KEPRIX_MCP_ALLOWED_SERVERS | MCP | (empty) | no |
GRAPHITI_MCP_URL | Leave empty for built-in local Graphiti store, or set an external MCP URL. | (empty) | no |
KEPRIX_GRAPHITI_ENABLED | MCP | 1 | no |
KEPRIX_GOVERNANCE_ENABLED | Governance (optional; disabled by default) | false | no |
KEPRIX_GOVERNANCE_PROVIDER | Governance (optional; disabled by default) | native | no |
KEPRIX_GOVERNANCE_API_KEY | Governance (optional; disabled by default) | (empty) | no |
KEPRIX_GOVERNANCE_WORKSPACE_ID | Governance (optional; disabled by default) | (empty) | no |
KEPRIX_GOVERNANCE_ENDPOINT | Governance (optional; disabled by default) | (empty) | no |
KEPRIX_GOVERNANCE_TRACE_EXPORT | Governance (optional; disabled by default) | false | no |
SCOUT_ENABLED | Scout integration (optional; uses governance endpoint/key when unset) | false | no |
SCOUT_API_KEY | Scout integration (optional; uses governance endpoint/key when unset) | (empty) | no |
SCOUT_ENDPOINT | Scout integration (optional; uses governance endpoint/key when unset) | https://console.labyrinthscout.com | no |
SCOUT_API_URL | Scout integration (optional; uses governance endpoint/key when unset) | (empty) | no |
SCOUT_REDIS_URL | Scout integration (optional; uses governance endpoint/key when unset) | (empty) | no |
KEPRIX_SCOUT_PRODUCT | Scout integration (optional; uses governance endpoint/key when unset) | keprix | no |
KEPRIX_SCOUT_AGENT_ID | Aiva/Carina agent Scout hooks (K06) | (empty) | no |
KEPRIX_SCOUT_AGENT_ID_PREFIX | Aiva/Carina agent Scout hooks (K06) | keprix-aiva | no |
KEPRIX_SCOUT_KILL_TOKEN | Aiva/Carina agent Scout hooks (K06) | (empty) | no |
KEPRIX_SCOUT_STRICT | Aiva/Carina agent Scout hooks (K06) | false | no |
KEPRIX_SCOUT_TOOL_BURST_LIMIT | Aiva/Carina agent Scout hooks (K06) | 40 | no |
KEPRIX_SCOUT_WARDEN_ENABLED | Aiva/Carina agent Scout hooks (K06) | 0 | no |
KEPRIX_SCOUT_WARDEN_URL | Aiva/Carina agent Scout hooks (K06) | (empty) | no |
KEPRIX_SCOUT_WARDEN_TOKEN | Aiva/Carina agent Scout hooks (K06) | (empty) | no |
CHANNEL_SHIELD_ENABLED | Channel Shield (shared inbound protection; optional) | false | no |
CHANNEL_SHIELD_SMTP_HOST | Channel Shield (shared inbound protection; optional) | 0.0.0.0 | no |
CHANNEL_SHIELD_SMTP_PORT | Channel Shield (shared inbound protection; optional) | 2525 | no |
CHANNEL_SHIELD_CLAMAV_SOCKET | Channel Shield (shared inbound protection; optional) | (empty) | no |
CHANNEL_SHIELD_YARA_RULES_DIR | Channel Shield (shared inbound protection; optional) | (empty) | no |
CHANNEL_SHIELD_WEB_ORIGINS | Channel Shield (shared inbound protection; optional) | (empty) | no |
CHANNEL_SHIELD_WEB_EMBED_KEY | Channel Shield (shared inbound protection; optional) | (empty) | no |
KEPRIX_ACTIVE_EXTENSIONS | Comma-separated product extensions (e.g. scout) | (empty) | no |
KEPRIX_ENABLED_PRODUCTS | Comma-separated products built on Keprix (see config/products.example.yaml) | (empty) | no |
KEPRIX_GENERATED_TOOLS_DIR | Mutation Engine | /data/keprix/generated/tools | no |
KEPRIX_GENERATED_SKILLS_DIR | Mutation Engine | /data/keprix/generated/skills | no |
KEPRIX_MUTATION_ENABLED | Mutation Engine | true | no |
KEPRIX_SANDBOX_TIMEOUT | Mutation Engine | 30 | no |
KEPRIX_GAP_CONFIDENCE | Mutation Engine | 0.7 | no |
KEPRIX_MUTATION_ADMIN_CHANNEL | Mutation Engine | web | no |
KEPRIX_MUTATION_MAX_RETRIES | Mutation Engine | 2 | no |
KEPRIX_MUTATION_REQUIRED_CHANNELS | Mutation Engine | web_ui,telegram | no |
AIVA_PROVIDER | Aiva uses a low-latency model independently of the engineering agent default. | deepseek | no |
AIVA_MODEL | Mutation Engine | deepseek-v4-flash | no |
AIVA_DEEPSEEK_THINKING | Keep Flash in low-latency non-thinking mode. Enable only for complex Aiva work. | false | no |
AIVA_WORKSPACE_MODELS | strings or objects with provider and model keys. | {} | no |
KEPRIX_TOOL_SIGNING_KEY | Mutation Engine | /data/keprix/secrets/tool-signing-key.pem | no |
KEPRIX_TOOL_VERIFY_KEY | Mutation Engine | /data/keprix/secrets/tool-verify-key.pem | no |
KEPRIX_MUTATION_REQUIRE_APPROVAL | Mutation Engine | true | no |
KEPRIX_MUTATION_RATE_LIMIT | Mutation Engine | 10 | no |
KEPRIX_MUTATION_TOOL_SYNTHESIS | Mutation Engine | true | no |
KEPRIX_MUTATION_PROMPT_EVOLUTION | Mutation Engine | false | no |
KEPRIX_MUTATION_SELF_CODING | Mutation Engine | false | no |
KEPRIX_MUTATION_BRANCH_PREFIX | Mutation Engine | mutation/ | no |
KEPRIX_MUTATION_MERGE_STRATEGY | Mutation Engine | squash | no |
KEPRIX_MUTATION_REPO_ROOT | Mutation Engine | . | no |
KEPRIX_MUTATION_AUTO_APPROVE_THRESHOLD | Mutation Engine | 0.85 | no |
KEPRIX_MUTATION_SYNTHESIS_MIN_CONFIDENCE | Mutation Engine | 0.75 | no |
KEPRIX_MUTATION_REQUIRE_TESTS | Mutation Engine | true | no |
KEPRIX_MUTATION_RETENTION_DAYS | Mutation Engine | 365 | no |
KEPRIX_MUTATION_MAX_GENERATED_TOOLS | Mutation Engine | 200 | no |
KEPRIX_MUTATION_PRUNE_AFTER_DAYS | Mutation Engine | 90 | no |
KEPRIX_TELEMETRY | Anonymous usage telemetry (default off). Never sends conversation content or secrets. | false | no |
KEPRIX_BILLING_PROVIDER | Provider: stripe (requires STRIPE_SECRET_KEY) or mock mode (KEPRIX_BILLING_ENABLED true) | (empty) | no |
KEPRIX_BILLING_ENABLED | Billing (SaaS monetization) | false | no |
KEPRIX_BILLING_USE_EXAMPLE | Optional: KEPRIX_BILLING_CONFIG path to billing.yaml | false | no |
KEPRIX_BILLING_CURRENCY | Billing (SaaS monetization) | gbp | no |
KEPRIX_BILLING_TAX_DEFAULT | Billing (SaaS monetization) | 0.20 | no |
KEPRIX_BILLING_ALLOW_UNSIGNED_WEBHOOKS | Billing (SaaS monetization) | false | no |
STRIPE_SECRET_KEY | Billing (SaaS monetization) | (empty) | no |
STRIPE_WEBHOOK_SECRET | Billing (SaaS monetization) | (empty) | no |
STRIPE_TEST_MODE | Billing (SaaS monetization) | true | no |
KEPRIX_DATA_DIR | Data Directories | /data/keprix | no |
KEPRIX_LOGS_DIR | Data Directories | /data/keprix/logs | no |
KEPRIX_LLM_USAGE_ENABLED | LLM usage and cost tracking (Prompt 145) | true | no |
KEPRIX_LLM_USAGE_RETENTION_DAYS | LLM usage and cost tracking (Prompt 145) | 90 | no |
KEPRIX_LLM_USAGE_SQLITE_FALLBACK | LLM usage and cost tracking (Prompt 145) | true | no |
KEPRIX_CHAT_GATEWAY_STREAM | Route workspace /chat through the WEB_UI gateway stream (mutation + tools + LLM). | true | no |
KEPRIX_CHAT_MUTATION_SIDECAR | Legacy sidecar gap bridge (Prompt 139). Default off; agent loop hook handles mutation. | false | no |
KEPRIX_MUTATION_APPROVAL_TIMEOUT | Seconds to wait for mutation approval before ending a paused agent turn. | 3600 | no |
KEPRIX_MUTATION_STREAM_WAIT_APPROVAL | Keep /chat NDJSON stream open until mutation approve/reject (Prompt 28 parity). | true | no |
KEPRIX_MUTATION_LLM_TRIGGER | Optional LLM-only mutation trigger in addition to tool_miss (default off). | false | no |
KEPRIX_CHAT_UPLOAD_MAX_BYTES | Upload Limits (bytes) | 10485760 | no |
KEPRIX_DOCUMENT_UPLOAD_MAX_BYTES | Upload Limits (bytes) | 26214400 | no |
KEPRIX_AUDIO_UPLOAD_MAX_BYTES | Upload Limits (bytes) | 26214400 | no |
KEPRIX_NOTEBOOK_RESEARCH_ENABLED | Notebook research bridge (optional external sidecar; Quick Notebook is native) | true | no |
NOTEBOOKLM_BRIDGE_CMD | Upload Limits (bytes) | (empty) | no |
NOTEBOOKLM_MCP_URL | Upload Limits (bytes) | (empty) | no |
KEPRIX_DESIGN_PREVIEW_ENABLED | Design live preview | true | no |
KEPRIX_INSTANCE_URL | Public HTTPS origin (Stripe returns, links, CORS companion to KEPRIX_ALLOWED_ORIGINS) | http://localhost:3000 | no |