Custom settings
Most settings live in Settings in the dashboard, which writes them to a settings.json file in the state directory of your Hub data root (ROOT_FOLDER_HOST). You can also edit that file yourself. Hub keeps it across restarts.
Where the file lives (the rest of the data root is in Folder structure):
- settings.json
On a packaged install, ROOT_FOLDER_HOST is Hub’s companion-hub data folder: ~/.local/share/companion-hub on Linux, ~/Library/Application Support/companion-hub on macOS, and %APPDATA%\companion-hub on Windows.
For example:
{
"guestDashboard": true,
"eventsTimeout": 15
}The file must be valid JSON. Validate it with a tool such as
JSONLint before restarting Hub. Stop Hub first
(cihub down) when you edit: the dashboard rewrites the file when you save in
Settings, and it drops any key it doesn’t recognize. If a single field is
invalid, Hub ignores that field, names it in its log, and applies the rest.
settings.json also holds your Portal device key (ciHubApiKey), the key
cihub uses to reach this Hub from the same machine (hubLocalKey), and, if
you added them, cloud provider API keys. Don’t share the file, and leave the
keys you didn’t add alone. Edit it as the account that runs Hub, not with
sudo: Hub keeps settings.json readable by that account only (mode 600),
and tightens an older, more open file the next time it starts.
The matching environment variable wins over settings.json — for example GUEST_DASHBOARD over guestDashboard. Hub resolves each value from the process environment first, then settings.json, then the generated .env file, then the default.
Available settings
| Parameter | Description | Type | Default value |
|---|---|---|---|
timeZone | The IANA time zone Hub uses, such as Europe/Berlin | string | (the host’s time zone) |
dnsIp | The IP address of the DNS server to use. Legacy, kept for compatibility | string | 9.9.9.9 |
appDataPath | The folder that holds installed apps’ data. A relative path resolves against the data root, and it must not end in /app-data | string | (the Hub data root) |
localDomain | The domain Hub uses to route Cloudflare-exposed apps to Traefik. It isn’t the address you open a local app at — see Finding your app’s URL. In Settings the field is read-only until you turn on Advanced settings | string | localhost |
demoMode | Start Companion Hub in demo mode | boolean | false |
guestDashboard | Allow guest access to the dashboard | boolean | false |
disablePasswordReset | Disable the password reset flow | boolean | true |
allowErrorMonitoring | Whether Hub sends anonymous crash reports to the Companion Intelligence developers. On by default in distributed builds; see Crash reporting | boolean | true |
allowAutoThemes | Enables thematically changing the dashboard based on the time of the year | boolean | true |
persistTraefikConfig | Has no effect. Hub’s startup code doesn’t read it, and Hub rewrites its Traefik files on every start. See Folder structure | boolean | false |
eventsTimeout | The time in minutes to wait for an action to complete before timing out (1 to 120) | integer | 5 |
maxBackups | The number of backups to keep per app (0 to 100). 0 means no limit is set; see Back up and prove the restore for what Hub still trims | integer | 0 |
advancedSettings | Show advanced options in the dashboard | boolean | false |
autoUpdates | Update the Hub stack automatically. This is the Auto-update stack switch in Settings | boolean | true |
settings.json accepts a few more keys that Hub doesn’t read from the file at
boot: domain, port, sslPort, postgresPort, and appsRepoUrl. Changing
them there has no effect. The public domain is assigned when you pair the
device, and the dashboard listens on port 5002 unless that port is in use.
listenIp and logLevel are also overridden, by the INTERNAL_IP and
LOG_LEVEL values that Hub’s compose file always sets. Inference and Hub Pool
keys, such as inferenceBackend and hubPoolEnabled, belong to Settings →
AI and Settings → Network — set them there.