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:
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
- Docker + Compose plugin
LLM_API_KEY(Anthropic / OpenAI) or a local Ollama instance
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:
/health(also/healthz,/livez) is liveness. It fails only when the process cannot answer, which is what the compose files and the image'sHEALTHCHECKrestart on./ready(also/readyz) is readiness. It answers503while the agents start or stop, and while the broker or the database is unreachable.
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_EXTENSIONS |
— | Installed packages whose extensions, agents and pipelines are loaded: distribution names, comma separated, or * for all. Unset loads none, and each package left out is named once in the log and on the dashboard. What Wactorz ships always loads, and so do targets in WACTORZ_AGENTS and WACTORZ_PIPELINES. A node has its own list, DEPLOY_<NODE>_EXTENSIONS; see Extensions |
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/, agents/at/ 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 |
WACTORZ_POLICY_CHECK_S |
600 |
How often main holds each shadow trial against its model's promotion policy, in seconds (docs/design/promotion-policy.md); the first check comes a minute after main starts. A trial is days long, so a few minutes is plenty; set it short to watch a test promote |
WACTORZ_DRIFT_CHECK_S |
600 |
How often the drift agent reads a model's two windows and runs its tests, in seconds (docs/design/drift.md), unless it was spawned with its own check_s; the first check comes a minute after it starts. A window is a day long, so a few minutes is plenty |
WACTORZ_DATA_RETENTION_DAYS |
0 |
How many days of recorded readings main keeps under <state>/data/ (docs/design/data-storage.md). Past it, an hour of a source is removed a few times a day, unless a stored model says it was trained on it. 0 keeps everything. wactorz-data sweep --dry-run says what a retention would remove |
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.
- What it holds: the database, each agent's state file and blobs, uploads, the models kept with
wactorz-artifacts, the install's id, the nodes' SSH host keys and, unless--no-secretsis given, the install's keys:node_signing.key, which every node checks main's messages against, and the broker's TLS keys inmqtt_tls/. With them, a restored install carries on as before; without them it makes new ones, and every node has to be deployed again. An archive with keys is written readable by its owner only, and is to be kept like the keys. - What it leaves out: logs, the MQTT outbox (what it holds would be stale by the time it was restored), dashboard sign-in sessions, files part way through being written or received, files moved aside as unreadable, and directory artifacts as unpacked for agents to read, which are unpacked again from the archive kept beside them.
- Export while it runs. The database is copied with SQLite's own backup, consistent however busy it is, and every other file is replaced in one step whenever it is written. What was persisted in the last second may be missing.
- Import with it stopped. A running server or node holds a lock on its state directory, and an import refuses while it is held; so does a second server started on the same directory by mistake. Import refuses a directory with anything in it unless
--replaceis given, which keeps what was there beside it as<directory>.before-import-<date>-<time>. - An archive is code. Agents' state files are pickles, unpickled when the system starts: importing an archive runs whatever its maker put in it. Import only archives you made. Import checks that an archive holds exactly the files its manifest lists, each matching its SHA-256, at a path inside the directory, which catches a damaged archive, not a forged one.
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 --reason "noisy" # unset a pointer
wactorz-artifacts add model.onnx imu-detector --positive fault --positive bearing # judged on these labels
wactorz-artifacts judge imu-detector:3 --positive fault # say it of a version already stored
wactorz-artifacts judge meter:2 --kind classifier --field appliance # it answers {"appliance": "kettle"}
wactorz-artifacts judge co2:1 --kind regressor --field co2_in_15m # it answers with a number
- A name and a version name one file. Each
addof a name is its next version. A reference isNAME:3for the third version,NAME:latestfor the newest,NAME:activeorNAME:shadowfor the version a pointer names, orNAMEalone for the active version, which is the newest until one is marked active; each resolves to the file's SHA-256, so what a machine fetches can be checked against it. The same bytes, under any names, are kept once. - Two pointers say which version is served and which is on trial.
activate NAME:Vmarks the version agents get when they name the model without a version; a new version stored after that changes nothing until it is activated, and going back is activating the earlier one again.shadow NAME:Vmarks one to run beside it, on the same input, acted on by nobody;promote NAMEmakes the shadow active and clearsshadow. A move records who made it and--reasonwhy, andlistandshowsay where the pointers stand. Pointingshadowat the active version is refused, as is moving a pointer to where it is. With no version active the newest is the one served, so ashadowon the newest starts no trial (there is nothing to try it beside): the agents keep no pairs, and the Models tab says to make another version active; a version a pointer names cannot be removed until the pointer is moved;remove NAME --every-versiontakes the pointers with the name. An agent that named the model, orNAME:active, follows the pointer: restarted after a move, it is pinned to whereactivestands then; one that named a version, orlatest, keeps what it ran.docs/design/model-pointers.mdrecords the decision, and the rest of the model loop builds on it. - What was said of a version reaches its agent.
--meta KEY=VALUE(repeatable; a value that reads as JSON is kept as JSON) is kept with the version and goes wherever the version does: an agent reads it asme.artifacts[key]["metadata"](oragent.artifactsin a program), on main or on a node, and a shadow pass sees the version on trial's. It is for what an agent reads, a threshold, a calibration constant, the dataset's name, and cannot change once stored: a new threshold is a new version. Since it travels in every spawn that names the version,addrefuses more than 64 KiB of it, as JSON; a model card belongs inside the artifact. - A version says what it is judged on.
--positive VALUE(repeatable) names the label values that count as what the model should flag: a fault an operator confirmed, a label an agent wrote. A trial then judges both sides against the labels without being asked, each input against the labels of its own source (the device or topic it came from), or of the one source--label-sourcenames. A version added without it takes the previous version's;judge NAME:Vsets or changes it on a stored version, and--clearremoves it, each change kept with who made it and when. In chat:/artifacts judge NAME:V fault,bearing [label source], ornone. The judged figures -- precision, recall, F1, the false-positive rate, false alarms per day, faults caught and how soon, the Matthews correlation, each rate with its 95% interval, and whether the two sides really differ -- are in the Models tab's trial card,GET /api/models/NAME/trialand the outcome written when a trial ends. That is adetector, the default--kind: it flags an input by publishing something for it. Aclassifieranswers with a class in one field of its output, named with--field, and is right when that is the label's value; an input it published nothing for, or no class in the field, counts as wrong and as no answer. Its figures are accuracy with its interval, precision, recall and F1 per class, their macro and weighted means, and the confusion of labels against answers. Aregressoranswers with a number in its--field, held against the label's value read as a number (a label that is not one is left out and counted): the mean absolute error, the RMS error, the bias and the worst error, and which side was nearer the truth more often, with a sign test saying whether that could be chance. Chat sets only a detector; the other kinds are declared withwactorz-artifacts. - A version trained inside the loop says what it learned from. The
trainerlibrary agent andwactorz-trainstore the versions they make with the recipe's hash, the seed and settings, the window and split, the figures on the held-out rows, anddata, the windows of readings the retention sweep keeps for it (docs/design/train-step.md);show NAME:Vprints them. Such a version inherits what the previous one is judged on. - A policy says when the shadow becomes active.
policy NAME --metric f1 --margin 0.02 --min-days 1 --min-labelled 100 --significant --manualsets when main may promote the shadow (docs/design/promotion-policy.md): the trial's figure on the metric must beat the active version's by the margin, over at least that many days and labelled inputs, with the difference not chance; what is not said keeps what was set, else the default. With no--metric, the trial is compared on the main figure of the kind it is judged as:f1for a detector,macro_f1for a classifier,maefor a regressor (less is better, as forfalse_positive_rateandrmse), and a regressor's difference is tested by the sign test on which side was nearer the truth. A metric the kind does not report is never met, and the trial card says which it does. With--automaticmain promotes aspolicywhen every term is met; with--manual, the default, it asks on the dashboard, and the answer promotes or clears the shadow.--clearunsets it;showprints it. In chat:/artifacts policy NAME margin=0.02 automatic=yes, ornone. The Models tab's trial card shows each term met or short. - Every machine hears a move. Main publishes where each pointer stands, retained, on
models/NAME/activeandmodels/NAME/shadow: the pointer as the store keeps it, or an empty payload when it is unset. Everything is published when main starts, and a move made beside it bywactorz-artifactsreaches the broker at main's next look at the index, a few seconds later; one made in chat is published at once. Each move found is a line on the activity feed. The topics are main's to publish: a pointer is moved through the store or through main, never by writing there. - The format comes from the file's ending:
.onnx,.safetensors,.npz,.npy,.gguf,.tflite,.skops.--formatnames it where the ending does not say, as for a.pt, which may hold astate_dictor a whole module;rawkeeps bytes as they are. Astate_dictmay be a whole checkpoint, the weights beside numbers and numeric numpy arrays (a normalisation, a threshold); where torch is installedaddreads it as an agent will and refuses one that would need code to load, and where it is not, says the file went in unread. A directory is kept as one archive of it, written the same way on every machine, so the same directory has the same hash wherever it is added; a link inside it is refused. - Formats that run code when they load are refused unless
--allow-codeis given: a pickle (.pkl), a joblib file and a whole torch module (--format torch). One stored anyway is marked as running code. - Where:
<state>/..artifacts/, beside the rest of the state, in whatwactorz-state exportwrites.--state-dirnames another state directory. Adding and removing work while the server runs. - In chat.
/artifactslists what is kept, and/artifacts <name>every version of one./artifacts activate <name:version> [reason],/artifacts shadow <name:version> [reason],/artifacts promote <name> [reason]and/artifacts clear active|shadow <name> [reason]move the pointers as the command does, recorded as made from chat; a social channel may list but not move. Main's model is given the same list on each turn, with the active and shadow version of each model, and so is the planner when a request becomes a pipeline, so asking for an agent that uses a model ("flag IMU readings far from normal with the imu-detector model") gets one that names it, and the one being served. Main's model has no way to move a pointer: serving a model is the operator's decision, or a deployed program's. - On the dashboard. The Models tab lists every stored model, saying which is serving a version, which is trying one beside it ("on trial") and which has none active, and opens one at
#/models/<name>: its versions along a line with the active, the shadow and the previous active marked, a table of versions with what was said of each, and the history of its pointer moves, each with who made it and why. From there a version is tried as shadow, the shadow promoted or cleared, and the active rolled back to the version it replaced; each move asks first and takes an optional reason, recorded as made from the dashboard. A pointer moved anywhere else (the CLI, chat, an agent) shows there within seconds. Making a version active directly is left to the CLI and chat: from the dashboard a version is served by being tried first. - Which store. Every
wactorz-artifactscommand says which store it used, andaddwarns when it had to make a new state directory: the default is./statein the folder it runs from, which is Wactorz's own only when run from where Wactorz runs. Pass--state-dir, or setWACTORZ_STATE_DIRfor both. - In an agent. A generated or catalogue agent names artifacts in its spawn config,
"artifacts": {"model": "imu-detector:3"}, and its program opens one withagent.artifact_path("model"): the file, or for a directory the directory it unpacks to, once, in<state>/..unpacked-artifacts/(left out of an export, and unpacked again when needed). A spawn on main that names an artifact that is not stored is refused. - On a node. Main pins each artifact to the version and the bytes it means when the spawn goes out —
imu-detectoralone means the newest then — and keeps that pinned form, so the agent restarted or moved later runs the same model. The node keeps what it fetches in<state>/..artifact-cache/across restarts, asks main only for what it lacks, and starts the agent once every file is there and matches its SHA-256; one that does not arrive leaves the agent unstarted, and a migration is put back where it was. Main sends a node only the artifacts an agent placed on it names. A spawn naming an artifact that is not stored, or one overWACTORZ_ARTIFACT_MAX_BYTES, is refused before anything is sent.
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.