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

The primary and replica connection limits are independent. Budget their sum across every API process against the PostgreSQL cluster's connection ceiling. Replica connections are recycled after five minutes by default to refresh read-only validation after promotion. Replica connection failures transparently fall back to primary and open a short passive circuit; no background database probe is added. Replica reads have no application-enforced staleness bound, so monitor lag in the database layer and keep consistency-sensitive reads on primary.

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, Slack bot, and Telegram 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 runs.

MULTICA_LLM_MAX_RETRIES is the single source for the retry policy. Leave it unset for the default of 2, set 0 to send exactly one request per call, or set 1–5 to cap retries at that many. It is a ceiling, not a quota: only retryable failures consume it, and a success or the caller's own deadline can end the call sooner. Any other value — negative, non-numeric, or above 5 — fails startup instead of being corrected silently. The ceiling is a latency budget: backoff starts at 0.5s and doubles to an 8s cap, so a larger budget would outlast the callers' own deadlines and turn a retryable failure into a timeout. Retries cover connection failures and HTTP 408, 409, 429 and 5xx; all other 4xx responses are returned as-is. The server logs the effective policy at startup as llm retry policy, with no credentials in the line.

Two features use this layer, and each one sends chat content to the endpoint you configure:

• Chat auto-titling — the first user message of a new chat session, sent verbatim. Attachments are never included.
• Follow-up questions (the suggestion buttons under an agent reply) — the tail of the conversation: up to 6 messages, with the reply being answered capped at 3000 characters and each older message at 800.

When both the API key and the base URL are empty, this layer is disabled and makes no upstream request at all — neither feature above sends anything. That is the supported configuration when your policy does not allow this layer to send chat content off the deployment: chat sessions keep the title the client derives from the first message, the follow-up question buttons do not appear, and everything else is unaffected.

Daemon configuration

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

For the internal context that the daemon injects into agent tasks, see Task runtime environment.

Each AI coding tool accepts MULTICA_<PROVIDER>_PATH and MULTICA_<PROVIDER>_MODEL to override the command path and default model. QwenPaw and MiniMax Code have no model variable because Multica never sends them a model; MiniMax Code's path variable is MULTICA_MCODE_PATH — 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). DeepSeek Harness additionally accepts MULTICA_DSH_PROFILE_BUNDLE: a comma-separated list of bundles to install into its multica profile when that profile is missing, tried in order, where each entry is an npm spec, a directory, or a packed tarball. It is unset by default, and the --stdio protocol Multica drives is what that profile supplies, so an unset variable leaves the DSH installation untouched and the daemon reports the missing profile instead of registering an unusable runtime. Multica's own bridge is not on a public npm registry yet, so choosing a value is covered in Install an agent runtime; whatever you set is installed into every daemon host's DSH home without further confirmation, so treat it as a supply-chain decision. The install MULTICA_DSH_PROFILE_BUNDLE enables is bounded on purpose: it runs at most once per daemon lifetime, only when the probe reports the profile genuinely absent, and a failure is logged with the package manager's own output and retried only after a daemon restart. A probe that times out, or answers with a protocol version this daemon does not drive, is reported and never installed over — the daemon does not overwrite a profile that is deliberately there. To diagnose, search the daemon log for DSH runtime profile; to undo an install, delete $DSH_HOME/profiles/multica (default ~/.dsh/profiles/multica). MULTICA_DSH_PLUGIN_PATH overrides the directory the install resolves pnpm from. DSH Desktop keeps the pnpm that dsh plugin forwards to inside its own runtime-commands directory on both macOS and Windows, and the daemon finds and prepends it automatically — including the versioned layout a newer Desktop uses — so this variable is only needed for an installation the daemon cannot find, or to make the install use a pnpm of your own. Setting it replaces the search entirely: if the directory does not exist, the install falls back to whatever pnpm is on the daemon's PATH rather than to the bundled one. Linux has no DSH Desktop, so there the install always uses PATH. Dim supports MULTICA_DIM_PATH and MULTICA_DIM_MODEL (a model id from the dim catalog). ZeroClaw supports MULTICA_ZEROCLAW_PATH but has no model variable; its agent profile owns the model selection. 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

Cursor's verified background cleanup requires Linux 6.9 or newer (process-group pidfds), macOS kernel support for process identity queries and audit-token signalling, or a successfully assigned nested Job Object on Windows. On macOS, each process is signalled using a kernel-checked PID version; no same-session group join is required. These macOS APIs are private and checked at capture time. A launch that cannot be claimed returns its original tool result and uses the ordinary idle watchdog, including when the tool watchdog is 0. Already-claimed work remains in flight if cleanup cannot be confirmed. With the tool watchdog set to 0 there is no such boundary at all: claimed background work keeps the run in flight for as long as it lives, so the run is bounded only by MULTICA_AGENT_TIMEOUT, which is 0 by default.

Owned Cursor background processes are also stopped when the run completes normally, so a background server started by that run does not intentionally survive finalization. macOS can recognize late children through retained original-parent identities, but cannot prove a chain whose intermediate processes disappeared before observation. Such processes, work that leaves the tracked group, or persistent ownership/signalling errors can leave background work behind. Unconfirmed cleanup is logged and never grants a successful-cleanup recovery window; unknown processes are not killed based only on their numeric PID or process group.

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

First-party self-host telemetry sends one deployment-level snapshot per UTC day to the fixed, non-configurable https://telemetry.multica.ai/v1/telemetry/events endpoint. It contains the formal release version; bucketed workspace, distinct-human-member, active-agent, and 24-hour active-daemon counts; and aggregate run counts for the previous 24 hours. It never includes names, email addresses or domains, IP addresses, business identifiers, host/device details, repositories, models/plugins, prompts/output, comments/chats, paths, token/cost data, credentials, errors, stacks, or logs. It is used only to understand self-hosted version adoption, deployment-size ranges, and aggregate usage—not for billing, licensing, authentication, or security decisions.

DO_NOT_TRACK and ANALYTICS_DISABLED are independent. The former controls this first-party anonymous snapshot; the latter controls the optional PostHog integration.

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.