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.
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). |