Environment variables
Bootstrap variables for .env and deployment profiles.
Environment variables control bootstrap-time concerns: how the control plane and runtime bind, where state lives, how auth is enforced, and which storage backends the stack talks to. Product configuration (providers, agents, secrets) lives behind the control plane and is not set here.
Where to set them
Set values in the .env file at the install directory root. The installer writes safe defaults on first boot. On VPS deployments, make sure the file is owned by the service user with permissions 0600.
Environment profile
| Variable | Default | Purpose |
|---|---|---|
| KODA_ENV | development | Set to production to refuse development auth modes and loopback-bootstrap at boot. |
| ALLOW_LOOPBACK_BOOTSTRAP | true (dev) | Allow 127.0.0.1 to skip the setup code during first-owner registration. Must be false in production. |
Control plane
| Variable | Default | Purpose |
|---|---|---|
| CONTROL_PLANE_ENABLED | true | Master toggle for the control-plane HTTP service. |
| CONTROL_PLANE_BIND | 127.0.0.1 | Address the control plane binds to. |
| CONTROL_PLANE_PORT | 8090 | Port the control plane listens on. |
| CONTROL_PLANE_AUTH_MODE | token | Auth mode. Use token in production. development and open are refused when KODA_ENV=production. |
| CONTROL_PLANE_API_TOKEN | — | Optional break-glass token for CLI access. Leave blank unless needed. |
| CONTROL_PLANE_MASTER_KEY_FILE | — | Path to a file containing the master encryption key used for secret storage. |
| CONTROL_PLANE_RATE_LIMIT | 120/min | General operator request bucket. |
| CONTROL_PLANE_OPERATOR_LOGIN_MAX_FAILURES | 5 | Failed logins before account lockout. |
| CONTROL_PLANE_OPERATOR_LOGIN_LOCKOUT_SECONDS | 900 | Seconds an account stays locked after hitting the failure cap. |
| CONTROL_PLANE_OPERATOR_PASSWORD_MIN_LENGTH | 12 | Minimum password length. You can only override upward. |
| CONTROL_PLANE_OPERATOR_SESSION_TTL_SECONDS | 604800 | Operator session lifetime in seconds (7 days). |
Web dashboard
| Variable | Default | Purpose |
|---|---|---|
| WEB_PORT | 3000 | Port the Next.js dashboard listens on. |
| WEB_OPERATOR_SESSION_SECRET | — | Required in production. 32+ random bytes used to seal the operator session cookie. |
| ALLOW_INSECURE_WEB_OPERATOR_SESSION_SECRET | false | Development-only escape hatch. Refused in production. |
| ALLOW_INSECURE_COOKIES | false | Development-only. Lets cookies skip the Secure flag. |
| RUNTIME_LOCAL_UI_TOKEN | — | Token the dashboard presents to the runtime when the two are on different origins. |
State & storage roots
| Variable | Default | Purpose |
|---|---|---|
| STATE_BACKEND | postgres | Durable state backend. Postgres is the supported default. |
| STATE_ROOT_DIR | /var/lib/koda/state | Root directory for container-local state (bootstrap files, caches). |
| RUNTIME_EPHEMERAL_ROOT | /var/lib/koda/runtime | Runtime scratch root. Cleaned up between tasks. |
| ARTIFACT_STORE_DIR | /var/lib/koda/artifacts | Local fallback artifact directory (ignored when S3 is available). |
| OBJECT_STORAGE_REQUIRED | true | Refuse to start if object storage is unavailable. |
Postgres
| Variable | Default | Purpose |
|---|---|---|
| KNOWLEDGE_V2_POSTGRES_DSN | — | Full Postgres DSN for knowledge, memory, runtime, and audit schemas. |
| KNOWLEDGE_V2_POSTGRES_SCHEMA | knowledge_v2 | Schema prefix. Override when sharing a cluster with other workloads. |
Object storage (S3-compatible)
| Variable | Default | Purpose |
|---|---|---|
| KNOWLEDGE_V2_STORAGE_MODE | primary | primary uses object storage as the source of truth; secondary mirrors from Postgres. |
| KNOWLEDGE_V2_S3_BUCKET | koda-objects | Bucket name. |
| KNOWLEDGE_V2_S3_PREFIX | koda | Object key prefix. |
| KNOWLEDGE_V2_S3_ENDPOINT_URL | http://seaweedfs:8333 | S3 endpoint. Point at AWS, MinIO, R2, or the bundled SeaweedFS. |
| KNOWLEDGE_V2_S3_REGION | us-east-1 | Region hint. Most S3-compatible backends ignore this; AWS requires it. |
| KNOWLEDGE_V2_S3_ACCESS_KEY_ID | — | Access key for the configured endpoint. |
| KNOWLEDGE_V2_S3_SECRET_ACCESS_KEY | — | Secret for the configured endpoint. |
Memory
| Variable | Default | Purpose |
|---|---|---|
| MEMORY_ENABLED | true | Global memory enablement. |
| MEMORY_EMBEDDING_MODEL | paraphrase-multilingual-MiniLM-L12-v2 | Sentence-transformer model used for memory embeddings. |
| MEMORY_MAX_RECALL | 25 | Maximum memories returned per recall. |
| MEMORY_RECALL_THRESHOLD | 0.25 | Minimum similarity for a memory to be recalled. |
| MEMORY_RECALL_TIMEOUT | 3.0 | Seconds the recall step is allowed to take before it's dropped (best-effort). |
| MEMORY_MAX_CONTEXT_TOKENS | 3500 | Token budget for the recall-assembled context. |
| MEMORY_RECENCY_HALF_LIFE_DAYS | 120 | Decay rate for time-based ranking. |
| MEMORY_MAX_PER_USER | 2000 | Retention cap before maintenance prunes least-important records. |
| MEMORY_SIMILARITY_DEDUP_THRESHOLD | 0.92 | Cosine threshold for deduplication during extraction. |
| MEMORY_EXTRACTION_PROVIDER | claude | Provider used for post-query memory extraction. |
| MEMORY_EXTRACTION_MODEL | claude-sonnet-4-6 | Model used for extraction. |
| MEMORY_MAINTENANCE_ENABLED | true | Run background maintenance (retention, embedding repair). |
| MEMORY_DIGEST_ENABLED | true | Run the daily digest job. |
Knowledge
| Variable | Default | Purpose |
|---|---|---|
| KNOWLEDGE_ENABLED | true | Global retrieval enablement. |
| KNOWLEDGE_MAX_RESULTS | 6 | Ranked hits returned per query. |
| KNOWLEDGE_RECALL_THRESHOLD | 0.35 | Minimum similarity for a chunk to be returned. |
| KNOWLEDGE_CONTEXT_MAX_TOKENS | 2200 | Token budget for the retrieval-assembled context. |
| KNOWLEDGE_RECALL_TIMEOUT | 2.0 | Seconds the retrieval step is allowed to take (best-effort). |
| KNOWLEDGE_V2_ENABLED | true | Toggle for the modern retrieval pipeline. |
| KNOWLEDGE_V2_MAX_GRAPH_HOPS | 3 | Entity-graph traversal depth during retrieval. |
Skills
| Variable | Default | Purpose |
|---|---|---|
| SKILLS_DIR | koda/skills | Directory the skill registry scans. Changed files are picked up automatically. |
Browser automation
| Variable | Default | Purpose |
|---|---|---|
| BROWSER_ALLOW_PRIVATE_NETWORK | false | Allow runtime browser sessions to reach internal/loopback destinations. Keep disabled unless explicitly needed. |
Next steps
- VPS deployment — the production checklist that pins the critical values above.
- Security — the full story around auth, sessions, cookies, and audit.