Environment variables
The backend is configured through a single .env file. In a provisioned installation it lives at /root/copula/.env (mode 0600); in a manual installation it is the .env you create from the ready template on the Manual installation page.
Core
| Variable | Default | Description |
|---|---|---|
BACKEND_PORT | 8080 | Port the backend listens on inside the container. The compose stacks publish host port 8901 to this port. |
LOG_LEVEL | — | Logging verbosity. |
CORS_ALLOWED_ORIGINS | * | Allowed CORS origins. |
JWT_SECRET | — | Required. Signing secret for JWTs; exactly 128 hex characters. |
ENCRYPTION_KEY | — | Required. AES-256 encryption key; 32 characters. |
LICENSE_TOKEN | — | Required. License token from the cabinet; also the bearer for the cabinet LLM router. |
CABINET_URL | https://api.copul4.com | Cabinet API endpoint. |
ADMIN_USER / ADMIN_PASS | — | Initial admin credentials; the backend auto-creates the admin account from them. |
Database
| Variable | Default | Description |
|---|---|---|
POSTGRES_HOST | postgres | PostgreSQL host. |
POSTGRES_PORT | 5432 | PostgreSQL port. |
POSTGRES_USER | agent | Database user. |
POSTGRES_PASSWORD | (empty) | Database password. |
POSTGRES_DB | agentdb | Database name. |
Model provider
| Variable | Default | Description |
|---|---|---|
MODEL_PROVIDER | openrouter | openrouter, custom or copula. Empty means openrouter; an unknown value logs a fatal message and falls back to openrouter. |
MODEL_BASE_URL | https://openrouter.ai/api/v1 | Base URL of the OpenAI-compatible API. |
MODEL_API_KEY | — | API key for the provider (not needed for copula — the license token is the credential). |
MODEL_NAME | — | Model name. New wizard installs default to copula-base. |
MODEL_MAX_TOKENS | 25000 | Max tokens per model response. |
Smart / Basic profiles
SMART_MODEL_* and BASIC_MODEL_* override the MODEL_* values per profile. Resolution follows the fallback chain SMART_* → BASIC_* → MODEL_* for each value.
| Variable group | Purpose |
|---|---|
SMART_MODEL_PROVIDER / SMART_MODEL_BASE_URL / SMART_MODEL_API_KEY / SMART_MODEL_NAME / SMART_MODEL_MAX_TOKENS | Overrides for the smart (heavy) profile. |
BASIC_MODEL_PROVIDER / BASIC_MODEL_BASE_URL / BASIC_MODEL_API_KEY / BASIC_MODEL_NAME / BASIC_MODEL_MAX_TOKENS | Overrides for the basic (light) profile. |
Legacy provider keys OPENROUTER_API_KEY and MINIMAX_API_KEY are also recognized.
Copula model preset
MODEL_PRESET selects which built-in agents inherit the smart profile and which inherit the basic profile when the backend seeds agent settings. The provisioning wizard writes this variable from the preset chosen on the Env step.
| Variable | Default | Description |
|---|---|---|
MODEL_PRESET | balanced | economy, balanced or performance. An empty or unknown value falls back to balanced with a warning in the log. |
| Preset | Smart profile | Basic profile |
|---|---|---|
economy | — | product, rnd, developer, qa, devops, e2e, chronicler |
balanced | product, rnd, devops | developer, qa, chronicler, e2e |
performance | product, rnd, developer, qa, devops, e2e, chronicler | — |
The preset is applied once, at first boot: seeding only fills agent settings that do not exist yet, so editing MODEL_PRESET later has no effect on existing agent settings — adjust profiles manually in the agent settings instead.
Smart-fast profile
SMART_FAST_MODEL_* is an additive third profile bundle that follows the same naming pattern as SMART_MODEL_* / BASIC_MODEL_*. Each value resolves along the fallback chain SMART_FAST_* → SMART_* → BASIC_* → MODEL_*.
| Variable group | Purpose |
|---|---|
SMART_FAST_MODEL_PROVIDER / SMART_FAST_MODEL_BASE_URL / SMART_FAST_MODEL_API_KEY / SMART_FAST_MODEL_NAME / SMART_FAST_MODEL_MAX_TOKENS | Overrides for the smart-fast profile. |
SMART_FAST_MODEL_CONTEXT_LIMIT | Context limit override for the smart-fast profile; falls back to AGENT_CONTEXT_TOKEN_LIMIT, then to 450000. |
When the resolved provider of the smart-fast profile is copula and none of SMART_FAST_MODEL_NAME, SMART_MODEL_NAME or BASIC_MODEL_NAME is set explicitly, the model name defaults to copula-smart-fast.
The smart-fast profile is seeded only if absent, under the same gate as the smart/basic profiles. On existing instances the profile appears additively at the next boot; instances without the new variables keep their current behaviour (the profile copies the values resolved from the fallback chain).
The existing names MODEL_*, SMART_MODEL_* and BASIC_MODEL_* are unchanged and remain fully supported — they are not deprecated. MODEL_PRESET and the preset inheritance maps above are also unchanged: smart-fast is not part of any preset.
copula-smart-fast requires the PRO tariff — see Getting a license.
Agents and runtime
| Variable | Default | Description |
|---|---|---|
AGENT_WORKSPACE | — | Workspace path for agent repositories. |
AGENT_CONTEXT_TOKEN_LIMIT | 120000 | Token limit for agent context. |
MAX_REPO_WORKERS | 20 | Maximum concurrent repository workers. |
SESSION_STORAGE_TYPE | — | database or file. |
SESSION_FILE_PATH | — | Path for file-based session storage. |
FILE_STORAGE_PATH | ./uploads | Where uploaded files are stored. |
MAX_FILE_SIZE_MB | 50 | Maximum upload size. |
Integrations and updates
| Variable | Default | Description |
|---|---|---|
SP_DISTRIBUTOR_URL | https://get.copul4.com | Distributor endpoint. |
SELF_UPDATE_IMAGE | — | Optional image reference override used by self-update availability checks. |
COCOINDEX_CODE_IMAGE | cocoindex/cocoindex-code:full | Code-search image override (compose-level). |
Cabinet LLM router (operators)
The cabinet LLM router (the copula provider endpoint behind CABINET_URL) is a centrally managed deployment. Its configuration is role-oriented, so an upstream provider can be swapped without renaming configuration:
| Variable | Default | Description |
|---|---|---|
PROVIDER_BASE_API_KEY | (empty) | API key of the base upstream; also the key of the search endpoint. |
PROVIDER_BASE_BASE_URL | https://api.minimax.io/v1 | Base URL of the base upstream. |
PROVIDER_BASE_MODEL | MiniMax-M3 | Upstream model override for copula-base. |
PROVIDER_SMART_API_KEY | (empty) | API key of the smart upstream. |
PROVIDER_SMART_BASE_URL | (empty) | Base URL of the smart upstream; while empty, copula-smart / copula-smart-long respond 502. |
PROVIDER_SMART_MODEL | kimi-k3 | Upstream model override for copula-smart. |
PROVIDER_SMART_MODEL_LONG | kimi-k3-1m | Upstream model override for copula-smart-long. |
PROVIDER_SMART_PROXY_URL | (empty) | Optional proxy for the smart upstream; validated fail-fast at startup. |
PROVIDER_SMART_FAST_API_KEY | (empty) | API key of the smart-fast upstream. |
PROVIDER_SMART_FAST_BASE_URL | (empty) | Base URL of the smart-fast upstream; while empty, copula-smart-fast responds 502. |
PROVIDER_SMART_FAST_MODEL | kimi-k3 | Upstream model override for copula-smart-fast (placeholder default). |
PROVIDER_SMART_FAST_PROXY_URL | (empty) | Optional proxy for the smart-fast upstream; same fail-fast validation. |
The old cabinet router names MINIMAX_* / MODAL_* were removed without a compatibility layer — the cabinet is a centrally managed deployment, and the operator updates the env at deploy time. This replacement applies to the cabinet router only; the backend env names above are unchanged.
Upstream model overrides are keyed by the wire model code. Wire models: copula-base (multiplier ×1), copula-smart (×10), copula-smart-long (×20) and copula-smart-fast (×20, PRO tariff only). copula-smart-fast has no context-limit fallback and no insurance retry.