Environment variables

Environment variables configure the Hub stack. The desktop app and cihub generate most of them, and most are not meant to be edited by hand. For changes you make from the dashboard, see custom settings. For the environment-variable workflow, see custom environment variables.

Where the values come from

Hub reads each setting from the first of these places that has a value:

1. The Hub container’s environment. Docker Compose builds it from the stack’s env file and from values the compose file sets itself.
2. state/settings.json. The Settings page writes this file. See Folder structure.
3. The built-in default.

Hub writes the values it settled on to state/.env.resolved each time it starts. One variable reverses the order: for ALLOW_ERROR_MONITORING, the Settings switch wins over the variable, so a variable can never turn crash reporting back on for someone who turned it off.

flowchart TD
    W["Desktop app or cihub<br/>writes the stack env file"] --> C["Docker Compose<br/>env file + compose environment"]
    C -->|"container environment"| R["Hub resolves each setting"]
    S["state/settings.json<br/>written by the Settings page"] --> R
    R -->|"environment, then settings.json,<br/>then default"| E["state/.env.resolved"]
    R -->|"allowlist + APP_* variables"| A["Each installed app"]

The stack’s env file is .env.dev on macOS and Linux and .env on Windows, in the data root, with an identical copy under the other name. See Folder structure.

Core

Docker and stack

Networking

Linux lets only root open ports below 1024, so the Linux desktop app publishes Traefik on 8880 and 8443. cihub up on rootful Docker uses 80 and 443 when they are free and otherwise moves to 8880 and 8443; under rootless Docker it always uses those two. Apps you expose with Public Web reach Traefik inside Docker, so they don’t depend on these host ports.

Database (PostgreSQL)

Message queue (RabbitMQ)

Inference

VLLM_URL defaults to port 8000, and Hub probes oMLX on the same port, but only on Apple Silicon unless you set OMLX_URL. The two engines are not offered on the same machine. MTPLX_URL, DSPARK_URL, SPECULATIVE_INFERENCE_URL, LLAMACPP_URL, and LMSTUDIO_URL are no longer read. A decode endpoint and an encode endpoint in Settings override the selected engine.

The compose file sets OLLAMA_URL directly, so a value in the env file does not override it. When that address does not answer, Hub also tries http://172.17.0.1:11434 and http://localhost:11434.

Tailscale (private VPN)

The hub-tailscale sidecar runs only when either TAILSCALE_AUTHKEY is set or the sidecar already holds a Tailscale login. A Hub you start with cihub also keeps it off when PRIVATE_VPN_USER_DISABLED is true.

Hub Pool tuning

These variables tune how Hub Pool places requests and how long it waits for an answer. The defaults suit most pairs of Hubs, so leave them alone until Recent routing gives you a reason to change one. Put them in the stack’s env file (see Where the values come from) and restart the stack. The desktop app drops lines it doesn’t manage the next time it launches, so they last only on a Hub you start with cihub up. The three kill switches, HUB_POOL_USER_DISABLED, HUB_POOL_OUTBOUND_DISABLED, and HUB_POOL_INBOUND_DISABLED, are in Tailscale (private VPN) above.

Model Context Protocol (MCP)

MCP_API_KEY is no longer a credential. Hub ignores it and drops it from its resolved environment. Create keys in Settings → Security or with cihub api-key create. See Companion agent.

Feature flags

Error monitoring (Sentry)

Crash reports go to Sentry only when a reporting address is present. The Hub image and the desktop app ship with one. Three switches turn reporting off even then: CI_LOCAL_ONLY, CI_TELEMETRY, and the Allow anonymous error monitoring switch in the General settings card on the Settings tab. See Crash reporting for what Hub sends.

VITE_SENTRY_DSN and VITE_SENTRY_RELEASE set the dashboard’s own Sentry address and release. They are compiled into the dashboard when the Hub image is built, so changing them at runtime has no effect.

Legacy variables

These variables are still accepted for backward compatibility but should not be used in new installations.

App variables

Hub writes an app.env file for each installed app, and every service in the app reads it. Hub does not copy its own environment into it. An app inherits only an allowlist of Hub values: DOMAIN, LOCAL_DOMAIN, ROOT_FOLDER_HOST, CI_HUB_APP_DATA_PATH, INTERNAL_IP, ARCHITECTURE, TZ, LOG_LEVEL, NODE_ENV, CI_HUB_VERSION, DEMO_MODE, and CI_CLOUD_URL. Hub’s secrets, such as JWT_SECRET and the database and queue passwords, never reach an app.

Hub then sets these app-scoped variables each time it writes the file: on install and whenever the app starts, restarts, updates, or resets.

An app that declares hub_integration in its manifest also receives the variables described in Companion agent and AI and inference.