# 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](/2-1-2/documentation/installation-and-upgrades/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=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](/2-1-2/documentation/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 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](/2-1-2/documentation/client-registry.md) process.

### Setting the Hostname

The hostname is displayed in the [Connectware UI](/2-1-2/documentation/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](/2-1-2/documentation/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.

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


---

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

```
GET https://docs.cybus.io/2-1-2/documentation/agents/installing-agents/installing-agents-via-docker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.