Skip to Content
DocumentationGetting startedCustom environment variables

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
FileWritten byEdit it?
.env and .env.dev in ROOT_FOLDER_HOSTHub. 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_HOSTHub (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.envYou. 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 checkoutYou, 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, and DOMAIN
  • COMPOSE_PROFILES, with private-vpn and cloudflare added or removed to match your Tailscale and Cloudflare state
  • SENTRY_DSN and SENTRY_DESKTOP_DSN
  • TAILSCALE_AUTHKEY (or the legacy HEADSCALE_PREAUTH_KEY) and TAILSCALE_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):

  1. Container process environment (process.env passed to ci-hub by Docker Compose)
  2. state/settings.json (written when you save in Settings in the dashboard)
  3. Generated .env / .env.dev in ROOT_FOLDER_HOST
  4. 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:

  • allowErrorMonitoring in state/settings.json overrides ALLOW_ERROR_MONITORING.
  • logLevel in state/settings.json overrides LOG_LEVEL for 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 as timeZone, localDomain, guestDashboard, defaultAppCpuLimit, eventsTimeout, maxBackups, logLevel, or allowErrorMonitoring, use Settings in the dashboard or edit state/settings.json. See Custom settings.
  • The process environment that starts Hub. To pass an infrastructure variable such as CI_HUB_DOCKER_HOST or PRIVATE_VPN_USER_DISABLED when 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), create user-config/<app-store>/<app-id>/app.env with KEY=value lines and restart the app from the dashboard or with cihub app restart <app-id>. Do not edit app-data/<app-store>/<app-id>/app.env directly, 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.

Last updated on