# Installing Agents via Docker

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

## Prerequisites

* Docker is installed on your system.
* Connectware [license key](https://docs.cybus.io/2-1-0/documentation/installation-and-upgrades/licensing) 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=localhost \
  -e CYBUS_TRUST_ALL_CERTS=true \
  -v /tmp/cybus:/data \
  --restart unless-stopped \
  --net=host \
  --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 (e.g., `2.1.0`).
{% 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](https://docs.cybus.io/2-1-0/documentation/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:

```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 machine, each agent must use its own Docker volume. Otherwise, agents will overwrite each other's credentials.
{% 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](https://docs.cybus.io/2-1-0/documentation/client-registry) process.

### Setting the Hostname

The hostname is displayed in the [Connectware UI](https://docs.cybus.io/2-1-0/documentation/agents/monitoring-agents). 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](https://docs.cybus.io/2-1-0/documentation/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**

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

### Agent Container

The agent container does not require any incoming TCP/IP ports. It initiates all necessary outbound connections to the Connectware server.

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