Capka Environment Variables

Use environment variables for deployment-level settings that should not live in the admin interface: root secrets, host routing, hard security ceilings, resource budgets, retention and observability.

Before editing .env

The supported self-host path is npm run up or scripts/up.sh. On first run it creates strong values for the required secrets and never overwrites values already present in .env. Local development through npm run docker:dev supplies loopback-only defaults and does not require copying the production file.

For a direct production docker compose up, Coolify or another orchestrator, set the required secrets yourself. Keep .env outside version control and store the same values in a password manager or secret store before the server becomes important.

Applying changes safely

Back up the database and persistent data before changing storage, retention or version settings.
Run docker compose up -d after editing .env; use docker compose ps and service logs to confirm a healthy restart.
Change one risk-sensitive group at a time: secrets, routing, sandbox security, then resource tuning.
Never rotate CAPKA_MASTER_KEY casually: it is the root key for encrypted provider credentials.

Effective values for the standard deployment follow docker-compose.yml. A component started outside Compose can occasionally have a different internal fallback.

Required secrets and identity

POSTGRES_PASSWORD Default: required

Postgres password. Compose uses it to build DATABASE_URL; production has no fallback.

CONTROLLER_SECRET Default: required

Shared secret between the platform and sandbox controller. Generate 64 hex characters with openssl rand -hex 32.

CAPKA_MASTER_KEY Default: required

64-hex root key that encrypts provider credentials at rest and stays outside the database.

SETUP_TOKEN Default: conditional

Required when the deployment is reachable beyond loopback. It prevents the first visitor from claiming the administrator account.

ALLOW_DB_MASTER_KEY Default: false

Emergency opt-out that permits the insecure database-stored master key when CAPKA_MASTER_KEY is absent. Do not use in production.

DATABASE_URL Default: Compose-generated

Needed only when the app runs outside the provided Compose stack; use a PostgreSQL connection URL.

PUBLIC_URL Default: request-derived

Canonical public origin without a trailing slash. Set it explicitly behind a production proxy for auth callbacks and absolute links.

Deployment, routing, and TLS

CAPKA_VERSION Default: latest

Published release tag used by platform, controller, and sandbox images. Pin a tag for deliberate upgrades.

PLATFORM_PORT Default: 3000

Host port that publishes the platform container.

PLATFORM_BIND Default: 0.0.0.0

Host interface for the published port. Use 127.0.0.1 when a reverse proxy on the same host fronts Capka.

DOMAIN Default: unset

Domain passed to npm run up; enables the Caddy profile and automatic HTTPS.

ACME_EMAIL Default: unset

Optional ACME account email. With DOMAIN, the install scripts can add ZeroSSL as a fallback issuer.

DOCKER_SOCKET Default: rootful socket

Override the host Docker socket path. Required when the stack drives a rootless Docker daemon.

BETTER_AUTH_URL Default: deprecated

Legacy alias for PUBLIC_URL. If both exist, PUBLIC_URL wins.

Sandbox isolation and access

SANDBOX_RUNTIME Default: runc

Use runsc only after installing gVisor on the host. The secure profile fails closed if the runtime is missing.

SANDBOX_ALLOW_NETWORK Default: true

Deployment-level network ceiling. Set false to forbid egress even if an administrator enables it in the UI.

SANDBOX_EGRESS_ALLOW Default: unset

Comma-separated HTTPS host allowlist. Supports exact hosts, *.example.com, and optional ports.

SANDBOX_EGRESS_SUBNET Default: 10.201.7.0/24

Internal subnet for allowlisted egress. Change only to resolve a host-route collision.

SANDBOX_EGRESS_PROXY_IP Default: 10.201.7.2

Fixed egress-proxy address; it must stay inside SANDBOX_EGRESS_SUBNET.

SANDBOX_MOUNT_ALLOW Default: unset

Colon-separated host roots that administrators may mount after enabling folder access. Recommended for multi-admin instances.

Sandbox resources and lifecycle

SANDBOX_MEMORY_MB Default: 1024 in Compose

RAM per sandbox, including its tmpfs mounts. The controller's standalone fallback is 512 MB.

SANDBOX_CPUS Default: 1.0

CPU cores per sandbox; fractional values such as 0.5 are accepted.

SANDBOX_PIDS_LIMIT Default: 1024

Maximum process/thread budget. Under gVisor it behaves like a high-water mark; values below about 128 can break rendering.

MAX_SESSIONS_PER_USER Default: 2 in Compose

Concurrent running sandboxes per user; the least recently used session is evicted at the limit. Standalone fallback: 5.

SANDBOX_IDLE_TTL_MS Default: 900000

Idle container stop delay: 15 minutes. Workspace files and the database row survive.

SANDBOX_BUSY_LEASE_MS Default: 3600000

Lease renewed by a checked background job: 1 hour.

SANDBOX_BUSY_MAX_MS Default: 21600000

Maximum continuous busy hold from lease start: 6 hours.

WORKSPACE_TTL_MS Default: 2592000000

Delete a workspace after 30 days without use.

GC_GRACE_MS Default: 604800000 in Compose

Grace before deleting a directory with no database row: 7 days in Compose; standalone fallback is 1 hour.

Storage and retention

VAULT_CAS_DIR Default: /app/data/vault-cas

Root of the vault content-addressed blob store.

TASK_RETENTION_DAYS Default: 30

Days to keep completed, failed, and cancelled tasks. 0 keeps them indefinitely.

USAGE_RETENTION_DAYS Default: 365

Days to keep finalized usage-ledger history. 0 keeps it indefinitely.

AUDIT_RETENTION_DAYS Default: 365

Days to keep governance audit events. 0 keeps them indefinitely.

DB_RETENTION_BATCH_SIZE Default: 1000

Rows removed per bounded daily cleanup batch.

JOBS_KEEP_DIRS Default: 20

Background-job log directories kept per workspace; 0 keeps none.

JOB_LOG_CAP_MB Default: 10

Maximum size of one background-job log.

VIEW_KEEP_DIRS Default: 4

Rendered view_file directories kept per workspace; 0 keeps none.

OUTPUT_KEEP_FILES Default: 5

Captured tool-output files kept per workspace; 0 keeps none.

OUTPUT_FILE_CAP_MB Default: 10

Maximum size of one captured tool-output file.

Agent, streaming, and workers

FORCE_TEXT_AFTER_STEPS Default: MAX_AGENT_STEPS − 5

Step at which a long tool loop must stop calling tools and write an answer; clamped to the step ceiling.

MAX_AGENT_STEPS Default: 25

Hard tool-calling step ceiling for one turn.

TASK_TIMEOUT_MINUTES Default: 20

Wall-clock ceiling for a turn, including tool calls.

WRAP_UP_AFTER_FRACTION Default: 0.8

Fraction of the time budget after which the agent stops starting tools and wraps up.

MAX_TOOL_OUTPUT_CHARS Default: 30000

Character cap for one tool result.

MAX_TURN_TOOL_OUTPUT_CHARS Default: 400000

Total tool-output character cap across one turn.

MAX_TOOL_OUTPUT_LINES Default: 1500

Line budget for one file read.

STREAM_IDLE_SECONDS Default: 60

Silence before a model stream is treated as stalled; one retry receives twice this window.

MAX_STREAM_RECOVERIES Default: 3

Re-stream attempts after stalls or transient failures; 0 disables recovery.

WORKER_MAX_CONCURRENCY Default: 3

Turns processed concurrently by the instance. There is no per-user fairness queue.

PG_POOL_MAX Default: 20

Platform Postgres pool size. Keep it comfortably above worker concurrency.

CAPKA_STREAM_USAGE Default: true

Set false only for an OpenAI-compatible gateway that breaks when stream usage is requested.

MCP connectors

MAX_MCP_MEDIA_BYTES Default: 5242880

Largest MCP media payload kept inline; 0 always spills media to a file.

MAX_MCP_TOOL_DESC_CHARS Default: 1024

Maximum description length for one MCP tool.

MCP_ALWAYS_LOAD Default: unset

Comma-separated connector names whose tools load eagerly instead of behind find_tool.

MCP_DEFER_TOKEN_PCT Default: 10

Context-window percentage that triggers deferred connector schemas.

MCP_DEFER_TOKEN_MAX Default: 8192

Absolute token cap for always-loaded connector schemas; 0 restores percentage-only gating.

Tracing and telemetry

OTEL_EXPORTER_OTLP_ENDPOINT Default: unset

OTLP HTTP endpoint. Unset keeps agent tracing off with no exporter overhead.

OTEL_EXPORTER_OTLP_HEADERS Default: unset

Comma-separated OTLP request headers, for example a backend authorization header.

OTEL_SERVICE_NAME Default: capka

Service name attached to exported spans.

CAPKA_TELEMETRY_CONTENT Default: false

Includes prompts, completions, tool arguments, results, and sandbox commands. This can expose user work.

CAPKA_TELEMETRY_CONTENT_REMOTE Default: false

Second explicit gate required before content can be exported to a remote host.

CAPKA_TELEMETRY_COST Default: false

Exports estimated USD cost; the internal usage ledger remains Capka's accounting source of truth.

CAPKA_TELEMETRY_SPAN_PREFIXES Default: capka.,ai.

Span-name prefixes to export; * exports every span, including framework spans.

CAPKA_TELEMETRY_EXTRA_ATTRIBUTES Default: unset

Additional exact attribute keys or prefix forms allowed through the export allowlist.

Optional product features

Capka source code · Full documentation for LLMs