Custom environment variables
Companion Hub reads its startup configuration from environment variables, state/settings.json, and its generated .env files. On a packaged install (the desktop app or a Linux package), Hub generates .env and .env.dev in your data root (ROOT_FOLDER_HOST) and rewrites them every time it starts. This page explains which files Hub manages, how precedence works, and where to place custom values for Hub or individual apps so they survive restarts.
Environment files in the Hub data root
The generated environment files sit in your Hub data root (ROOT_FOLDER_HOST) alongside state/.env.resolved, and per-app environment overrides live under user-config/:
- .env
- .env.dev
- settings.json
- .env.resolved
- app.env
| File | Written by | Edit it? |
|---|---|---|
.env and .env.dev in ROOT_FOLDER_HOST | Hub. The desktop app and companion-hub --detached write .env.dev on macOS/Linux and .env on Windows (plus a copy). | Only for preserved keys (listed below). Hub overwrites all other keys on the next start. |
state/.env.resolved in ROOT_FOLDER_HOST | Hub (ci-hub container) at startup (mode 0600). | No — read-only snapshot of the final resolved configuration from the last boot. |
user-config/<app-store>/<app-id>/app.env | You. Merged on top of the app’s generated app-data/<app-store>/<app-id>/app.env whenever the app starts or updates. | Yes — use this file to add or override environment variables for an installed app. |
.env.local in a source checkout | You, when building and running Hub from a git checkout. | Yes, for cihub up local. Packaged installs do not read .env.local in ROOT_FOLDER_HOST. |
What Hub keeps in .env
When the launcher rewrites .env and .env.dev on startup, it preserves these keys from the existing file and recomputes everything else:
ROOT_FOLDER_HOST,JWT_SECRET,POSTGRES_PASSWORD,RABBITMQ_PASSWORD, andDOMAINCOMPOSE_PROFILES, withprivate-vpnandcloudflareadded or removed to match your Tailscale and Cloudflare stateSENTRY_DSNandSENTRY_DESKTOP_DSNTAILSCALE_AUTHKEY(or the legacyHEADSCALE_PREAUTH_KEY) andTAILSCALE_SERVE_USER_DISABLED=true, when set- The Hub image pin (
CI_HUB_IMAGE) written by an in-app stack update
The desktop app removes PRIVATE_VPN_USER_DISABLED when it rewrites .env, because only cihub reads that variable. See Turning Private VPN off.
Hub also selects host ports (API_PORT, HTTP_PORT, HTTPS_PORT, TRAEFIK_PORT, POSTGRES_PORT, and RABBITMQ_PORT) each time it starts, switching to a free port if a default port is already in use. On Linux desktop installs, the launcher publishes Traefik on 8880 and 8443 instead of 80 and 443 because unprivileged user accounts cannot bind ports below 1024. The launcher records the chosen ports in logs/desktop.log.
Resolution precedence
When the ci-hub container starts, it resolves each setting in this order (first match wins):
- Container process environment (
process.envpassed toci-hubby Docker Compose) state/settings.json(written when you save in Settings in the dashboard)- Generated
.env/.env.devinROOT_FOLDER_HOST - Built-in default
Three keys reverse steps 1 and 2 so choices saved in the dashboard or during pairing take precedence on the next start:
allowErrorMonitoringinstate/settings.jsonoverridesALLOW_ERROR_MONITORING.logLevelinstate/settings.jsonoverridesLOG_LEVELfor Hub’s own application log.- The public zone assigned when you pair with a CI Account overrides
DOMAIN.
Where to put your own values
- Dashboard settings (
state/settings.json). For Hub behavior such astimeZone,localDomain,guestDashboard,defaultAppCpuLimit,eventsTimeout,maxBackups,logLevel, orallowErrorMonitoring, use Settings in the dashboard or editstate/settings.json. See Custom settings. - The process environment that starts Hub. To pass an infrastructure variable such as
CI_HUB_DOCKER_HOSTorPRIVATE_VPN_USER_DISABLEDwhen starting Hub from the CLI, set it in the command environment — for example,CI_HUB_DOCKER_HOST=unix:///run/user/1000/docker.sock cihub up --detached. See Where the values come from. - Per-app environment overrides (
user-config/<app-store>/<app-id>/app.env). To set or override environment variables for an installed app (such as an API key, feature flag, or custom port setting), createuser-config/<app-store>/<app-id>/app.envwithKEY=valuelines and restart the app from the dashboard or withcihub app restart <app-id>. Do not editapp-data/<app-store>/<app-id>/app.envdirectly, because Hub regenerates that file on every app start. See Customize app configuration.
Only override Hub environment variables that you understand. Invalid database, queue, or path variables can prevent Companion Hub from starting.
See Environment variables for the full variable reference and Folder structure for where these files live on each operating system.