Environment variables

Multica reads environment variables at process startup. After changing one, restart the affected API, web, or daemon process. Docker Compose's docker compose restart does not re-read .env; recreate containers with up -d for changes to take effect.

This page lists deployment-facing configuration only; test variables and internal task variables are not covered here. It is a grouped reference — for full deployment steps, see the self-host quickstart.

Minimum production configuration

DATABASE_URL=postgres://user:password@postgres:5432/multica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://multica.example.com
MULTICA_APP_URL=https://multica.example.com
MULTICA_PUBLIC_URL=https://api.multica.example.com

You also need to pick an email service, otherwise verification codes and invitations are only written to the server log.

API and database

When setting a shutdown hold on Kubernetes, terminationGracePeriodSeconds must exceed the hold plus the time the actual shutdown needs.

Public URLs and browser access

When the frontend and API run on different hosts and the browser talks to the API domain directly, you must set COOKIE_DOMAIN — otherwise the browser cannot read the CSRF cookie: every write request returns 403 CSRF validation failed while reads work fine. Use the narrowest parent domain that covers both hosts (.agent.example.com over .example.com). It spreads the sign-in session cookie to every host under that domain, which is only acceptable when all of those hosts are operated by the same trusted party. After changing it, clear the old cookies on both hosts and sign in again. If you follow the same-origin recipe in the self-host quickstart (the browser only visits the app domain), keep it empty. Do not use an IP address — browsers ignore cookies whose Domain is an IP.

Email and sign-in

Resend

SMTP

SMTP takes priority over Resend whenever SMTP_HOST is non-empty.

Google OAuth

Signup scope

For the exact allowlist evaluation order, see Sign-in and signup.

Attachment storage

When S3_BUCKET is unset, Multica uses local disk.

S3 or compatible storage

Use ATTACHMENT_DOWNLOAD_MODE=proxy when the endpoint — an internal MinIO, for example — is not reachable from the browser.

Local disk

CloudFront

Redis and rate limiting

Deployments behind a reverse proxy must list their real proxy ranges. Do not blanket-trust all sources, or clients can forge forwarded IPs.

The auth rate limits require REDIS_URL; without it, the startup log notes that auth rate limiting is disabled. Invitation limits still run in process-local memory without Redis and become shared across replicas when Redis is configured. If configured Redis becomes temporarily unavailable, auth rate limiting fails open, while invitation creation returns a retryable 503 instead of sending email without protection.

External integrations

Without GITHUB_APP_ID and the private key, PRs still link, mirror, and trigger merge-to-done normally, but cards show no CI or mergeability status, and the "pick from GitHub" repository entry is disabled.

For setup steps, see GitHub integration, Lark bot, and Slack bot.

Server-side LLM

This group configures server-side assist generation, such as conversation titles; it is not the AI coding tool credentials agents use to execute tasks.

When both the API key and base URL are empty, server-side LLM generation is off and callers use local fallback logic.

Daemon configuration

The variables below are read on the computer that runs your agents, not in the API container.

Each AI coding tool accepts MULTICA_<PROVIDER>_PATH and MULTICA_<PROVIDER>_MODEL to override the command path and default model. QwenPaw is the exception: it has no MULTICA_QWENPAW_MODEL, because Multica never sends it a model — see AI coding tools comparison. DeepSeek Harness supports MULTICA_DSH_PATH and MULTICA_DSH_MODEL (a model id from the dsh catalog, e.g. deepseek-official/deepseek-chat). Machine-wide default arguments via MULTICA_<PROVIDER>_ARGS are currently supported for five tools: Claude Code, Codex, CodeBuddy, Qwen Code, and QwenPaw. The variables are MULTICA_CLAUDE_ARGS, MULTICA_CODEX_ARGS, MULTICA_CODEBUDDY_ARGS, MULTICA_QWEN_ARGS, and MULTICA_QWENPAW_ARGS. For example:

MULTICA_CLAUDE_PATH=/opt/bin/claude
MULTICA_CLAUDE_ARGS=--max-turns 40

Precedence is command-line flag → environment variable → ~/.multica/config.json → built-in default. For watchdog behavior, see Daemon and runtimes.

Persisting daemon configuration

Common daemon-side settings can also be written to ~/.multica/config.json instead of relying on shell environment variables; named profiles keep theirs at ~/.multica/profiles/<name>/config.json:

multica config set poll_interval 10s
multica config show

Supported keys:

A few value rules:

• Duration keys accept positive Go durations (such as 10s, 2h); 0s and negative values are rejected. The one exception is agent_timeout: 0s is valid and explicitly disables the run time limit.
• Passing an empty string clears a persisted value and falls back to the env var or built-in default, for example multica config set poll_interval "".
• max_concurrent_tasks requires a non-negative integer.
• Relative workspaces_root values are converted to absolute paths when saved.

Observability and analytics

Next steps

• Sign-in and signup — sign-in methods and signup restrictions.
• Troubleshooting — symptom-based diagnosis of deployment problems.
• Daemon and runtimes — the daemon-side counterparts of this configuration.