Postgres password. Compose uses it to build DATABASE_URL; production has no fallback.
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 -dafter editing.env; usedocker compose psand 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_KEYcasually: 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.
No variable matches.
Required secrets and identity
Shared secret between the platform and sandbox controller. Generate 64 hex characters with openssl rand -hex 32.
64-hex root key that encrypts provider credentials at rest and stays outside the database.
Required when the deployment is reachable beyond loopback. It prevents the first visitor from claiming the administrator account.
Emergency opt-out that permits the insecure database-stored master key when CAPKA_MASTER_KEY is absent. Do not use in production.
Needed only when the app runs outside the provided Compose stack; use a PostgreSQL connection URL.
Canonical public origin without a trailing slash. Set it explicitly behind a production proxy for auth callbacks and absolute links.
Deployment, routing, and TLS
Published release tag used by platform, controller, and sandbox images. Pin a tag for deliberate upgrades.
Host port that publishes the platform container.
Host interface for the published port. Use 127.0.0.1 when a reverse proxy on the same host fronts Capka.
Domain passed to npm run up; enables the Caddy profile and automatic HTTPS.
Optional ACME account email. With DOMAIN, the install scripts can add ZeroSSL as a fallback issuer.
Override the host Docker socket path. Required when the stack drives a rootless Docker daemon.
Legacy alias for PUBLIC_URL. If both exist, PUBLIC_URL wins.
Sandbox isolation and access
Use runsc only after installing gVisor on the host. The secure profile fails closed if the runtime is missing.
Deployment-level network ceiling. Set false to forbid egress even if an administrator enables it in the UI.
Comma-separated HTTPS host allowlist. Supports exact hosts, *.example.com, and optional ports.
Internal subnet for allowlisted egress. Change only to resolve a host-route collision.
Fixed egress-proxy address; it must stay inside SANDBOX_EGRESS_SUBNET.
Colon-separated host roots that administrators may mount after enabling folder access. Recommended for multi-admin instances.
Sandbox resources and lifecycle
RAM per sandbox, including its tmpfs mounts. The controller's standalone fallback is 512 MB.
CPU cores per sandbox; fractional values such as 0.5 are accepted.
Maximum process/thread budget. Under gVisor it behaves like a high-water mark; values below about 128 can break rendering.
Concurrent running sandboxes per user; the least recently used session is evicted at the limit. Standalone fallback: 5.
Idle container stop delay: 15 minutes. Workspace files and the database row survive.
Lease renewed by a checked background job: 1 hour.
Maximum continuous busy hold from lease start: 6 hours.
Delete a workspace after 30 days without use.
Grace before deleting a directory with no database row: 7 days in Compose; standalone fallback is 1 hour.
Storage and retention
Root of the vault content-addressed blob store.
Days to keep completed, failed, and cancelled tasks. 0 keeps them indefinitely.
Days to keep finalized usage-ledger history. 0 keeps it indefinitely.
Days to keep governance audit events. 0 keeps them indefinitely.
Rows removed per bounded daily cleanup batch.
Background-job log directories kept per workspace; 0 keeps none.
Maximum size of one background-job log.
Rendered view_file directories kept per workspace; 0 keeps none.
Captured tool-output files kept per workspace; 0 keeps none.
Maximum size of one captured tool-output file.
Agent, streaming, and workers
Step at which a long tool loop must stop calling tools and write an answer; clamped to the step ceiling.
Hard tool-calling step ceiling for one turn.
Wall-clock ceiling for a turn, including tool calls.
Fraction of the time budget after which the agent stops starting tools and wraps up.
Character cap for one tool result.
Total tool-output character cap across one turn.
Line budget for one file read.
Silence before a model stream is treated as stalled; one retry receives twice this window.
Re-stream attempts after stalls or transient failures; 0 disables recovery.
Turns processed concurrently by the instance. There is no per-user fairness queue.
Platform Postgres pool size. Keep it comfortably above worker concurrency.
Set false only for an OpenAI-compatible gateway that breaks when stream usage is requested.
MCP connectors
Largest MCP media payload kept inline; 0 always spills media to a file.
Maximum description length for one MCP tool.
Comma-separated connector names whose tools load eagerly instead of behind find_tool.
Context-window percentage that triggers deferred connector schemas.
Absolute token cap for always-loaded connector schemas; 0 restores percentage-only gating.
Tracing and telemetry
OTLP HTTP endpoint. Unset keeps agent tracing off with no exporter overhead.
Comma-separated OTLP request headers, for example a backend authorization header.
Service name attached to exported spans.
Includes prompts, completions, tool arguments, results, and sandbox commands. This can expose user work.
Second explicit gate required before content can be exported to a remote host.
Exports estimated USD cost; the internal usage ledger remains Capka's accounting source of truth.
Span-name prefixes to export; * exports every span, including framework spans.
Additional exact attribute keys or prefix forms allowed through the export allowlist.
Optional product features
Allows users to import a public claude.ai or chatgpt.com share link into a chat.