Breaking Updates
Companion Hub is still before 1.0. The changes below can affect scripts, app manifests, and tools that you wrote against an earlier release. For the routine update process, see Updating Companion Hub.
Changes that can affect an existing setup
| Release | What changed | What to do |
|---|---|---|
| 0.2.60 | Hub stopped reading the Runtipi-era manifest fields tipi_version and min_tipi_version. It reads cihub_app_version and min_hub_version, and the older cihub_version and min_cihub_version. | Rename the fields in your app's config.json. |
| 0.2.76 | PostgreSQL and RabbitMQ moved onto a private ci-hub_internal network, and their host ports bind to 127.0.0.1 only. An installed app now receives only an allowlist of Hub environment variables, never Hub secrets. | Move tooling that reached the database or queue over the LAN onto the Hub machine. Stop relying on an app reading Hub secrets from its environment. |
| 0.2.77 | Traefik, cloudflared, and the Tailscale sidecar joined a new fixed-address ci-hub_edge network. Agent apps and apps with no login of their own publish their host port on 127.0.0.1 only. | Reach those apps from another device through Private VPN or the public web, not the LAN address and port. |
| 0.2.77 | Hub's inference engines are Ollama, vLLM, oMLX, and Lemonade. MTPLX, DSpark, Lucebox, llama.cpp, and LM Studio are gone. Their URL variables are no longer read, and a saved choice of a dropped engine falls back to Ollama. | Add the server as a decode or encode endpoint in Settings → AI. |
| 0.3.0 | Restoring a backup refuses an archive that holds hard links, devices, entries outside app-data, app, and user-config, or symlinks outside the app's data folder. Hub checks the archive before it changes the app. | Rebuild a hand-made archive from those three folders. |
| 0.3.0 | Sign-in, two-factor, sign-up, and password-reset requests are limited per client address, and a request over the limit gets HTTP 429 with Too many attempts. Try again in N seconds. A pending two-factor sign-in lasts five minutes and five tries. The unauthenticated guest dashboard list no longer includes each app's install settings. | Pace scripted sign-ins, and read install settings through an authenticated call. |
| 0.3.0 | The daily Auto-update stack check no longer asks the desktop app to install itself. The route GET /api/system/update/host-listener-token is gone: the app keeps its update token in state/update-listener.token. settings.json, seed, and .env.resolved are readable only by the account that runs Hub (mode 600). | Update the desktop app from Settings → System. Run cihub as the account that owns the data folder. |
| 0.3.0 | The desktop app keeps TAILSCALE_AUTHKEY and TAILSCALE_SERVE_USER_DISABLED, and ignores PRIVATE_VPN_USER_DISABLED, which now only keeps cihub from starting the Tailscale sidecar. Forward auth adds X-CI-Hub-User-Issuer, X-CI-Hub-User-Id, and X-CI-Hub-User-Id-Signature beside the existing three headers. cihub pool pair refuses a .local name. | Set TAILSCALE_SERVE_USER_DISABLED=true to stop Hub writing Tailscale Serve configuration. Pair Hub Pool nodes by tailnet name, or by address with --pin. |
Backward compatibility with legacy naming
Companion Hub builds on the foundation of the RunTipi self-hosting platform, so some legacy names are still accepted for compatibility. You do not need to change anything for these to keep working, but new apps and configurations should use the current names.
Every legacy name documented across the reference pages, in one place:
| Legacy name | Where | Current name | Status |
|---|---|---|---|
| tipi_version | config.json | cihub_app_version | No longer read since 0.2.60 |
| min_tipi_version | config.json | min_hub_version | No longer read since 0.2.60 |
| cihub_version | config.json | cihub_app_version | Still read |
| min_cihub_version | config.json | min_hub_version | Still read |
| TIPI_*, RUNTIPI_* | Environment | CI_HUB_* | Mapped at startup, for the path and directory variables |
| NGINX_PORT | Environment | HTTP_PORT | Still read |
| NGINX_PORT_SSL | Environment | HTTPS_PORT | Still read |
| HEADSCALE_PREAUTH_KEY | Environment | TAILSCALE_AUTHKEY | Still accepted |
| DNS_IP | Environment | Still read, but nothing uses it | |
| ci-os-hub, ci-os-hub-queue | Container and network names | ci-hub, ci-hub-queue | Still resolve as network aliases |
| cihub-compose.yml | user-config/ | hub-compose.yml | Read only when hub-compose.yml is absent |
| ci.lan default | Local domain | LOCAL_DOMAIN, falling back to DOMAIN, then localhost | Set LOCAL_DOMAIN to keep old hostnames |
The sections below give the detail for each area; the environment rows come from the legacy variables table, and the compose override file from Customize Companion Hub compose and Traefik config.
App manifest fields (config.json)
| Legacy field | Current field | Notes |
|---|---|---|
tipi_version | cihub_app_version | Hub no longer reads it. Without cihub_app_version, the manifest revision defaults to 1. |
min_tipi_version | min_hub_version | Hub no longer reads it. |
cihub_version | cihub_app_version | Still parsed, as the name from the first CIHub rename. |
min_cihub_version | min_hub_version | Still parsed. Hub currently records min_hub_version but does not enforce it. |
See config.json options for the full manifest format.
Environment variables
Earlier TIPI_* and RUNTIPI_* path and directory variables, such as RUNTIPI_APP_DATA_PATH and TIPI_DATA_DIR, are mapped to their CI_HUB_* equivalents at startup. The version variable is CI_HUB_VERSION. See Environment variables for the current list, including a table of legacy variables still accepted.
Local domain
Hub no longer hardcodes a LAN domain. LOCAL_DOMAIN now resolves to your configured DOMAIN when unset, and to localhost when neither is set, so no DNS configuration is needed out of the box. Hub doesn’t open a local app by hostname on any of these values: you open it on its direct port, as Finding your app’s URL describes. The local domain is the base of the internal hostnames that carry tunnel traffic to Traefik for apps you expose.
If you set a custom localDomain previously, it is preserved and still takes precedence. Installations that relied on the former ci.lan default should set LOCAL_DOMAIN explicitly to keep their existing internal hostnames.
How Hub picks the local domain that internal app hostnames are built under:
flowchart TD
A(["LOCAL_DOMAIN set?"]) -->|"yes"| B["internal hostnames under LOCAL_DOMAIN"]
A -->|"no"| C(["DOMAIN set?"])
C -->|"yes"| D["internal hostnames under DOMAIN"]
C -->|"no"| E["internal hostnames under localhost<br/>no DNS needed"]A localDomain saved in settings.json counts as set, and still takes precedence.
See Finding Your App’s URL and Custom settings.
Legacy names are a compatibility convenience, not a long-term guarantee. New
installations and app submissions should use the current cihub_app_version,
min_hub_version, and CI_HUB_* names.