> 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/2-0-6/documentation/agents/installing-agents/installing-agents-via-docker-compose.md).

# Installing Agents via Docker Compose

This guide explains how to install agents via Docker Compose.

## Prerequisites

* Docker and Docker Compose installed.
* A valid Connectware [license key](/2-0-6/documentation/installation-and-upgrades/licensing.md).

{% hint style="warning" %}
If multiple agents are running on the same machine, each agent must be assigned its own Docker volume. Otherwise, agents will overwrite each other’s persisted data, including username and password credentials.
{% endhint %}

## Procedure

1. Log in to the Cybus Docker registry. Enter the following command in your terminal:

{% code lineNumbers="true" %}

```sh
docker login registry.cybus.io
```

{% endcode %}

When prompted, enter the following credentials:

* **Username:** `license`
* **Password:** Your Connectware license key

2. Create a folder for your agent (e.g., `myAgent`).
3. Inside this folder, create a new file named `docker-compose.yml`.
4. Paste the following example configuration into your `docker-compose.yml` file. Replace `${IMAGE_TAG}` with the protocol-mapper agent image version you want to use (e.g., `2.0.6`).

{% code title="docker-compose.yml" lineNumbers="true" %}

```yaml
services:
  protocol-mapper-agent:
    image: registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
    environment:
      CYBUS_AGENT_MODE: distributed
      CYBUS_AGENT_NAME: myAgent
      CYBUS_HOSTNAME_INGRESS: localhost
      CYBUS_TRUST_ALL_CERTS: true
    volumes:
      - protocol-mapper-agent:/data
    restart: unless-stopped
    network_mode: host
    hostname: <some-suitable-hostname>
volumes:
  protocol-mapper-agent:
```

{% endcode %}

5. In your terminal, run the following command to start the agent:

{% code lineNumbers="true" %}

```sh
docker compose up -d
```

{% endcode %}

6. Optional: To run the agent with root permission, add `user: root` to the `docker-compose.yml` file.

{% code lineNumbers="true" %}

```yaml
services:
  protocol-mapper-agent:
    user: root
    image: registry.cybus.io/cybus/protocol-mapper:${IMAGE_TAG}
    # ...other configuration...
```

{% endcode %}

**Result**

The agent is now installed and running. To verify, use:

{% code lineNumbers="true" %}

```sh
docker ps
```

{% endcode %}

This command lists running containers. You should see `protocol-mapper-agent` in the output.


---

# 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/2-0-6/documentation/agents/installing-agents/installing-agents-via-docker-compose.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.