Quickstart: Docker Hub
The fastest way to run Wactorz — no repo clone needed. Everything runs in containers pulled straight from Docker Hub.
Prerequisite: Docker Desktop installed and running.
Which image
There are two, built from the same source and published under the same name:
| Tag | What it holds | When to use it |
|---|---|---|
waldiez/wactorz:latest, :<version> |
Wactorz and its integrations (the all extra). |
Agents that talk to APIs, Home Assistant, MQTT, chat platforms. This is the one the examples here use. |
waldiez/wactorz:ultra, :<version>-ultra |
The same, plus PyTorch (the CPU build), Ultralytics and OpenCV, the system libraries they load, a compiler, and GStreamer with its introspection data. | Vision agents (anything that imports cv2, torch or ultralytics), and the Reachy Mini catalogue agent, whose SDK has to build part of itself. |
The larger one is several times the size of the other, which is the reason there are
two. An agent that needs it fails in the small image when it imports cv2
(libGL.so.1: cannot open shared object file) or when pip tries to build a package that
ships no wheel. To switch, change the tag in compose.yaml and start again; the state
volume is the same for both.
The ultra image runs on Python 3.13, one release behind the other, because the Reachy
Mini SDK needs it. It has no GPU support: PyTorch in it is the CPU build.
Licences
Wactorz is Apache-2.0, and so is everything in the default image. The ultra image also
contains Ultralytics, which is licensed
under the AGPL-3.0, so the ultra image as a whole is distributed under its terms.
Using the ultra image, or Ultralytics through it, in a closed-source product or a hosted
service means meeting the AGPL-3.0 (offering the source of the whole to its users) or
holding an Ultralytics licence. Wactorz's own
code stays Apache-2.0 either way, and the default image has no such component.
The corresponding source is the source of this release at https://github.com/waldiez/wactorz (its tag, with the Dockerfile that builds the image) and Ultralytics' own at https://github.com/ultralytics/ultralytics. Every package in an image is listed with its licence in
/app/THIRD_PARTY.txt.
Option A: Terminal and Compose (recommended)
Works in any terminal, including the built-in terminal inside Docker Desktop.
1. Create a project folder
mkdir wactorz
cd wactorz
2. Make two secrets
The server will not start without an API key: it listens on the network inside its container, and anything that reaches it could otherwise drive your agents and spend your LLM budget. The broker needs a password for the same reason. Run this twice and keep both lines it prints — it uses the Wactorz image's own Python, so it works the same on Linux, macOS and Windows:
docker run --rm --entrypoint python waldiez/wactorz:latest -c "import secrets; print(secrets.token_hex(32))"
3. Create three files inside that folder
Windows tip: open Notepad, paste the content, then Save As — set Save as type to All Files and type the filename exactly as shown. This prevents Windows from secretly adding
.txtto the end.
mosquitto.conf
listener 1883
allow_anonymous false
password_file /mosquitto/data/passwd
persistence true
persistence_location /mosquitto/data/
log_dest stdout
compose.yaml (the broker is named by its tag here; the repository's own compose.yaml pins the build by digest, and is the one to copy the digest from)
name: wactorz
services:
mosquitto:
image: eclipse-mosquitto:2.1.2-alpine
container_name: wactorz-mosquitto
restart: unless-stopped
environment:
MQTT_USERNAME: ${MQTT_USERNAME:-wactorz}
MQTT_PASSWORD: ${MQTT_PASSWORD:?set MQTT_PASSWORD in .env}
# The password file is written from .env each time the broker starts, into
# its own volume, so changing the password is an edit to .env and a restart.
command:
- /bin/sh
- -c
- |
umask 077
mosquitto_passwd -b -c /mosquitto/data/passwd "$$MQTT_USERNAME" "$$MQTT_PASSWORD"
chown mosquitto:mosquitto /mosquitto/data/passwd
exec mosquitto -c /mosquitto/config/mosquitto.conf
ports:
- "127.0.0.1:1883:1883"
volumes:
- ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
- mosquitto-data:/mosquitto/data
networks:
- wactorz-net
healthcheck:
test: ["CMD-SHELL", "mosquitto_sub -u \"$$MQTT_USERNAME\" -P \"$$MQTT_PASSWORD\" -t '$$SYS/#' -C 1 -i hc -W 3"]
interval: 10s
timeout: 5s
retries: 5
wactorz:
image: waldiez/wactorz:latest
container_name: wactorz
restart: unless-stopped
env_file:
- .env
environment:
MQTT_HOST: mosquitto
MQTT_PORT: "1883"
INTERFACE: rest
ports:
- "127.0.0.1:8000:8000"
- "127.0.0.1:8888:8888"
networks:
- wactorz-net
depends_on:
mosquitto:
condition: service_healthy
networks:
wactorz-net:
volumes:
mosquitto-data:
The ports are published on this machine only (127.0.0.1). To reach the dashboard
from another device, remove 127.0.0.1: from the two wactorz lines; the API key
is what then keeps it yours.
.env — the two secrets from step 2, then the provider you want to use:
# ── Access ─────────────────────────────────────────────────────────────────────
API_KEY=paste-the-first-secret-here
MQTT_USERNAME=wactorz
MQTT_PASSWORD=paste-the-second-secret-here
# ── Anthropic (Claude) — default ─────────────────────────────────────────────
LLM_API_KEY=sk-ant-...
LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-4-6
# ── OpenAI ────────────────────────────────────────────────────────────────────
# LLM_API_KEY=sk-...
# LLM_PROVIDER=openai
# LLM_MODEL=gpt-4o
# OPENAI_URL= # optional: set to redirect to a compatible endpoint (Groq, Together, vLLM…)
# ── Ollama (local) ───────────────────────────────────────────────────────────
# LLM_PROVIDER=ollama
# LLM_MODEL=llama3
4. Start
docker compose up -d
Images are pulled automatically on first run.
5. Open
| URL | |
|---|---|
| Monitor UI | http://localhost:8888 — sign in with the API_KEY from .env |
| REST API | http://localhost:8000 — send it as the X-API-Key header |
To stop: docker compose down
Option B: Docker Desktop and Terminal
The same setup with docker run, in PowerShell.
Step 1 — Create a project folder
Use a new folder so the .env and mosquitto.conf paths are easy to copy into Docker commands:
mkdir wactorz
cd wactorz
Invoke-WebRequest `
-Uri "https://raw.githubusercontent.com/waldiez/wactorz/main/.env.template" `
-OutFile ".env.template"
Copy-Item .env.template .env
Step 2 — Edit .env
Make two secrets — run this twice and keep both lines it prints:
docker run --rm --entrypoint python waldiez/wactorz:latest -c "import secrets; print(secrets.token_hex(32))"
notepad .env
Fill in your LLM key and provider, put the first secret in API_KEY and the second
in MQTT_PASSWORD, and make sure these Docker-specific values are set:
API_KEY=paste-the-first-secret-here
MQTT_HOST=wactorz-mosquitto
MQTT_USERNAME=wactorz
MQTT_PASSWORD=paste-the-second-secret-here
PORT=8000
MONITOR_PORT=8888
Port conflict? On some Windows machines port
8888is reserved by a system service. If the monitor UI is unreachable, changeMONITOR_PORTto any free port (e.g.8887) and use that port in Step 4.
Step 3 — Start Mosquitto
[System.IO.File]::WriteAllText(
(Join-Path (Get-Location) "mosquitto.conf"),
"listener 1883`nallow_anonymous false`npassword_file /mosquitto/data/passwd`npersistence true`npersistence_location /mosquitto/data/`nlog_dest stdout`n",
[System.Text.UTF8Encoding]::new($false)
)
docker network create wactorz-net
docker volume create wactorz-mosquitto-data
docker run -d --name wactorz-mosquitto `
--network wactorz-net `
-p "127.0.0.1:1883:1883" `
--env-file "${PWD}\.env" `
-v "${PWD}\mosquitto.conf:/mosquitto/config/mosquitto.conf:ro" `
-v "wactorz-mosquitto-data:/mosquitto/data" `
eclipse-mosquitto:2.1.2-alpine `
/bin/sh -c 'umask 077; mosquitto_passwd -b -c /mosquitto/data/passwd "$MQTT_USERNAME" "$MQTT_PASSWORD" && chown mosquitto:mosquitto /mosquitto/data/passwd && exec mosquitto -c /mosquitto/config/mosquitto.conf'
If wactorz-net already exists, the network create line will error — that is OK.
Step 4 — Start Wactorz
docker run -d --name wactorz `
--network wactorz-net `
-p "127.0.0.1:8000:8000" `
-p "127.0.0.1:8888:8888" `
--env-file "${PWD}\.env" `
-e MQTT_HOST=wactorz-mosquitto `
waldiez/wactorz:latest
Open http://localhost:8888 and sign in with the API_KEY from .env.