Installing Agents via Docker

How to install agents using Docker.

This page explains how to install and configure agents using the Docker CLI.

Prerequisites

• Docker is installed on your system.

• Connectware license key is available.

Installation

1. Run the agent container. In the following example, we install an agent named myAgent that persists data to /tmp/cybus on the host system.

docker run \
  -e CYBUS_AGENT_MODE=distributed \
  -e CYBUS_AGENT_NAME=myAgent \
  -e CYBUS_HOSTNAME_INGRESS=connectware.example.com \
  -e CYBUS_TRUST_ALL_CERTS=true \
  -v /tmp/cybus:/data \
  --restart unless-stopped \
  --network=bridge \
  --hostname=${HOSTNAME} \
  registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}

Replace ${IMAGE_TAG} with the protocol-mapper agent image version that matches your Connectware version, for example 2.6.0. Replace connectware.example.com with the address of your Connectware server.

Result: The agent is installed and running.

Configuration

Environment Variables

You can configure the agent using environment variables. For a comprehensive list of available environment variables, see Environment Variables.

Required Environment Variables

Environment Variable	Description
CYBUS_AGENT_MODE	Must be set to distributed to run in agent mode.
CYBUS_AGENT_NAME	Unique identifier for this agent instance.
CYBUS_HOSTNAME_INGRESS	IP address or hostname of the Connectware server.

Optional Environment Variables

Environment Variable	Default Value	Description
CYBUS_MQTT_USERNAME	<agentName>	Authentication username for Connectware.
CYBUS_DATAPLANE_SCHEME	mqtt	MQTT connection scheme (mqtts or mqtt).
CYBUS_DATAPLANE_PORT	MQTT 1883, MQTTS 8883	Port number for MQTT connection.

Persisting Agent Credentials

To ensure your agent's credentials persist across container restarts and system reboots, mount a Docker volume to the /data path:

docker volume create agent-data
docker run -v agent-data:/data ...

The agent will automatically store and retrieve credentials from this volume.

If multiple agents are running on the same host, each agent must use its own Docker volume. Otherwise, agents will overwrite each other's credentials. Run them with bridge networking. See Network Mode.

Alternative: Setting a Password

As an alternative to generating credentials locally, you can set the CYBUS_PROTOCOL_MAPPER_PASSWORD environment variable. This is useful if the agent is managed by the same orchestration tool as your central Connectware instance.

In most cases, we recommend using local credentials stored in a volume and authorized through the client registration process.

Setting the Hostname

The hostname is displayed in the Connectware UI. By default, the Docker container ID (e.g., d172c8c3667b) is shown.

To display a custom hostname, use the --hostname flag:

docker run --hostname=${HOSTNAME} ...

The ${HOSTNAME} environment variable may be available on your system, or you can specify it manually.

Running with Root Permissions

By default, agents run as an unprivileged user. To run with root privileges (required for certain protocols like USB access or promiscuous network mode), add the --user=root parameter:

docker run --user=root ...

Security Configuration

Enabling Mutual TLS (mTLS)

To use mutual TLS, set the environment variable:

-e CYBUS_USE_MUTUAL_TLS=true

For more information, see Environment Variables.

Mounting Certificates

Mount your certificates as volumes. By default, the agent looks for certificates in these locations (configurable via environment variables):

Environment Variable	Default Path
AGENT_KEY	/connectware/certs/client/tls.key
AGENT_CERT	/connectware/certs/client/tls.crt
CA	/connectware/certs/ca/ca-chain.pem

Example

docker run \
  -v /path/to/certs:/connectware/certs \
  ...

Network Requirements

Communication from the agent to the Connectware server is unidirectional, simplifying firewall rules and increasing security.

Network Mode

Run agents with --network=bridge. Every agent binds port 8888 for its health probe and port 9184 for its metrics endpoint. In bridge mode each agent keeps those ports to itself, so any number of agents can run on the same host. Agents using --network=host share the host's ports, so only the first one to start binds them and the rest fail to start.

With bridge networking, localhost refers to the container, not the host. Set CYBUS_HOSTNAME_INGRESS to an address that reaches Connectware from inside the container. If Connectware runs on the same host, use the host's IP address.

Agent Container

The agent container does not require any incoming TCP/IP ports. It initiates all necessary outbound connections to the Connectware server. The health probe on port 8888 and the metrics endpoint on port 9184 bind inside the container and need no inbound firewall rule.

Outbound Connections

Ensure the following outbound TCP/IP connections are allowed from the agent's network:

• 443/tcp (HTTPS): For secure web communication

• One of the following:

  • 1883/tcp (MQTT): If using unencrypted MQTT

  • 8883/tcp (MQTTS): If using encrypted MQTT

• One of the following:

  • 4222/tcp: If using mTLS authentication

  • 4223/tcp: If using username & password authentication

The choice between MQTT and MQTTS depends on your CYBUS_DATAPLANE_SCHEME setting.

Connectware Server

No special inbound firewall rules are required on the Connectware server, as the agent initiates all connections.