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.

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

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.

Frontend access control

GitHub integration

The GitHub PR ↔ issue integration uses an inbound, read-only GitHub App for PR and check-suite webhooks. Set both variables below to enable Connect GitHub in Settings and accept incoming webhooks.

Behavior when either 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.

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.

Chain GitHub App

The issue-chain workflow uses a separate daemon-side GitHub App to mint outbound installation tokens for agent PR, review, and merge operations. It has no webhook and is not connected through Settings → GitHub.

The daemon never passes its own process-level GH_TOKEN / GITHUB_TOKEN through to child agents. When all four Chain App variables are present and valid, the daemon injects fresh GH_TOKEN / GITHUB_TOKEN values only for the built-in chain-capable agents (coda, wren, felix, dax). If minting fails for one of those tasks, the daemon refuses to fall back to an inherited GitHub token. When the Chain App is not configured and a non-chain agent needs GitHub credentials, set them on that agent through the agent environment endpoint instead of the daemon process env.

Usage analytics

Analytics is opt-in. If POSTHOG_API_KEY is empty, PostHog reporting is a no-op.

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