> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/agents/installing-agents/installing-agents-via-docker.md).

# 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](/deployment/licensing.md) 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.

{% code lineNumbers="true" %}

```bash
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}
```

{% endcode %}

{% hint style="info" %}
Replace `${IMAGE_TAG}` with the protocol-mapper agent image version that matches your Connectware version, for example `2.6.1`. Replace `connectware.example.com` with the address of your Connectware server.
{% endhint %}

**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](/reference/environment-variables.md).

#### 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:

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

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

{% hint style="warning" %}
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](#network-mode).
{% endhint %}

### 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](/access/client-registry.md) process.

### Setting the Hostname

The hostname is displayed in the [Connectware UI](/data-flows/agents/monitoring-agents.md). By default, the Docker container ID (e.g., `d172c8c3667b`) is shown.

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

```bash
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:

```bash
docker run --user=root ...
```

## Security Configuration

### Enabling Mutual TLS (mTLS)

To use mutual TLS, set the environment variable:

```bash
-e CYBUS_USE_MUTUAL_TLS=true
```

For more information, see [Environment Variables](/reference/environment-variables.md).

### 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**

```bash
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/data-flows/agents/installing-agents/installing-agents-via-docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.