Resilient AI agents that run 24/7 — built for physical AI.
Docs | Installation | Architecture | Home Assistant Addon | Issues
Wactorz is a runtime for physical AI: LLM-driven agents that live next to the sensors, machines and spaces they act on — not in a cloud notebook. Agents run as long-lived, supervised actors on the hardware you already have: a Raspberry Pi in the garage, a factory gateway, an old laptop, a VM in your closet. You describe what you want in chat; the planner writes the Python, spawns it on a node, and supervises it. When an agent crashes, only that one restarts — with its state intact — and you can migrate an agent to a different machine without losing it.
Everything rides on MQTT, so anything happening inside the system surfaces as a topic external code can subscribe to. Home Assistant talks to it the same way Discord and Telegram do — one channel among several, alongside a REST API and an MCP server. The LLM provider is configurable (Anthropic, OpenAI, Gemini, NIM) or fully local via Ollama, so the system keeps running with no cloud at all.
https://github.com/user-attachments/assets/e832eed9-ba61-4872-8c20-5d0e8cfe14d5
How Wactorz is different
Most agent frameworks build a crew that runs a task and exits. Wactorz builds a system that keeps running. Agents are long-lived, supervised actors — they persist their state, restart themselves when they crash, and can move between machines — rather than functions you call inside one script.
| Wactorz | Orchestration libraries (LangChain, CrewAI, AutoGen) | Visual automation (n8n, Node-RED) | HA native automations | |
|---|---|---|---|---|
| Lifecycle | Long-lived, self-supervising actors | Task-scoped, exit when the script ends | Long-lived flows | Long-lived rules |
| Failure handling | Per-agent crash isolation + restart | Your code handles it | Per-flow | Per-rule |
| Distribution | Agents spawn and migrate across nodes over MQTT | Single process | Single instance | Single instance |
| How agents are built | LLM writes and runs the Python at runtime | You write the chain | You wire nodes by hand | You write YAML |
| Runs offline / self-hosted | Yes — BYO key or fully local via Ollama | Varies | Yes | Yes |
It's not a replacement for Home Assistant — it sits alongside it, adding an LLM planner and dynamic agents on top of the home you already automate.
Quick Start
git clone https://github.com/waldiez/wactorz
cd wactorz
pip install -e ".[all]"
# Start the MQTT broker
docker compose up -d mosquitto
# Set your provider, model, and key (or put them in .env)
export LLM_PROVIDER=anthropic # anthropic | openai | ollama | nim | gemini | fake
export LLM_MODEL=claude-sonnet-4-6
export LLM_API_KEY=your-key-here
python -m wactorz
Dashboard: http://localhost:8888.
If you'd rather skip the clone, pull the image from Docker Hub. To run without an API key, use Ollama:
ollama pull llama3
python -m wactorz --llm ollama --ollama-model llama3
Windows setup is in docs/windows.md; the full set of deployment options lives in docs/deployment.md.
Use it as a library
Bring an agent you already have — a trained model, a class with its own loop — and Wactorz supervises it, restarts it, persists its state and shows it on the dashboard. One decorator is enough:
import wactorz
@wactorz.agent(subscribes="sensors/imu/#", publishes="anomalies/imu")
def detect(reading: dict) -> dict | None:
return reading if MODEL.score(reading) > 4.0 else None
wactorz.run(agents=[detect], minimal=True) # monitor + dashboard + your agent, no LLM needed
# or, inside a program that already has an event loop: await wactorz.serve(agents=[detect], minimal=True)
Or name it in WACTORZ_AGENTS=mypkg.agent:detect for a normal wactorz start, or list it
as a wactorz.agents entry point in your package. wactorz.pipeline(...) groups several
such agents with a schedule and rules, wiring checked up front. The Home Assistant agents start only
when Home Assistant is configured. See Using Wactorz as a library
and examples/imu_anomaly/.
Example prompts
when a person is detected in my pc camera, open the office light
when the door opens, make reachy wakeup
when the light has been on for too long, send me a discord notification
Architecture
flowchart LR
User["User<br/>CLI, REST, Discord, Telegram, HA"] --> Main["MainActor<br/>intent routing"]
Main --> Actuate["OneOffActuatorAgent<br/>direct service calls"]
Main --> Planner["PlannerAgent<br/>pipeline planning"]
Main --> HA["HomeAssistantAgent<br/>REST + WebSocket"]
Main --> Chat["LLM reply<br/>streaming response"]
Planner --> Dynamic["DynamicAgents<br/>LLM-generated runtime code"]
Actuate --> Bus["MQTT broker"]
HA --> Bus
Dynamic --> Bus
Bus --> Dashboard["Live dashboard<br/>agents, logs, cost, heartbeats"]
Bus --> Remote["Remote nodes"]
Bus --> External["Sensors, services, and IoT systems"]
Interfaces
| Interface | How to use it |
|---|---|
| CLI | python -m wactorz |
| Live dashboard | http://localhost:8888 |
| REST API | python -m wactorz --interface rest |
| Discord | python -m wactorz --interface discord |
| Telegram | python -m wactorz --interface telegram |
python -m wactorz --interface whatsapp |
|
| MCP server | wactorz-mcp |
| Home Assistant addon | One-click install inside the HA Supervisor |
LLM Configuration
Set these three env vars in .env or export them in your shell:
# Options: anthropic | openai | ollama | nim | gemini | none | fake
# none = no provider at all; fake = deterministic canned replies, calls nothing
LLM_PROVIDER=anthropic
# Model ID — examples:
# anthropic → claude-sonnet-4-6
# openai → gpt-4o
# ollama → llama3
# nim → meta/llama-3.3-70b-instruct
# gemini → gemini-2.5-flash
LLM_MODEL=claude-sonnet-4-6
# Generic key — used for anthropic / openai / nim / gemini
# For Ollama, set OLLAMA_URL instead (default: http://localhost:11434)
# For OpenAI-compatible endpoints (Groq, Together, vLLM…), set OPENAI_URL to redirect
LLM_API_KEY=your-key-here
# Optional — sampling temperature for every LLM call.
# 0 = deterministic (recommended for device control and classification);
# leave unset/empty to keep each provider's own default.
# Ignored on Claude models from Opus 4.7 onward, which no longer accept it.
LLM_TEMPERATURE=0
# Optional — transient failures (429, 5xx, timeouts) are retried with backoff,
# and an attempt that exceeds LLM_TIMEOUT_S seconds is abandoned and retried.
# For a streamed reply that bounds the wait for the first chunk, so a long
# answer is never cut off. Defaults shown; 0 retries means the first failure is
# the answer, and a 0 timeout waits on the provider SDK's own default.
LLM_MAX_RETRIES=2
LLM_TIMEOUT_S=300
At startup Wactorz logs the configuration it resolved, so you can confirm it at a glance:
LLM: anthropic/claude-sonnet-4-6 | temperature=0.0
Per-call-site overrides (hybrid setups)
Optionally, route individual call sites to different models with LLM_OVERRIDES —
for example run the cheap, high-frequency calls on a local model and keep the
planner on a hosted one:
# <site>=<provider>[:<model>], comma-separated. Unlisted sites use the global provider.
LLM_OVERRIDES="intent=ollama:qwen3:4b,actuator=ollama:llama3,planner=anthropic:claude-sonnet-4-6"
Sites: main (conversation), intent (intent routing), planner (pipeline
planning/codegen), actuator (one-off device control), ha (Home Assistant
agent), dynamic (the get_llm() shim inside generated agents).
To compare models per call site before choosing an override, run the built-in evaluation harness — it scores each site automatically and reports accuracy, latency and cost:
python -m wactorz.evalharness \
--models "ollama:qwen3:4b,anthropic:claude-sonnet-4-6" --temperature 0
See docs/evaluation.md for the benchmark format and metrics.
Security
Wactorz is under active development. The perimeter is closed by default; the remaining caveats below are about what an authenticated caller can do.
What protects an install:
- The API and dashboard require a key. Set
API_KEYand every route, the WebSocket handshake, the Prometheus scrape, and the login flow are authenticated — constant-time comparison, session cookies that survive a restart, and sign-in throttling. - The server binds to
127.0.0.1. Reaching it from the network is deliberate: setWACTORZ_BIND_HOST, and startup refuses unlessAPI_KEYis set too, orWACTORZ_EXPOSED_OK=1says the only way in is already authenticated. A key short enough to guess is warned about. - The broker requires credentials. Anonymous MQTT is off, and remote nodes are given credentials rather than connecting openly.
- Origin and Host allow-lists guard the HTTP surface and the WebSocket handshake against cross-site requests and DNS rebinding.
What to still assume:
- Agents execute code. The planner generates and runs Python, and remote nodes run code delivered over MQTT. Anyone holding the API key or the broker credentials can run code on the host and on every connected node — treat both as root-equivalent, the same way you would an Ansible control node.
- Generated code is screened by a best-effort blocklist, not a sandbox.
Deployment rules:
- ✅ Set
API_KEYbefore exposing anything beyond loopback. - ✅ Prefer the Home Assistant add-on, which keeps the UI behind HA's ingress auth.
- ✅ Keep the broker on a network you control, with credentials set.
- ❌ Do not run it as a multi-user or multi-tenant service — there is one key, not per-user accounts, and no isolation between agents.
- If you reach it remotely, prefer a VPN or an authenticating reverse proxy over a bare port-forward, even with a key set.
More detail in docs/security.md. Found a security issue? Please see SECURITY.md rather than opening a public issue.
Repository Map
| Path | What lives there |
|---|---|
wactorz/ |
Python actor runtime, built-in agents, interfaces, monitoring, HA integration |
frontend/ |
Vite + TypeScript card dashboard |
ha-addon/ |
Home Assistant Supervisor addon |
docs/ |
Markdown docs source |
infra/ |
Mosquitto, Prometheus, nginx, and HA configs |
tests/ |
Python test suite |
Documentation
| Start here | For |
|---|---|
| Quickstart | First run and Windows setup |
| Docker Hub | Run from Docker without cloning the repo |
| Architecture | Actor system, supervision, MQTT flow |
| Agents | Built-in agents, recipes, and dynamic agents |
| Library | Your own agents, pipelines and models, with examples |
| Pipelines | Reactive automation patterns |
| Remote nodes | Edge deployment over SSH |
| Interfaces | CLI, REST, chat platforms, dashboard, MCP |
| API reference | REST endpoints and payloads |
| Deployment | Docker, Home Assistant add-on, environment setup |
| Prometheus | Metrics and monitoring |
| Security | Auth, exposure, broker credentials, threat model |
| Evaluation harness | Compare models per LLM call site |
| Technical reference | Deeper internals |
Contributors
|
Panagiotis Kasnesis 📆 💻 |
Lazaros Toumanidis 💻 🎨 |
Chris 💻 📓 |
Amalia Contiero 💻 📣 |
Contributions of any kind are welcome. See CONTRIBUTING.md to get started.
Contributing
| What | How |
|---|---|
| Found a bug | Open an issue |
| Found an accessibility barrier | Tell us; ACCESSIBILITY.md says what we aim for and what we know falls short |
| Have an idea | Start a discussion |
| Want to code | Fork, branch, and open a PR against dev (main is releases only) |
| Docs, tests, UI | Same drill, open a PR |
| New agent recipe | Add it in wactorz/catalogue_agents/ and open a PR |
| Home Assistant | HA integrations and addon config PRs are very welcome |
Read CONTRIBUTING.md for setup instructions, code style, and the PR process.
License
Apache 2.0. Free to use, modify, and distribute.
Metadata
Release files for wactorz 0.7.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wactorz-0.7.2.tar.gz | 5.3 MB | With provenance | Details for wactorz-0.7.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wactorz-0.7.2-py3-none-any.whl | Python 3 | none | any | Details for wactorz-0.7.2-py3-none-any.whl |
Total release size: 7.2 MB
Release files / wactorz-0.7.2.tar.gz
| Download URL | wactorz-0.7.2.tar.gz |
|---|---|
| Size | 5.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
955ac2a67d07b4ce654b65976c6c212716978c3d496763cf53d8b621f813435d
|
|
BLAKE2b-256 checksum How to use checksums |
6313fbdee09eaca86e39b7c2085b372cc1366e24594e70eb9685cf4a81c67ad9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / wactorz-0.7.2-py3-none-any.whl
| Download URL | wactorz-0.7.2-py3-none-any.whl |
|---|---|
| Size | 1.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5996155e63029217951e32a6c5d6a17c4e02ec5599fcf376313f4364cb7b5b95
|
|
BLAKE2b-256 checksum How to use checksums |
e58a163a69642e99fe06dcc49abbefdd72896fe759ce07fcaf193b10a18657b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for wactorz 0.7.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for wactorz-0.7.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.