Deployment

Wactorz supports three deployment modes:

Mode When to use
Docker Hub New users; no repo clone needed — just Docker Desktop
Full Docker Full stack via git clone; everything in containers
Home Assistant add-on Home Assistant OS or Supervised installs

Docker Hub

The fastest way to get started — no repo clone or Python needed. See the dedicated guide:

→ Quickstart: Docker Hub

The image comes in two sizes: waldiez/wactorz:latest, and waldiez/wactorz:ultra with PyTorch, Ultralytics, OpenCV and what the Reachy Mini SDK needs. Which image says when the larger one is the one to pull.


Full Docker (compose.yaml)

Prerequisites

Steps

git clone https://github.com/waldiez/wactorz
cd wactorz
cp .env.template .env
nano .env           # set LLM_API_KEY at minimum

# Python stack (recommended starting point)
docker compose --profile python up -d

Open http://localhost:8888 (monitor UI) or http://localhost:8000 (REST API).

Compose builds the image from the checkout. For vision agents or the Reachy Mini agent, build the larger one (which image) by setting WACTORZ_FLAVOUR=ultra in .env, then:

docker compose --profile python up -d --build

Both ask for the API key. With API_KEY blank in .env, the stack generates one on first start and keeps it in a volume. Read it with docker compose exec wactorz-python cat /run/wactorz/api_key, or follow the one-time sign-in link in docker compose logs wactorz-python. Set API_KEY in .env to choose your own.

Services

Default profile (no flag) starts Mosquitto only. Add --profile flags to bring up more services.

Profile Service Internal address External port
(all) mosquitto mosquitto:1883 127.0.0.1:1883, and :8883 (TLS)
python wactorz-python wactorz-python:8000 127.0.0.1:8000 (REST API)
python monitor UI wactorz-python:8888 127.0.0.1:8888
python prometheus wactorz-prometheus:9090 127.0.0.1:9090
python alertmanager alertmanager:9093 127.0.0.1:9093
full home-assistant homeassistant:8123 127.0.0.1:8123
sandbox wactorz-sandbox — none: it dials the broker

Every port except the broker's TLS one is published to this host only. Reach the dashboard and the API from elsewhere through a TLS proxy; HA_EXTERNAL_BIND=0.0.0.0 opens Home Assistant to the network, and MQTT_EXTERNAL_BIND=0.0.0.0 the plain broker port.

Each container has a ceiling on memory and on process ids, so one that leaks is restarted instead of exhausting the host. The app's are settings, because what an agent loads varies: WACTORZ_MEM_LIMIT (default 8g), WACTORZ_PIDS_LIMIT (4096, threads included) and WACTORZ_CPUS (cores; 0, the default, is no limit). An app container that restarts under a heavy agent, with OOMKilled in docker inspect, needs WACTORZ_MEM_LIMIT raised. Home Assistant's container has none.

# Python stack (most common)
docker compose --profile python up -d
# Open: http://localhost:8888  (monitor UI)  http://localhost:8000  (REST API)

The sandbox node

Code the model writes runs in a container of its own, holding none of main's credentials: wactorz-sandbox starts with the app, under the python, full and sandbox profiles, and main sends the model's code there once it reports. WACTORZ_MODEL_CODE_NODE=main in .env keeps the code on main instead, and leaves the sandbox container idle.

sandbox-env, a one-shot, writes the node what /deploy writes any node: its name, the broker, its signing key and broker account, and the CA with TLS. It writes them into a volume that only wactorz-sandbox mounts. It runs again on every docker compose up, so after the broker's CA or the node's account changes, docker compose --profile python --profile sandbox up -d hands the node the new ones. The sandbox container mounts neither .env nor ./state, and its network has the broker on it and nothing else, so main's API and Home Assistant are out of its reach. The packages its agents install go into its own volume. It is limited by WACTORZ_SANDBOX_MEM_LIMIT (default 2g) and WACTORZ_SANDBOX_PIDS_LIMIT (1024). See a node on main's own machine for what goes there and what stays on main.

Health probes

Both servers answer the same probes, with no key:

On Kubernetes, point each probe at its own path, and give liveness a start period that covers startup:

livenessProbe:
  httpGet: { path: /livez, port: 8888 }
  initialDelaySeconds: 60
  periodSeconds: 30
readinessProbe:
  httpGet: { path: /readyz, port: 8888 }
  periodSeconds: 10

Never use /ready for liveness. A broker outage would then restart every replica in a loop, and restarting fixes nothing the broker's return would not. See the API reference for what each check means.


Home Assistant add-on

Use the add-on when Wactorz should run inside Home Assistant OS or a Supervised Home Assistant install. The add-on uses prebuilt multi-arch images from GHCR, so Supervisor updates pull an image instead of building Wactorz on the device.

See ha-addon/wactorz/README.md (or ha-addon/wactorz-ultra/README.md for the ML variant) for install and local testing details.


Environment variables

See .env.template for the full annotated list. The most important ones:

Variable Default Notes
LLM_PROVIDER anthropic anthropic / openai / ollama / gemini / nim
LLM_MODEL claude-sonnet-4-6 Any model ID
LLM_API_KEY (required for cloud providers) API key — not needed for Ollama only
OPENAI_URL (unset) Redirect openai provider to a compatible endpoint (Groq, Together, vLLM, etc.)
LLM_COST_LIMIT_USD 0 (disabled) Hard spend cap per period — set 0 to disable
LLM_COST_LIMIT_PERIOD monthly Reset period: daily, weekly, or monthly
MQTT_HOST localhost Use mosquitto inside Docker
MQTT_PORT 1883
MQTT_USERNAME wactorz Broker username. Blank only for a broker of your own that takes anonymous connections
MQTT_PASSWORD (none) Broker password. Required by docker compose — the bundled broker refuses anonymous connections and compose refuses to start without it, rather than coming up open. Its password file is generated from these at container start, so there is no mosquitto_passwd step
PORT 8000 Python REST API listen port
WS_PORT / MONITOR_PORT 8888 Web UI / monitor server port
WACTORZ_STATE_DIR ./state Where all durable state lives — SQLite database, per-agent pickles, MQTT outbox. Set an absolute path when the working directory isn't durable (a container without a mounted volume loses it on restart); the Home Assistant add-on pins /data/state. wactorz-reset reads the same variable, so a wipe targets whatever the app is using
WACTORZ_DOCUMENT_DIRS your Documents folder The folders an agent that converts files (the doc-to-pptx agent) may read from and write to, separated like PATH. Anything under WACTORZ_STATE_DIR stays out of reach whatever is named here. See Doc → PPTX agent
WACTORZ_PIP_ALLOW — Packages an agent may have installed without the operator being asked, separated by commas or spaces, in addition to the built-in list. Anything else is asked about on the dashboard first; /packages shows the whole list. See the packages an agent installs
WACTORZ_PIP_INDEX_URL — The package index every install uses, such as a private mirror. Unset, pip uses PyPI
WACTORZ_MODEL_CODE_NODE sandbox if there is one The node code the model writes runs on when its spawn names none. Unset, it is the node named sandbox whenever one exists (see a node on main's own machine), and main otherwise. main keeps such code on main
WACTORZ_MODEL_CODE_ON_MAIN ask While the model's code goes to a node, what happens to a spawn the model wrote that names main: ask on the dashboard, allow, or never
WACTORZ_AGENTS — Agents this deployment brings, as package.module:attr targets (an Actor subclass or a function declared with @wactorz.agent), comma separated. Supervised at startup beside the built-ins; see Bringing your own agents
WACTORZ_PIPELINES — Pipelines this deployment brings, as package.module:attr targets of what wactorz.pipeline() returned, comma separated; their steps, schedule and rules are supervised at startup
WACTORZ_HA_AGENTS auto Whether the Home Assistant agents start: auto starts them when HA_URL and HA_TOKEN are set, on and off decide outright
WACTORZ_MINIMAL 0 Start only the monitor, the dashboard and the agents this deployment brings: no orchestrator, catalogue or installer, so no model is needed. Same as wactorz --minimal
WACTORZ_ORCHESTRATOR — What answers chat, as one package.module:attr target: an object implementing wactorz.Orchestrator, or a class or factory called with the actor registry to build one. In place of main (the default when main runs) and of the model-free orchestrator of the minimal profile; a target that cannot be loaded or is not an orchestrator refuses to start. See Your own orchestrator in the library guide
WACTORZ_TZ (unset) Override the timezone used in agents' date/time context (e.g. Europe/Athens). Precedence: a user's pref_timezone fact > WACTORZ_TZ > standard TZ > host local zone. Blank or unknown values fall through to the next candidate
WACTORZ_LOG_FORMAT text json writes each log record as one JSON object on one line (JSON Lines), to the console and to wactorz.log, for a collector that parses logs: fields ts (UTC), level, logger, message, and exception holding the whole traceback. Redaction applies as in text. The dashboard's log view is unaffected. A node reads the setting from its own environment
WACTORZ_RETENTION_CHAT_DAYS 365 Days chat history is kept; 0 keeps it for ever. An attached file goes with the last message that refers to it, or a day after upload if it was never sent
WACTORZ_RETENTION_TIMESERIES_DAYS 365 Days sensor readings, detections, Home Assistant state changes and actuations are kept; 0 keeps them for ever. The time-series collector agent's own retention_days applies too, and the shorter window holds
WACTORZ_RETENTION_OUTBOX_DAYS 7 Days an MQTT message the broker never accepted stays in the outbox; 0 keeps it until delivered. Once expired it is not retried after a restart, and the log names its topic. A command — a non-retained message under nodes/ or agents/by-name/, such as a spawn, a stop or a task for an agent — expires after 10 minutes whatever this says, since replaying one later would undo or repeat what has happened since; a node's retained desired_state follows this setting
WACTORZ_RETENTION_METRICS_DAYS 7 Days the per-minute metrics history of every agent and node is kept (/api/history/...); 0 keeps it for ever. A metrics reset clears it
WACTORZ_BRIDGE_CALLS_PER_MINUTE 60 Model calls main answers for one node's agents a minute, after a burst of as many; past it a call is refused at once with an error saying why, and the dashboard says so the first time. Read on main; 0 sets no limit
WACTORZ_BRIDGE_HISTORY_PAGES_PER_MINUTE 600 Pages of main's history (query_ts and the like on a node) main answers for one node a minute, after a burst of as many; past it a read fails, saying why. Read on main; 0 sets no limit
WACTORZ_MIGRATION_MAX_STATE_BYTES 8388608 Largest agent state a /migrate ships, as JSON; a larger one is refused before the agent stops, and --force does not override it. Set on main, which sends it to the node it asks; 0 sets no limit
WACTORZ_MIGRATION_MAX_BLOB_BYTES 67108864 Largest total of an agent's blobs (models, arrays, bytes) a /migrate carries beside its state, and the largest blob a machine accepts from another; over it, the agent stays where it was. Read on main and on each node; 0 sets no limit
WACTORZ_ARTIFACT_MAX_BYTES 268435456 Largest artifact (a model kept with wactorz-artifacts) main sends a node and a node accepts. A spawn naming a larger one is refused before it is sent. Read on main and on each node; 0 sets no limit
WACTORZ_NODE_ARTIFACT_CACHE_BYTES 1073741824 How much of the artifacts it has fetched a node keeps. Past it, those no agent on the node names are deleted, the least recently used first; one an agent names is kept whatever the total. Read on each node; 0 keeps everything
PROMETHEUS_EXTERNAL_PORT 9090 Prometheus host port
ALERTMANAGER_EXTERNAL_PORT 9093 Alertmanager host port
ALERT_WEBHOOK_URL (none) Compose only: where Alertmanager POSTs alerts. Unset, alerts are listed on its page and sent nowhere. See prometheus.md
ALERT_WEBHOOK_TOKEN (none) Compose only: sent to that webhook as a bearer token
HA_EXTERNAL_BIND / HA_EXTERNAL_PORT 127.0.0.1 / 8123 Where compose publishes Home Assistant (profile full). 0.0.0.0 opens it to the network
WACTORZ_MEM_LIMIT 8g Compose only: the app container's memory ceiling
WACTORZ_PIDS_LIMIT 4096 Compose only: the app container's ceiling on processes and threads
WACTORZ_CPUS 0 Compose only: cores the app container may use; 0 is no limit
PROMETHEUS_SCRAPE_INTERVAL 15s Global Prometheus scrape interval
PROMETHEUS_MONITOR_MOSQUITTO 1 Enable Mosquitto TCP availability probe
DEPLOY_TARGETS (unset) Comma-separated remote node names /deploy may bootstrap; each needs a DEPLOY_<NODE>_* block — see Remote nodes
DEPLOY_KNOWN_HOSTS <WACTORZ_STATE_DIR>/known_hosts Where learned SSH host keys are stored
DEPLOY_STRICT_HOST_KEYS 0 1 = never learn a host key on first contact; unknown hosts are refused

Backing up and moving an install

wactorz-state writes a state directory to one archive, and puts one back:

wactorz-state export                       # wactorz-state-<date>-<time>.tar.gz, here
wactorz-state export backup.tar.gz --no-secrets
wactorz-state import backup.tar.gz         # into WACTORZ_STATE_DIR, or ./state
wactorz-state import backup.tar.gz --replace

Both read WACTORZ_STATE_DIR as the server does; --state-dir names another directory.

A node's state is moved the same way, on the node: wactorz-state export --state-dir ~/wactorz/state, and an import there with the node stopped. The Home Assistant add-on's state is in /data/state, which Home Assistant's own backups already include.

Models kept on main

wactorz-artifacts keeps models and other large files that agents load, each under a name and a version:

wactorz-artifacts add detector.onnx imu-detector --meta dataset=imu-2026 --meta auc=0.93
wactorz-artifacts add yolo-model/ yolo                       # a directory, kept as one archive
wactorz-artifacts add model.pt imu-detector --format state_dict
wactorz-artifacts list                                       # every name and version
wactorz-artifacts show imu-detector:latest                   # one version, as JSON
wactorz-artifacts remove imu-detector:1                      # one version
wactorz-artifacts remove imu-detector --every-version
wactorz-artifacts verify                                     # stored files still match their hashes
wactorz-artifacts activate imu-detector:3 --reason "auc 0.95"  # the version agents serve
wactorz-artifacts shadow imu-detector:4                      # one on trial beside it
wactorz-artifacts promote imu-detector                       # the shadow becomes active
wactorz-artifacts clear shadow imu-detector                  # unset a pointer

SSH key management

Wactorz reaches remote machines over SSH when bootstrapping an edge node with /deploy. Key auth is preferred over a password — generate a dedicated deploy key:

ssh-keygen -t ed25519 -C "wactorz-deploy" -f ~/.ssh/wactorz_deploy -N ""

# Authorise on the target host
ssh-copy-id -i ~/.ssh/wactorz_deploy.pub -p 22 pi@192.168.1.50

Then point the node's deploy target at it in .env:

DEPLOY_TARGETS=rpi-kitchen
DEPLOY_RPI_KITCHEN_HOST=192.168.1.50
DEPLOY_RPI_KITCHEN_USER=pi
DEPLOY_RPI_KITCHEN_KEY=~/.ssh/wactorz_deploy
DEPLOY_RPI_KITCHEN_BROKER=192.168.1.10

Credentials are read from here and never from chat — /deploy takes a node name and nothing else. Host keys are verified on every connection, learned on first contact unless DEPLOY_STRICT_HOST_KEYS=1. Full details in Remote nodes.


Updating Home Assistant integration

Wactorz can send REST commands to Home Assistant and receive automations.

# infra/homeassistant/configuration.yaml
rest_command:
  wactorz_chat:
    url: "http://wactorz-python:8000/api/chat"
    method: POST
    content_type: "application/json"
    # The endpoint reads `message`, plus an optional `agent_name` that defaults
    # to the orchestrator. Add `"agent_name": "<name>"` to address one agent.
    payload: '{"message":"{{ message }}"}'

Set HA_URL and HA_TOKEN in .env.


Connecting to an existing Home Assistant instance

If you already have Home Assistant running (in Docker or elsewhere), point Wactorz at it via .env:

# .env
HA_URL=http://192.168.1.x:8123   # or http://homeassistant.local:8123
HA_TOKEN=eyJ...                  # Long-lived access token from HA → Profile → Security

Then start only the Wactorz stack (no embedded HA):

docker compose --profile python up -d

The full profile (docker compose --profile full up -d) starts a fresh Home Assistant container alongside Wactorz on the same Docker network — useful for a clean dev environment, not for connecting to an existing production HA.

Home Assistant OS / Supervised users — use the Wactorz HA addon instead. It runs inside the Supervisor and connects to your existing HA instance automatically.