Змінні середовища Capka

Змінні середовища призначені для deployment-рівня: root secrets, маршрутизації хоста, жорстких security-обмежень, ресурсів, retention та observability.

Перед редагуванням .env

Підтримуваний шлях self-hosting — npm run up або scripts/up.sh. Під час першого запуску скрипт створює сильні значення обов’язкових секретів і не перезаписує вже наявні значення в .env. Для локальної розробки npm run docker:dev дає loopback-only defaults без копіювання production-файла.

Для прямого production docker compose up, Coolify чи іншого orchestrator задайте обов’язкові секрети самостійно. Не додавайте .env у git; збережіть ті самі значення в password manager або secret store.

Безпечне застосування змін

Зробіть backup бази та постійних даних перед зміною storage, retention або version settings.
Після редагування .env виконайте docker compose up -d і перевірте docker compose ps та логи сервісів.
Змінюйте по одній ризиковій групі: secrets, routing, sandbox security, а вже потім resource tuning.
Не обертайте CAPKA_MASTER_KEY без окремого плану: це root key для зашифрованих ключів провайдерів.

Ефективні значення для стандартного розгортання наведені за docker-compose.yml. Якщо запускати компоненти окремо, їхні внутрішні fallback-и іноді відрізняються.

Обов'язкові секрети та адреса

POSTGRES_PASSWORD Типове значення: required

Пароль Postgres. Compose формує з нього DATABASE_URL; у production немає fallback.

CONTROLLER_SECRET Типове значення: required

Спільний секрет платформи й sandbox-controller. Згенеруйте 64 hex-символи через openssl rand -hex 32.

CAPKA_MASTER_KEY Типове значення: required

64-символьний hex-ключ для шифрування ключів провайдерів; він зберігається поза базою даних.

SETUP_TOKEN Типове значення: conditional

Обов'язковий для інстансу, доступного не лише з loopback. Не дає першому відвідувачу забрати обліковий запис адміністратора.

ALLOW_DB_MASTER_KEY Типове значення: false

Аварійний небезпечний fallback: дозволяє ключ у базі, якщо немає CAPKA_MASTER_KEY. Не використовуйте у production.

DATABASE_URL Типове значення: Compose-generated

Потрібний лише коли застосунок працює поза готовим Compose-стеком; значення — PostgreSQL connection URL.

PUBLIC_URL Типове значення: request-derived

Канонічний публічний origin без кінцевого /. За production proxy задайте явно для auth callback та абсолютних посилань.

Розгортання, маршрутизація та TLS

CAPKA_VERSION Типове значення: latest

Тег опублікованого релізу для platform, controller і sandbox images. Зафіксуйте тег для контрольованих оновлень.

PLATFORM_PORT Типове значення: 3000

Порт хоста, на якому публікується контейнер платформи.

PLATFORM_BIND Типове значення: 0.0.0.0

Інтерфейс для опублікованого порту. Використайте 127.0.0.1, якщо Capka стоїть за reverse proxy на тому самому хості.

DOMAIN Типове значення: unset

Домен для npm run up; вмикає Caddy-профіль та автоматичний HTTPS.

ACME_EMAIL Типове значення: unset

Необов'язковий email ACME. Разом із DOMAIN інсталятор може додати ZeroSSL як резервний issuer.

DOCKER_SOCKET Типове значення: rootful socket

Шлях до Docker socket на хості. Потрібен, коли стек використовує rootless Docker daemon.

BETTER_AUTH_URL Типове значення: deprecated

Застарілий alias для PUBLIC_URL. Якщо задані обидва, перемагає PUBLIC_URL.

Ізоляція та доступ пісочниці

SANDBOX_RUNTIME Типове значення: runc

Використовуйте runsc лише після встановлення gVisor на хості. Secure profile не запускається, якщо runtime відсутній.

SANDBOX_ALLOW_NETWORK Типове значення: true

Deployment-рівень дозволу мережі. false забороняє egress, навіть якщо адміністратор увімкне його в UI.

SANDBOX_EGRESS_ALLOW Типове значення: unset

Список дозволених HTTPS-хостів через кому. Підтримує точні хости, *.example.com та необов'язкові порти.

SANDBOX_EGRESS_SUBNET Типове значення: 10.201.7.0/24

Внутрішня підмережа allowlist-egress. Змінюйте лише при конфлікті з маршрутом хоста.

SANDBOX_EGRESS_PROXY_IP Типове значення: 10.201.7.2

Фіксована адреса egress-proxy; має належати до SANDBOX_EGRESS_SUBNET.

SANDBOX_MOUNT_ALLOW Типове значення: unset

Корені хоста через :, які адміністратори можуть монтувати після ввімкнення folder access. Рекомендовано для multi-admin інстансів.

Ресурси та життєвий цикл пісочниці

SANDBOX_MEMORY_MB Типове значення: 1024 in Compose

RAM на одну пісочницю разом із tmpfs. Внутрішній fallback controller поза Compose — 512 MB.

SANDBOX_CPUS Типове значення: 1.0

CPU cores на пісочницю; дозволені дробові значення, наприклад 0.5.

SANDBOX_PIDS_LIMIT Типове значення: 1024

Ліміт процесів і потоків. Під gVisor це high-water mark; значення нижче приблизно 128 можуть ламати rendering.

MAX_SESSIONS_PER_USER Типове значення: 2 in Compose

Одночасні запущені пісочниці на користувача; при ліміті витісняється LRU-сесія. Внутрішній fallback: 5.

SANDBOX_IDLE_TTL_MS Типове значення: 900000

Час до зупинки idle-контейнера: 15 хвилин. Файли workspace та запис у базі лишаються.

SANDBOX_BUSY_LEASE_MS Типове значення: 3600000

Lease, який оновлює активна фонова задача: 1 година.

SANDBOX_BUSY_MAX_MS Типове значення: 21600000

Максимальний busy-hold від початку lease: 6 годин.

WORKSPACE_TTL_MS Типове значення: 2592000000

Видалення workspace після 30 днів без використання.

GC_GRACE_MS Типове значення: 604800000 in Compose

Grace для каталогу без запису в базі: 7 днів у Compose; внутрішній fallback — 1 година.

Сховище та зберігання даних

VAULT_CAS_DIR Типове значення: /app/data/vault-cas

Корінь content-addressed blob store для vault.

TASK_RETENTION_DAYS Типове значення: 30

Дні зберігання завершених, помилкових і скасованих задач. 0 — безстроково.

USAGE_RETENTION_DAYS Типове значення: 365

Дні зберігання фіналізованої історії usage ledger. 0 — безстроково.

AUDIT_RETENTION_DAYS Типове значення: 365

Дні зберігання governance audit events. 0 — безстроково.

DB_RETENTION_BATCH_SIZE Типове значення: 1000

Кількість рядків у bounded batch щоденного очищення.

JOBS_KEEP_DIRS Типове значення: 20

Кількість каталогів логів фонових задач на workspace; 0 не зберігає жодного.

JOB_LOG_CAP_MB Типове значення: 10

Максимальний розмір одного логу фонової задачі.

VIEW_KEEP_DIRS Типове значення: 4

Кількість rendered-каталогів view_file на workspace; 0 не зберігає жодного.

OUTPUT_KEEP_FILES Типове значення: 5

Кількість збережених файлів tool output на workspace; 0 не зберігає жодного.

OUTPUT_FILE_CAP_MB Типове значення: 10

Максимальний розмір одного збереженого файла tool output.

Агент, streaming та workers

FORCE_TEXT_AFTER_STEPS Типове значення: MAX_AGENT_STEPS − 5

Крок, після якого довгий цикл припиняє tools і пише відповідь; обмежується загальним step ceiling.

MAX_AGENT_STEPS Типове значення: 25

Жорсткий ліміт tool-calling кроків одного turn.

TASK_TIMEOUT_MINUTES Типове значення: 20

Wall-clock ліміт одного turn разом із tool calls.

WRAP_UP_AFTER_FRACTION Типове значення: 0.8

Частка time budget, після якої агент перестає запускати tools і завершує відповідь.

MAX_TOOL_OUTPUT_CHARS Типове значення: 30000

Ліміт символів одного результату інструмента.

MAX_TURN_TOOL_OUTPUT_CHARS Типове значення: 400000

Сумарний ліміт символів tool output за один turn.

MAX_TOOL_OUTPUT_LINES Типове значення: 1500

Ліміт рядків для одного читання файла.

STREAM_IDLE_SECONDS Типове значення: 60

Тиша до визнання model stream завислим; одна повторна спроба отримує подвоєне вікно.

MAX_STREAM_RECOVERIES Типове значення: 3

Кількість повторних streaming-спроб після зависань; 0 вимикає recovery.

WORKER_MAX_CONCURRENCY Типове значення: 3

Кількість turn, які інстанс виконує одночасно. Per-user fairness queue немає.

PG_POOL_MAX Типове значення: 20

Розмір Postgres pool платформи. Він має бути помітно більшим за worker concurrency.

CAPKA_STREAM_USAGE Типове значення: true

Ставте false лише для OpenAI-сумісного gateway, який ламається від запиту stream usage.

MCP-конектори

MAX_MCP_MEDIA_BYTES Типове значення: 5242880

Найбільший MCP media payload inline; 0 завжди переносить media у файл.

MAX_MCP_TOOL_DESC_CHARS Типове значення: 1024

Максимальна довжина опису одного MCP tool.

MCP_ALWAYS_LOAD Типове значення: unset

Імена конекторів через кому, tools яких завжди завантажуються eagerly, а не через find_tool.

MCP_DEFER_TOKEN_PCT Типове значення: 10

Відсоток context window, після якого connector schemas відкладаються.

MCP_DEFER_TOKEN_MAX Типове значення: 8192

Абсолютний token cap для always-loaded connector schemas; 0 лишає тільки percentage gating.

Tracing і telemetry

OTEL_EXPORTER_OTLP_ENDPOINT Типове значення: unset

OTLP HTTP endpoint. Без значення agent tracing вимкнений і не має exporter overhead.

OTEL_EXPORTER_OTLP_HEADERS Типове значення: unset

OTLP request headers через кому, наприклад authorization header для backend.

OTEL_SERVICE_NAME Типове значення: capka

Назва сервісу в експортованих spans.

CAPKA_TELEMETRY_CONTENT Типове значення: false

Додає prompts, completions, tool arguments, results і sandbox commands. Це може розкрити роботу користувачів.

CAPKA_TELEMETRY_CONTENT_REMOTE Типове значення: false

Друга явна згода, без якої content не експортується на віддалений host.

CAPKA_TELEMETRY_COST Типове значення: false

Експортує оцінену вартість у USD; внутрішній usage ledger лишається джерелом фінансової правди.

CAPKA_TELEMETRY_SPAN_PREFIXES Типове значення: capka.,ai.

Префікси span names для експорту; * експортує всі spans, включно з framework spans.

CAPKA_TELEMETRY_EXTRA_ATTRIBUTES Типове значення: unset

Додаткові точні attribute keys або prefix-форми, дозволені export allowlist.

Необов'язкові можливості

Вихідний код Capka · Повна документація для LLM