Skip to main content
Version: Beta

Configuration reference

This is the complete list of the launch options that control how the Companion server starts.

On a headless or Docker install these are set in a config.yaml file (/companion/config.yaml in the Docker image, /etc/companion/config.yaml on CompanionPi), using the key in the Key column below. On CompanionPi the config-tool edits this file for you; in the Docker image you edit it by hand and the entrypoint applies it on startup. The same options can be passed as cli flags or environment variables when running the server manually.

For guidance on what these do and when to change them, see Server configuration.

Network​

adminPort​

number · default 8000 · cli --admin-port

TCP port the web admin interface and API listen on. Default 8000.

adminInterface​

string · cli --admin-interface

Bind the admin interface to the first IPv4 address of this named network interface (e.g. eth0). Leave unset to use a bind address instead.

adminAddress​

string · cli --admin-address

IP address to bind the admin interface to. Leave unset to bind to all interfaces (0.0.0.0 / ::). Cannot be combined with a bind interface.

trustedProxies​

string · cli --trusted-proxies · env COMPANION_TRUSTED_PROXIES

Use this when Companion runs behind a reverse proxy, so the real visitor IP is detected instead of the proxy's. Set to 'loopback', or a comma/semicolon separated list of proxy IP addresses or subnets to trust.

disableIpv6​

boolean · default false · env DISABLE_IPV6

Disable IPv6 support. When enabled the various api and web interface ports in Companion bind to IPv4 (0.0.0.0) by default instead of ::.

Logging​

logLevel​

one of error, warn, info, debug, silly · cli --log-level

How verbose console logging is. One of error, warn, info, debug, silly. Leave unset for the default (info).

Syslog​

syslogEnable​

boolean · default false · cli --syslog-enable

Forward logs to a syslog server. The remaining syslog options only apply when this is enabled.

syslogHost​

string · cli --syslog-host

Hostname or IP of the syslog server to write to. Default localhost.

syslogPort​

number · cli --syslog-port

Port on the syslog server to write to. Default 514.

syslogTcp​

boolean · default false · cli --syslog-tcp

Use TCP transport for syslog instead of the default UDP.

syslogLocalhost​

string · cli --syslog-localhost

Hostname this machine reports to the syslog server. Leave unset to use the system hostname.

Security​

enableShellCommandSupport​

boolean · default false · cli --enable-shell-command-support · env COMPANION_ENABLE_SHELL_COMMAND_SUPPORT

Allow running shell commands on this computer (e.g. the internal "run shell command" action). Disabled by default.

enableRestrictedModules​

boolean · default true · cli --enable-restricted-modules · env COMPANION_ENABLE_RESTRICTED_MODULES

Allow loading modules otherwise held back for safety, e.g. importing custom modules from remote (non-loopback) clients. Enabled by default.

Paths​

extraModulePath​

string · cli --extra-module-path

An additional directory to search for in-development modules to be loaded from.

Advanced​

notifications​

boolean · default true · cli --no-notifications

Show version-related notifications in the admin UI header. Enabled by default.

installName​

string · cli --install-name · env COMPANION_INSTALL_NAME

A fixed name for this Companion installation. When set it overrides and locks the value in the admin UI, so it cannot be changed there and survives database resets. Leave unset to manage the name from the UI.

Server-only options​

These are set by the launcher or container entrypoint rather than the config.yaml file, so they are only available as cli flags.

  • --config-dir <path> — Directory used to store configuration and data. The default varies by platform.
  • --list-interfaces — List the available network interfaces that can be used for the admin bind interface, then exit.