Test an Agent Locally

The Quick Start deploys your agent through the HiveMQ Platform, where you get fleet visibility, health monitoring, human feedback, and agent-to-agent messaging. Sometimes, though, you just want to run an agent definition on your own machine to see it cycle before you commit to a deployment.

This page shows you how to take an agent definition you downloaded from Act and run it in a single docker run command.

A locally run agent is invisible to the HiveMQ Platform. It does not appear in your fleet, health monitoring, or feedback views, and it cannot use human-in-the-loop (HITL) feedback, agent-to-agent (A2A) messaging, or persistent memory. Use this path for quick testing only. To run an agent for real, deploy it through the platform. See Quick Start.

Before You Start

Docker installed and running (install Docker).
An agent definition file. In the Act tab, open the agent and select Download to save its YAML (for example, mqtt-message-counter.yaml).
Provider keys your agent needs, commonly:
- OPENROUTER_API_KEY for LLM (large language model) reasoning
- SENDGRID_API_KEY for email actions

The One-Liner

Place your agent definition in your current directory, then run:

docker run --rm -it \
  -v "$(pwd)/<your-agent>.yaml:/agent.yaml:ro" \
  -e HIVEMQ_SANDBOX_MODE=true \
  -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
  -e SENDGRID_API_KEY="$SENDGRID_API_KEY" \
  ghcr.io/hivemq/hivemq-agentic-agent:latest \
  run /agent.yaml

Replace <your-agent>.yaml with the filename you downloaded. Add or remove -e flags to match the environment variables your agent uses. The image is public and requires no docker login.

Sandbox Mode Is On by Default Here

The command above sets HIVEMQ_SANDBOX_MODE=true, which puts the agent in Sandbox Mode: sense substages emit synthetic data (no MQTT broker, database, or source credentials needed), so the agent cycles end-to-end in seconds on any laptop.

Actuate handlers still fire for real in Sandbox Mode: emails send, Slack messages post, MQTT publishes happen. The runtime appends a disclosure to each so recipients know the upstream data was simulated. See Sandbox Mode.

To run against your real data sources instead, remove the sandbox line:

- -e HIVEMQ_SANDBOX_MODE=true \

You then need your MQTT brokers, databases, and APIs reachable from the container, with credentials passed through -e flags.

What You See

When the container starts, the runtime logs a few lines before the first cycle. It notes that it skips features that require the agent bus (feedback, A2A, fleet monitoring) because there is no orchestrator. Then it logs each cycle:

INFO  cycle 1 started
INFO  sense: collected 3 readings from mqtt-broker
INFO  reason: threshold exceeded — planning alert action
INFO  actuate: email sent to admin@example.com
INFO  cycle 1 complete (duration: 1.2s)

Press Ctrl+C to stop. The agent drains the current cycle, logs agent stopped, and exits cleanly.

Step-by-Step Walkthrough

1. Get the Agent Definition

In the Act tab, open the agent you want to test and click Download to save its YAML. Save it as, for example, mqtt-message-counter.yaml in a working directory.

2. Set Your Environment Variables

export OPENROUTER_API_KEY="sk-or-..."

If your agent sends email, also set the relevant key:

export SENDGRID_API_KEY="SG...."

Check the downloaded YAML for any ${VAR_NAME} tokens. Each one is an environment variable your agent needs.

3. Run the Agent

docker run --rm -it \
  -v "$(pwd)/mqtt-message-counter.yaml:/agent.yaml:ro" \
  -e HIVEMQ_SANDBOX_MODE=true \
  -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" \
  ghcr.io/hivemq/hivemq-agentic-agent:latest \
  run /agent.yaml

Docker pulls the image on the first run (a few hundred MB). Subsequent runs start in seconds.

4. Observe and Stop

Watch the cycle logs in your terminal. Press Ctrl+C to stop. The agent finishes its current cycle and exits with code 0.

What You Cannot Do Locally

A locally run agent is a single container with no orchestrator and no agent bus, so these features are unavailable:

Human-in-the-loop feedback: No controlled-action approvals.
Agent-to-agent messaging: Single container, single agent.
Persistent memory: The container is ephemeral; long-term memory needs a network with long-term storage.
Fleet visibility and audit history: The agent does not appear in the HiveMQ Platform.

When you need any of these, deploy the agent through the HiveMQ Platform instead. See Quick Start and Deploy an Orchestrator.

Troubleshooting

Image Pull Fails or Returns "unauthorized"

The image ghcr.io/hivemq/hivemq-agentic-agent:latest is public. You do not need a docker login. If the pull fails, check your network connection and confirm Docker is running. A 403 or 404 from the registry is usually transient. Retry after a moment.

Container Exits Immediately with a Non-Zero Code

The most common cause is a path mismatch in the volume mount. Make sure <your-agent>.yaml exists in $(pwd) (the directory where you run the command) and that the filename matches exactly, including the .yaml extension. Run ls -l *.yaml to confirm.

Environment Variables Not Reaching the Agent

Each environment variable your YAML references needs its own -e flag. Check the YAML for all ${VAR_NAME} tokens and add a matching -e VAR_NAME="$VAR_NAME" entry, or use --env-file .env and list them in a .env file.