Security
Wactorz runs AI agents that hold your credentials, control your devices, and can write and run Python. This page describes what it protects, what it does not, and how to deploy it so the difference does not matter.
Read it before you make Wactorz reachable from anything but the machine it runs on.
The short version
| Deployment | What protects it |
|---|---|
| Default install | It listens on 127.0.0.1 only. Nothing off the machine can reach it. |
| Reachable install | API_KEY. Binding to a reachable address without one refuses to start. |
| Compose stack | API_KEY from .env, or one generated on first start. Every container on the stack's network can reach the app, so it never runs without one. |
| Home Assistant add-on | Home Assistant's own login. The panel goes through ingress, and requests are verified as coming from the Supervisor. |
The refusal is deliberate rather than a warning: a warning scrolls past in a
container log while you believe you only changed an address. Three ways forward,
and the message names all three — set API_KEY, bind to 127.0.0.1, or set
WACTORZ_EXPOSED_OK=1 when the only route in is already authenticated.
Trust boundaries
| Inside the boundary | Outside it |
|---|---|
| The Wactorz process and every agent in it | The browser |
| The MQTT broker and everything published on it | Any machine that can reach the broker port |
Edge nodes reached by /deploy |
The network between them |
| The state directory and the SQLite database | — |
Everything inside shares one privilege level. There is no separation between agents: an agent is a Python object in a process, not a principal. If two agents have different levels of trust in your head, they do not have different levels of access in Wactorz.
Agents run code in the Wactorz process
A spawned agent's body is Python, compiled and executed inside the running process. It has the same file access, the same network access, the same environment variables, and the same credentials as Wactorz itself — including your LLM keys and your Home Assistant token.
Generated code is scanned for dangerous constructs before it runs, and obvious ones are rejected. That check is not a sandbox and is not intended as one. It reads source text; code that reaches the same capability by another route passes it. Treat it as a guard against mistakes, not against intent.
The practical consequence:
Anyone who can make Wactorz spawn an agent can run arbitrary code as the Wactorz process. Granting that ability is equivalent to granting shell access to the machine, with the credentials attached.
Spawning is reachable from the dashboard and the API, both of which sit behind
API_KEY on a reachable install. It is deliberately not reachable from
social channels — Discord and Telegram use a restricted entry point that refuses
spawning, deletion, code and automation, at the action rather than by inspecting
the text, so it cannot be talked around.
If you need agents that cannot do this, run Wactorz in a container with only the credentials that deployment needs, and do not mount what it should not reach.
Untrusted input is not just what a user types
The boundary that matters is not "someone typed into chat". It is any text any agent reads, because that text reaches a model that can act.
Agents ingest, among other things:
- web pages and search results
- PDFs and device manuals downloaded from the internet
- email bodies and calendar entries
- MQTT payloads from devices and edge nodes
- Home Assistant entity names and attributes
A concrete example that ships in the catalogue: the device-manual agent searches the web for a manual, downloads the PDF it finds, extracts the text, and puts that text into a prompt. Nothing about that PDF is under your control. It reaches that agent's own model first and the main agent's context only indirectly, through the reply — two hops rather than a direct line to the spawner, which is why it is worth stating plainly rather than assuming the distance protects you. What it can fetch is bounded: only public web addresses, every redirect checked the same way, so a search result cannot send it to a router or a cloud metadata address on the network it runs in, and nothing past 50 MB.
Assume any document an agent reads can attempt to instruct it. Give agents the narrowest credentials that let them do their job.
The MQTT broker is the control plane
Agent commands, chat, task delegation and the source of spawned agents all cross the broker. Anything that can publish to it can drive Wactorz.
- Credentials are required. The bundled broker refuses anonymous
connections, and
docker composewill not start withoutMQTT_PASSWORD. - Edge nodes reach the broker over TLS where the broker serves it. Wactorz
keeps a private CA in the state directory and issues the broker's certificate
from it; the compose stack and the add-on's embedded broker serve TLS on
8883beside plain1883./deployhands a node the CA and switches it to TLS only after checking from the node that the broker answers it — a node that could not stays on cleartext, and the deploy log says so. The server's own connection uses TLS withMQTT_TLS=1, on the broker's TLS port. The compose stack publishes plain1883to its own host only; setMQTT_EXTERNAL_BIND=0.0.0.0for a node not yet on TLS, until it is deployed again. The add-on's embedded broker publishes nothing unless you map a port. The broker still belongs on a network you trust, and nothing here replaces a tunnel or VPN across the public internet. See "Encrypted connections (TLS)" inremote-nodes.md. - Edge nodes hold broker credentials.
/deploywrites them to the node over SSH. On a broker Wactorz does not configure, a node uses the server's own account unless told otherwise, so a stolen node holds full broker access.WACTORZ_NODE_ACCOUNTS=1— the default in the compose files and the add-ons' embedded broker — gives each node an account of its own instead, and on the brokers Wactorz configures an access list that names what a node may use: its ownnodes/<name>/..., the shared agent traffic, and the data topics agents publish under by convention. Every other node's topics,agents/+/commands,system/and anything else on the broker —zigbee2mqtt/, Home Assistant's discovery — are closed to it.WACTORZ_NODE_TOPICSopens more data topics to every node. Once a node is deployed, an account the list does not name has no access, so list any other system that shares the broker inWACTORZ_BROKER_ACCOUNTS. It takes effect for a node at its next/deploy, so rotate the shared password once the last one has moved. A node's agents share its account: the boundary is the machine, not the agent. See "An account per node" inremote-nodes.md. /deploytrusts a node's SSH host key the first time it connects. The key is recorded in<WACTORZ_STATE_DIR>/known_hosts, or whereverDEPLOY_KNOWN_HOSTSpoints, and a later change fails the connection. The first connection is the exposure: whatever answers at the node's address then is trusted, and is handed the node's broker credentials and signing key. On a network you do not fully trust, setDEPLOY_STRICT_HOST_KEYS=1and add each key yourself after checking its fingerprint. See "Host key verification" inremote-nodes.md.- Commands to an edge node are signed. A node runs the code in a spawn it
receives, so broker access alone must not be enough to send one. Main signs
every command it sends a node with a key derived for that node, which
/deploywrites to the node with its broker credentials. WithWACTORZ_NODE_SIGNING=enforce, the default, a node refuses a command not signed for it; withwarnit acts on it and main says so in chat, to find out what sends unsigned commands before refusing them. A node deployed before signing holds no key and checks nothing until it is deployed again, and a node takes the mode at its next/deploy. - Main takes a node's word only from that node. A node signs everything it
publishes with the same key, and main checks it against the node it expects:
an agent's task reply, manifest and data samples count only signed by the node
main's own records place the agent on, and a node's heartbeat only signed by
that node. So code on one node, the sandbox included, cannot answer for
another node's agent or describe one to the planner. An unsigned message
follows
WACTORZ_NODE_SIGNING; underenforcea node deployed before this stays up but is sent no tasks until it is deployed again. A signature names the machine, not the agent on it, and an agent's status, logs and what agents read from each other on the broker are still not checked. - Main's LLM answers only the nodes it deployed. An agent on a node asks main's
LLM over the broker (
main/llm_request), and main answers with its own budget and an account the broker lets write anywhere. So a request names its node and is signed with that node's key, and main replies only on that node's ownnodes/<name>/reply/...topics: a request naming any other reply topic gets nothing at all. An unsigned request followsWACTORZ_NODE_SIGNINGlike a command:enforceanswers it with an error,warnanswers it and main says so in chat. Reads of main's stored history (main/history_request, behindagent.query_tsand its kind on a node) are admitted the same way, and run only the queries the agent API offers, never SQL a request supplies. A node main deployed may read all of that history: sensor readings, detections and Home Assistant state changes. Each node gets so many model calls and history pages a minute (WACTORZ_BRIDGE_CALLS_PER_MINUTE, 60, andWACTORZ_BRIDGE_HISTORY_PAGES_PER_MINUTE, 600) and only a few running at once; past either, a request is refused at once with a reply saying why, and the first refusal for a node is said on the dashboard. So one node's agent in a loop neither spends main's budget as fast as the provider answers nor holds up the other nodes' requests. A spending cap over all calls isLLM_COST_LIMIT_USD. - An operator's answer is not authenticated. The pick an agent receives from
ask_operatorornotify_userarrives on itsagents/<id>/answertopic, where any node, and anything else holding broker access, can publish one. It says what someone answered, never that you did: do not make it the approval for anything you would not let the agent do unasked. Packages are the exception: they are approved through the dashboard itself, never the broker. - Main's deploy credentials open every node. The SSH key or password a
DEPLOY_<NODE>_*block names gives a shell on that node, as the user it names, so whoever holds main's environment holds every node, as with its broker account. A node deployed as root, or as a user with passwordless sudo, hands over root with it. Deploy nodes as a user without sudo: see "Run as a service" inremote-nodes.md.
Secrets, logs and stored data
- Logs are redacted as they are written — known credential shapes are
scrubbed before anything is stored or served: a secret named as one
(
password=,"api_key": …), aBearerheader, credentials in a URL, a private key, and tokens recognisable by their shape alone — a Telegram bot token in the Bot API's URLs, a JSON web token such as Home Assistant's, andsk-,ghp_,github_pat_andxox?-keys. This is a floor, not a guarantee: a log can carry a secret nobody chose to write into it. Treat the log view as shareable with care. - Raising a library to
DEBUGputs request bodies and headers into that same log. It is refused through the API unlessWACTORZ_LOG_DEBUG_CAPTURE=1is set on the host, so turning it on requires reaching the machine. - Chat history, uploaded files and agent state are stored unencrypted in the state directory. Protect it with filesystem permissions; anyone who can read it can read every conversation.
- The browser is never given your API key. Signing in exchanges it for a session cookie that can be revoked on its own, so signing out does not disturb scripts and integrations using the key directly.
Deployment checklist
- Keep the default
127.0.0.1bind unless you need otherwise. - If you need otherwise, set
API_KEYto something generated —openssl rand -hex 32. Behind a reverse proxy, list it inWACTORZ_TRUSTED_PROXIESand have it setX-Forwarded-HostandX-Forwarded-Protorather than append to them. Forwarded headers from any other peer are ignored. Do not list a loopback address: a page in a browser on the same machine connects from there too. For a proxy on the same host, have it passHostthrough instead. - Put the broker on a trusted network segment, and set
MQTT_PASSWORD. - Give each edge node its own broker account: the compose files and the add-ons'
embedded broker do by default; elsewhere set
WACTORZ_NODE_ACCOUNTS=1once the broker has the accounts. Deploy every node again, then rotate the account they shared. Where another system shares that broker, name its account inWACTORZ_BROKER_ACCOUNTS. - Deploy every edge node again after upgrading, so it holds a signing key,
refuses unsigned commands and signs what it publishes
(
WACTORZ_NODE_SIGNING=enforce, the default). Publish the broker's8883where nodes can reach it first, so the deploy puts them on TLS, and check the deploy log says so. - Give Wactorz only the credentials the agents you run actually need.
- Restrict filesystem access to the state directory — it also holds the secret the node keys are derived from, and the key of the CA nodes trust the broker by.
- Treat the ability to spawn agents as equivalent to shell access, and hand it out on that basis.
- Deploy each edge node as a user without sudo, with lingering enabled, so the deploy key main holds is not root on the node.
Reporting a problem
Please report security issues privately, by email to development @ waldiez.io,
rather than in a public issue. The maintainers will work with you on a fix
before any public disclosure.