Deploy an Orchestrator

An orchestrator is the engine that runs your agents. The Docker orchestrator runs agents as containers on your own infrastructure, locally alongside your brokers, so the agents sit close to the data they act on. It requires Docker on the host.

The orchestrator is outbound-only: it connects out to the HiveMQ Platform to receive its agents and report health. The HiveMQ Platform never calls into your infrastructure.

Add and Enroll an Orchestrator

You enroll an orchestrator either from a network’s Orchestrators section or as part of the deploy wizard when you choose a new or not-yet-enrolled orchestrator. Both paths use the same enrollment flow.

Add and enroll an Orchestrator from a network:

  1. Open the Act tab, then Networks, and select your network.

  2. In the Orchestrators section, click Add orchestrator.

  3. Enter a Name for the orchestrator, then continue to Connect your orchestrator.

  4. Click Copy command, then run the Docker enrollment command on the host where you want the orchestrator to run.

  5. Wait while the page shows Waiting for first heartbeat…. The orchestrator must connect before you can finish.

The enrollment command carries a short-lived registration token. The page shows a token-expiry countdown and a Regenerate token button if the token expires before the orchestrator connects.

How Enrollment Works

When you run the command, the orchestrator connects to the HiveMQ Platform and generates its own certificates during registration. It then persists them so it can reconnect on later restarts without re-enrolling. You do not download, place, or manage any certificate files. Registration handles them for you.

The Orchestrator Detail Page

Open an orchestrator from its network’s Orchestrators section. The header shows the orchestrator’s name, type, network, status, communication, and labels.

Header actions:

  • Show enrollment instructions: Re-displays the Docker enrollment command, the same one shown during the wizard. Use this action to re-run enrollment on a host.

  • Edit: Change the orchestrator’s Name and Labels (for example env=prod).

Sections:

  • Health & Performance: The orchestrator’s live operational metrics:

    Metric What it Shows

    Status

    The orchestrator’s overall health, for example Healthy.

    Uptime

    The percentage of time the orchestrator has stayed connected and checking in.

    Avg CPU

    Average CPU usage on the orchestrator, as a percentage.

    Avg Memory

    Average memory usage on the orchestrator, as a percentage.

    Last Seen

    When the orchestrator last checked in with the HiveMQ Platform.
    CPU and memory are reported for the orchestrator (the engine that runs your agents), not for individual agents. There is no per-agent CPU or memory metric.

  • Agents: A table of the agents running on this orchestrator (Name, Started, Status). Select a row to open the agent.

The Delete orchestrator button is at the bottom. Unlike a network, you can delete an orchestrator directly through an enabled confirmation. The dialog warns that after removal, the platform no longer manages any agents deployed on the orchestrator.

Reference: Running the Docker Orchestrator

The enrollment wizard fills the values below into the docker run command for you. Copy the command from the wizard rather than assembling it by hand. It already contains the correct Platform URL and a single-use registration token.

docker run -d \
  --name hivemq-agentic-orchestrator \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v hivemq-agentic-orch-state:/var/lib/hivemq-agentic \
  -e CONTROL_PLANE_URL=https://<your-platform-url> \
  -e HIVEMQ_AGENTIC_REGISTRATION_TOKEN=<token-from-wizard> \
  ghcr.io/hivemq/hivemq-agentic-orch-docker:latest \
  orchestrator

The orchestrator argument starts the Docker orchestrator in fleet-management mode.

Environment Variables

Variable Required Description

CONTROL_PLANE_URL

Yes

URL of the HiveMQ Platform the orchestrator connects to.

HIVEMQ_AGENTIC_REGISTRATION_TOKEN

First boot

Single-use registration token from the enrollment wizard. Not required on later restarts once the state directory is populated.

HIVEMQ_AGENTIC_STATE_DIR

No

Path to the persistent state directory (default /var/lib/hivemq-agentic). Mount a Docker named volume here so the orchestrator’s certificates survive restarts and it does not have to re-enroll.

Docker Socket Requirement

The orchestrator creates and removes agent containers through the Docker Engine API, so it needs access to the Docker socket:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock
Platform Socket path

Linux

/var/run/docker.sock

macOS (Docker Desktop)

/var/run/docker.sock

Windows

//./pipe/docker_engine

On Linux, the user that runs the orchestrator must be in the docker group, or the container must run as root.

Supply LLM Keys and Secrets to Agents

Templates do not store LLM (large language model) API keys and similar secrets. Prefix them with AGENT_ on the orchestrator, and the orchestrator forwards them into each agent container with the prefix stripped. For example, the orchestrator delivers AGENT_OPENROUTER_API_KEY to the agent as OPENROUTER_API_KEY:

docker run -d \
  --name hivemq-agentic-orchestrator \
  -e AGENT_OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
  -e AGENT_ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  # ... plus the volume, socket, CONTROL_PLANE_URL, and token flags above
  ghcr.io/hivemq/hivemq-agentic-orch-docker:latest \
  orchestrator

You can also supply per-deployment values through network tools or template parameters at deploy time.

Next Steps