Skip to Content
DocumentationGetting StartedCustom environment variables

Custom environment variables

Companion Hub reads its configuration from environment variables. On a packaged install (the desktop app or a Linux package), you don’t set them by editing files: Hub generates its .env file and rewrites it on start. This page explains what survives and where to put your own values instead.

The generated .env file sits at the top of your Hub data root (ROOT_FOLDER_HOST):

    • .env
FileWritten byEdit it?
.env in the data root of a packaged installHub. The desktop app, and companion-hub --detached, rewrite it every time they start the HubNo — anything except the values listed below is overwritten on the next start
.env.local in a source checkoutYou, if you build Hub from sourceYes, for cihub up local. A .env.local in a packaged install’s data folder is not read

What Hub keeps in .env

When Hub rewrites .env, it carries these values forward and recomputes everything else from the app it’s running:

  • 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 next to it
  • TAILSCALE_AUTHKEY (or the older HEADSCALE_PREAUTH_KEY) and TAILSCALE_SERVE_USER_DISABLED=true, when you set them
  • 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 it. See Turning Private VPN off.

Hub also chooses the ports (API_PORT, HTTP_PORT, HTTPS_PORT, and the others) each time it starts, and moves to a free port when the default is taken. On Linux the desktop app publishes Traefik on 8880 and 8443 instead of 80 and 443, because Linux doesn’t let a normal user open ports below 1024. logs/desktop.log records the choice.

Where to put your own values

  • Settings. Most options you’d want to change are in Settings in the dashboard, or in settings.json — see Custom settings.
  • The environment that starts Hub. Set the variable in the environment of the process that starts it, for example CI_HUB_DOCKER_HOST=unix:///run/user/1000/docker.sock cihub up, or POSTGRES_PASSWORD=... cihub up on a machine that has never run Hub. Hub reads a process environment variable before settings.json and before .env.

Not all environment variables can be safely overridden. Only override values you understand — incorrect settings may prevent Companion Hub from starting.

See Environment variables for a list of available variables and Folder structure for where these files live.

Last updated on
Custom settingsTutorials