25. Relay Configuration

Relay can be configured using a configuration file. As with Cog, most of Relay’s configuration entries can be controlled via environment variables. For each key in the configuration file, the corresponding environment variable is the upper-cased key, prepended with RELAY_. Thus, the key max_concurrent can be overridden using the environment variable RELAY_MAX_CONCURRENT, and so on.


The sole exception to this is the Relay “execution env” setting. If used, this must be set in the configuration file; there is no corresponding environment variable.


An annotated example of a complete configuration file is kept in Relay’s GitHub repo here.


Controls what version of the Docker API should be used when interacting with Docker.

Defaults to 1.23


Encrypts MQTT traffic between Relay and Cog.

Defaults to false.


The host name or IP address of the Cog server.

Defaults to See also [COG_MQTT_HOST].


The MQTT listen port of the Cog server.

Defaults to 1883. See also [COG_MQTT_PORT].


Controls how often Relay refreshes its list of installed bundles and Docker images.

Valid time units are s (seconds), m (minutes), and h (hours).

Defaults to 15m. Consider reducing this interval to 1m or less when frequently updating bundles.


Path to the Cog server’s SSL certificate.

Enables certificate verification if set.


Shared secret between Cog and a given Relay.

Corresponds to the TOKEN argument used when creating a Relay via cogctl.


This is a required setting.


Controls how frequently Relay will remove unused Docker containers.

Uses the same time unit notation as [RELAY_COG_REFRESH_INTERVAL].

Defaults to 5m.


Controls how much memory (in megabytes) is allocated to each Docker container Relay uses to execute a command.

Docker requires a minimum of 4MB per container.

Defaults to 16.


Docker image registry host name.

Defaults to index.docker.io.

Email address credential used to access an authenticating Docker registry.
Username credential used to access an authenticating Docker registry.
Password credential used to access an authenticating Docker registry.


RELAY_DOCKER_REGISTRY_EMAIL, RELAY_DOCKER_REGISTRY_USER, and RELAY_DOCKER_REGISTRY_PASSWORD are required when using Relay with private Docker repositories or private registries.


Location of Docker’s Unix socket. Must begin with either unix:// or tcp://.

Defaults to unix:///var/run/docker.sock.

Controls whether or not Relay uses environment variables to set up its Docker connection. If true, Relay will use the environment variables DOCKER_HOST, DOCKER_TLS_VERIFY, and DOCKER_CERT_PATH to connect.


This is a required setting when using Relay with Docker running inside docker-machine.


Comma separated list of command execution engines. Valid engine names are:

  • native: Runs commands distributed as native executables installed directly on the Relay host.

  • docker: Runs commands distributed as Docker container images

    Defaults to native,docker. At least one engine must be enabled.

UUID assigned to the Relay.


This is a required setting.


Controls if Relay logs in plain text or JSON.

Defaults to false.


Controls logging verbosity.

Defaults to info.


Controls where Relay sends its log output. Valid values are:

  • Any valid file path

  • stdout or console

  • stderr

    Defaults to console.


Maximum number of concurrent command invocations.

Defaults to 16.


Controls whether or not Relay pulls dynamic configuration for installed command bundles from Cog.

If set to true, Relay will retrieve dynamic configuration files from the Cog server, instead of relying on files placed on the Relay host itself. Configuration changes can be submitted to Cog via the API, and will be picked up by Relay when it checks in periodically. See [RELAY_MANAGED_DYNAMIC_CONFIG_INTERVAL].

Defaults to true.

File path used to store dynamic bundle configuration files. A missing or empty value disables this feature. Nonexistent paths will be created on first use.

Controls how often Relay polls Cog for dynamic configuration updates.

Uses the same time units as [RELAY_COG_REFRESH_INTERVAL].

Defaults to 5s.


This setting only takes effect when managed dynamic configuration is enabled.