Environment variables

A self-hosted Multica server reads its configuration from environment variables at startup — database, sign-in, email, storage, signup allowlists all live here. This page groups every variable by purpose: each section spells out what happens if you leave it unset and which ones you must set in production. For how to actually configure the auth-related ones, see Sign-in and signup configuration.

Core server variables

These are the core variables you must think about before deploying — some have defaults that let the server start, but in production you should set the required ones explicitly.

Database connection pool

When unset, the values above are used — not pgx's built-in 4/NumCPU defaults, which previously caused pool exhaustion in production.

Email configuration

Multica supports two delivery backends — Resend for cloud deployments, or an SMTP relay for internal / on-premise networks. SMTP_HOST takes priority over RESEND_API_KEY when both are set.

Resend

SMTP relay

STARTTLS is upgraded automatically when the server advertises it. The dial timeout is 10s and the whole SMTP session has a 30s deadline, so a black-holed relay can't hang the auth handler.

Behavior when neither is set: the server does not error, but every email that should have been sent (verification codes, invite links) is written to the server's stdout only. Convenient for local development — copy the code out of the server logs; in production, forgetting to set this creates a silent black hole, with users never receiving email and no error surfaced.

Google OAuth configuration

Optional. Leave unset for email + verification code only; configure it to add "Sign in with Google" on the sign-in page.

Takes effect at runtime: the frontend reads these settings via /api/config at runtime, so changing them requires no frontend rebuild or redeploy — restart the server and they apply.

Full setup (including Google Cloud Console steps) is in Sign-in and signup configuration.

File storage configuration

Multica stores user-uploaded attachments (images and files in comments). S3 is preferred; if S3 is not configured, it falls back to local disk.

S3 / S3-compatible storage

When S3_BUCKET is unset: the server logs "S3_BUCKET not set, cloud upload disabled" at startup, and all uploads fall back to local disk.

Stored object URLs are constructed in this order of priority:

1. https://<CLOUDFRONT_DOMAIN>/<key> if CLOUDFRONT_DOMAIN is set.
2. <AWS_ENDPOINT_URL>/<S3_BUCKET>/<key> (path-style) if AWS_ENDPOINT_URL is set.
3. https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key> (virtual-hosted-style). When S3_BUCKET contains dots, the server falls back to https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key> (path-style) because the AWS-issued wildcard TLS certificate does not validate dotted bucket hosts.

API download_url values use GET /api/attachments/{id}/download unless CloudFront signing is configured. The endpoint redirects to CloudFront/S3 presigned URLs when safe, or streams through the server for private/internal endpoints such as http://rustfs:9000. For Docker/VPC-only object stores, set ATTACHMENT_DOWNLOAD_MODE=proxy if auto detection is not conservative enough for your network.

Local disk (when S3 is not configured)

CloudFront (optional)

If you front S3 with CloudFront, three variables apply: CLOUDFRONT_DOMAIN, CLOUDFRONT_KEY_PAIR_ID, CLOUDFRONT_PRIVATE_KEY (or CLOUDFRONT_PRIVATE_KEY_SECRET to read from Secrets Manager). Skip them if you don't use CloudFront — they don't conflict with S3 configuration.

Cookie domain

• Empty: the cookie is valid only on the exact host visited (correct for single-host deployments)
• Set to .example.com: the cookie is shared across subdomains (so app.example.com and api.example.com share a sign-in session)
• Warning: it cannot be an IP address (browsers ignore it)

Restricting who can sign up

Three allowlist layers combine by priority. If any layer is set to a non-empty value, emails that don't match are rejected — even ALLOW_SIGNUP=true won't override that.

The counterintuitive part: ALLOWED_EMAIL_DOMAINS=company.io + ALLOW_SIGNUP=true does not mean "allow company.io or everyone" — it means only allow company.io. The allowlist layers are AND semantics — the full decision tree is in Sign-in and signup configuration → Signup allowlists.

Invite flows themselves do not check the signup allowlist — but the invitee must still be able to sign in before accepting the invite. If they already have a Multica account (for example from another workspace), they can accept directly, unaffected by the allowlist; if they have never signed up, the first step of sign-in (requesting a verification code) still passes through the allowlist check, and an email rejected by ALLOW_SIGNUP=false or by ALLOWED_EMAILS / ALLOWED_EMAIL_DOMAINS cannot finish signup, and therefore cannot accept the invite.

Locking down workspace creation

ALLOW_SIGNUP=false blocks new accounts, but it does not block an already-signed-in user from creating another workspace via POST /api/workspaces. On a self-hosted instance where every issue, repo, and agent must be visible to the platform admin, set DISABLE_WORKSPACE_CREATION=true to close that gap.

Recommended bootstrap sequence:

1. Start the instance with DISABLE_WORKSPACE_CREATION unset (the default).
2. Sign in as the admin and create the shared workspace.
3. Set DISABLE_WORKSPACE_CREATION=true and restart the backend. From this point on, users join via invitation only.

If you also want to keep ALLOW_SIGNUP=true so invited users can finish signup with their first verification code, combine DISABLE_WORKSPACE_CREATION=true with ALLOWED_EMAIL_DOMAINS / ALLOWED_EMAILS to scope which addresses can sign up. Setting ALLOW_SIGNUP=false will additionally block pending invitees from creating their account at all — useful only on instances where every member already has a Multica account.

Rate limiting (optional Redis)

Public auth endpoints — /auth/send-code, /auth/verify-code, /auth/google — have per-IP fixed-window rate limiting in front of them. The limiter is backed by Redis. When REDIS_URL is unset the middleware is a no-op (fail-open) and the backend logs rate limiting disabled: REDIS_URL not configured at startup.

When a request is over the limit, the server replies with 429 Too Many Requests, Retry-After: 60, and body {"error":"too many requests"}.

This separate RATE_LIMIT_TRUSTED_PROXIES is not the same as MULTICA_TRUSTED_PROXIES, which controls the autopilot-webhook limiter (/api/webhooks/autopilots/{token}). Each limiter parses its own list, so a deployment behind a proxy should set both.

Daemon tuning parameters

The daemon runs on the user's local machine, and its config is read from local environment variables too. The common ones:

For a full explanation of how each parameter affects daemon behavior, see Daemon and runtimes.

Default agent arguments (MULTICA_<PROVIDER>_ARGS)

These set a fleet-wide default layer of CLI flags for a backend — a convenient way to apply a default cost or resource baseline (for example --max-turns) across every agent on a daemon without editing each agent's custom_args individually. This is a default layer, not a hard ceiling: per-agent custom_args are appended afterward and can override it (see Precedence below).

• Precedence: the default args are applied first, then each agent's own custom_args are appended after. For flags that take a value, the downstream CLI's own argument parser decides the winner (last occurrence wins for most tools), so an individual agent can raise a daemon default but the default still applies wherever the agent doesn't override it.
• Parsing: the value is split with POSIX shell-word rules, so quoting works — MULTICA_CLAUDE_ARGS='--append-system-prompt "multi word"' parses into two tokens.
• Safety: both the default-args and per-agent custom_args layers pass through the same blocked-flags filter, so protocol-critical flags (such as -p, --output-format, --input-format, --permission-mode, --mcp-config for Claude, and --listen for Codex) cannot be injected through either layer.
• Unset/empty means no change to behavior.

Frontend access control

GitHub integration

The GitHub PR ↔ issue integration needs two variables. Set both to enable Connect GitHub in Settings and accept incoming webhooks. Two additional variables are optional but populate the connected account name on install.

Behavior when either of the required variables is unset:

• Connect GitHub in Settings → GitHub is disabled and shows a "not configured" hint to admins.
• The /api/webhooks/github endpoint returns 503 github webhooks not configured — Multica refuses to process events with no secret rather than treating every signature as valid.

Behavior when the optional GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY are unset:

• The connection card briefly shows Connected to unknown after install. Multica refreshes the row to the real org/user name as soon as GitHub delivers the installation.created webhook (typically within a few seconds), and broadcasts a realtime update so any open Settings → GitHub tab reflects the change without a manual refresh.

Note: GITHUB_WEBHOOK_SECRET is reused as the signing key for the install-flow state token, so operators only need to manage one secret. It is not the GitHub App's Client secret — Client secrets are OAuth-related and not used by this integration. See GitHub integration → Self-host setup for the full walkthrough.

Usage analytics

By default, the server reports to Multica's official PostHog instance. To opt out, set ANALYTICS_DISABLED=true.

Next

• Sign-in and signup configuration — how to actually configure the auth-related variables above and where the traps are
• GitHub integration — how to set up the GitHub App that backs GITHUB_APP_SLUG / GITHUB_WEBHOOK_SECRET
• Troubleshooting — symptoms and fixes for common misconfigurations
• Daemon and runtimes — what the MULTICA_DAEMON_* parameters actually do