Environment variables
Deployment settings, their defaults, and which address each part of Cantinarr needs.
Most settings belong in the app. These variables configure the server process. Restart or recreate the container after changing them.
| Variable | Default | Description |
|---|---|---|
CANTINARR_PORT |
8585 |
HTTP listen port. Kubernetes service-link values (tcp://…) injected by a Service named cantinarr are ignored in favor of the default; set a numeric value to override |
CANTINARR_SERVER_NAME |
Cantinarr |
Display name shown in clients |
CANTINARR_ARR_CALLBACK_URL |
direct request origin | Origin the Radarr/Sonarr/Chaptarr/Lidarr containers POST webhooks back to, so it must be resolvable and reachable from the arrs themselves: in same-network/cluster deployments a cluster-internal origin like http://cantinarr:8585 is usually the right value. Set it explicitly behind a reverse proxy (forwarded headers are deliberately ignored). Formerly CANTINARR_PUBLIC_URL, which stays accepted forever (the new name wins when both are set); it was renamed because “public URL” suggested the user-facing address, which is the in-app Settings > External Address instead |
CANTINARR_OAUTH_ISSUER |
request-derived origin | Canonical external HTTPS origin for inbound MCP OAuth metadata, token audience, and browser-origin checks; setting it also enables stable RFC 9207 authorization-response iss and permits that origin to call /mcp. Set it behind a reverse proxy and keep it stable (changing it makes existing audience-bound MCP tokens reconnect); do not substitute the arr-reachable CANTINARR_ARR_CALLBACK_URL |
CANTINARR_MCP_ALLOWED_ORIGINS |
unset | Comma-separated additional browser origins allowed to call /mcp. If neither this nor CANTINARR_OAUTH_ISSUER is configured, requests that supply Origin are rejected; native and server-side MCP clients need no entry |
CANTINARR_JWT_SECRET |
auto-generated | HMAC secret for signing short-lived access tokens. Device sessions do not depend on it: changing it never signs anyone out |
CANTINARR_ENCRYPTION_KEY |
auto-generated key file | Base64 32-byte key for secrets-at-rest (default: /config/encryption.key) |
CANTINARR_AI_PROVIDER |
codex |
Fallback provider for the included server AI profile when none is saved in the admin UI (anthropic, openai, gemini, grok, codex, or grok_oauth) |
CANTINARR_AI_MODEL |
provider default | Fallback model for the included server AI profile when none is saved in the admin UI |
CANTINARR_CODEX_BIN |
auto-discovered | Optional path to codex-app-server or the full codex CLI; container images bundle the tested 0.144.3 app-server at /usr/local/bin/codex-app-server |
CANTINARR_CODEX_RUNTIME_DIR |
/dev/shm/cantinarr-codex |
Absolute Linux tmpfs/ramfs directory used for server-owned, ephemeral per-session Codex state; if it already exists, it must be owned by the server user with mode 0700 |
CANTINARR_MEDIA_ROOTS |
unset | Comma-separated absolute paths forming the outer filesystem allowlist for completed-media downloads. Empty disables file downloads. Mount libraries read-only inside these Cantinarr-visible roots, then map each arr-reported prefix to a path beneath them in that instance’s settings; / is refused |
CANTINARR_PUSH_GATEWAY_URL |
unset | Push gateway origin: setting it enables push notifications (auto-enrolls on first start). The community relay is https://push.cantinarr.com; its former name https://push.julian.codes is still accepted and rewritten to the new one at start (same gateway, same enrollment) |
CANTINARR_PUSH_API_KEY |
unset | Optional pinned gateway key (blank = auto-enroll) |
CANTINARR_PUSH_ENROLL_TOKEN |
unset | Only for gateways with gated enrollment |
CANTINARR_APPLE_APP_IDS |
unset | TeamID.BundleID values for native Apple passkeys (/.well-known/apple-app-site-association) |
CANTINARR_ANDROID_PACKAGE_NAME |
codes.julian.cantinarr |
Android package name for native passkeys |
CANTINARR_ANDROID_CERT_SHA256_FINGERPRINTS |
unset | Android signing cert fingerprints for /.well-known/assetlinks.json |
CANTINARR_WEBAUTHN_EXTRA_ORIGINS |
unset | Additional WebAuthn origins to trust |
CANTINARR_DISABLE_UPDATE_CHECK |
unset | Set to 1 to disable the periodic GitHub release check behind the admin update-status endpoint |
HTTP_PROXY / HTTPS_PROXY |
unset | Standard proxy variables (Go’s semantics; lower-case names accepted) for the server’s internet-bound traffic only: TMDB, Trakt, hosted AI providers, plex.tv, the GitHub update check, and the push relay. An address saved under Settings > Outbound Proxy wins whenever one is set. Arr instances, download clients, Plex Media Server, Jellyfin/Emby/Audiobookshelf, Tautulli/Tracearr, and the Local AI provider are dialed directly no matter what these say |
NO_PROXY |
unset | Hosts the env-var proxy skips (Go’s semantics). It never needs your arr, download-client, or media-server hosts, because LAN instance traffic is never proxied; it is the right tool for a self-hosted push relay on the LAN, which the in-app setting would proxy |
PUID |
unset (runs as root) | Container image only. Run the server as this user id: on every start the image takes ownership of /config for it, so the database and encryption key it writes are owned by that user on the host (the linuxserver-style convention Synology and Unraid stacks expect). Ignored when the container is already started as a non-root user (compose user:, TrueNAS) |
PGID |
same as PUID |
Group id to pair with PUID; ignored without it |
Compatibility aliases
Section titled “Compatibility aliases”CANTINARR_PUBLIC_URL remains an alias for CANTINARR_ARR_CALLBACK_URL; the new name wins. CANTINARR_ANDROID_CERT_SHA256 remains an alias for CANTINARR_ANDROID_CERT_SHA256_FINGERPRINTS; the plural name wins. Kubernetes may inject CANTINARR_SERVICE_HOST and CANTINARR_SERVICE_PORT; these are platform values, not settings to add by hand.
The database lives at /config/cantinarr.db. There is no supported CANTINARR_DB_PATH setting. Preserve the whole /config directory and its encryption key. See backups and networking for worked examples.