Skip to main content

Wactorz

Wactorz

Build AI agents that keep running — across your home, robots, and spare computers.

Docs | Get started | Architecture | Home Assistant Addon | Issues

CI Coverage PyPI License Python MQTT Home Assistant Status: beta


Wactorz is a self-hosted runtime for AI that needs to do more than answer once. Describe an automation in chat and its planner can write a Python agent, run it as a supervised actor, and show you what it is doing in a live dashboard. Agents can listen to sensors and MQTT topics, act through Home Assistant or other services, keep state across restarts, and run on another machine when the job belongs closer to the hardware.

Bring a hosted model from Anthropic, OpenAI, Gemini, or NVIDIA NIM, or keep model inference local with Ollama. The runtime, agent state, dashboard, and MQTT control plane remain on hardware you control.

https://github.com/user-attachments/assets/e832eed9-ba61-4872-8c20-5d0e8cfe14d5


Who it is for

Wactorz is built first for technical hobbyists and makers: people connecting a smart home, robot, camera, Raspberry Pi, or old laptop who are comfortable using a terminal and editing a configuration file. It is also useful to Python developers who want an extensible actor runtime instead of a one-shot agent script.

It is currently a beta, not a no-code consumer app or a multi-user hosted service. Agents can execute generated Python, so use it on systems you control and review the security model before exposing it to a network.

What you can build

  • Persistent automations that react to sensor readings, schedules, and MQTT events.
  • Home Assistant actions described in chat rather than hand-authored for every case.
  • Robot and edge-device agents that run close to their cameras, microphones, or motors.
  • Small groups of agents that keep state, restart independently, and move between nodes.
  • Custom Python agents with REST, MCP, Discord, Telegram, or WhatsApp as an interface.

Quick start

The most predictable first run uses Docker Compose. You need Git, Docker with the Compose plugin, and an API key for your chosen model provider.

git clone https://github.com/waldiez/wactorz
cd wactorz
cp .env.template .env

Open .env and set at least these values:

MQTT_PASSWORD=choose-a-long-random-password
LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-4-6
LLM_API_KEY=your-key-here

Then start Wactorz:

docker compose --profile python up -d

Open the dashboard at http://localhost:8888. Follow the logs with docker compose logs -f wactorz-python and stop everything with docker compose --profile python down.

On Windows, use Copy-Item .env.template .env instead of cp. To install from PyPI, use Ollama, or run inside Home Assistant, see the deployment guide. Repository contributors should start with the development setup.

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 and name that package in WACTORZ_EXTENSIONS. 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/.


Try an automation

Once the dashboard is connected to the services or devices named in a request, try:

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
WhatsApp python -m wactorz --interface whatsapp
MCP server wactorz-mcp
Home Assistant addon One-click install inside the HA Supervisor

Choose a model

Set LLM_PROVIDER, LLM_MODEL, and LLM_API_KEY in .env. The generic key works with every hosted provider, or you can use its provider-specific variable.

Provider LLM_PROVIDER Example model Provider-specific key
Anthropic anthropic claude-sonnet-4-6 ANTHROPIC_API_KEY
OpenAI openai gpt-4o OPENAI_API_KEY
Google Gemini gemini gemini-2.5-flash GEMINI_API_KEY
NVIDIA NIM nim meta/llama-3.3-70b-instruct NIM_API_KEY
Ollama ollama llama3 No key; configure OLLAMA_URL

Wactorz logs the resolved provider and model at startup. Advanced setups can route different jobs to different models and use the evaluation harness before choosing them. Optional LLM_TEMPERATURE, LLM_MAX_RETRIES, and LLM_TIMEOUT_S settings are documented in .env.template.


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_KEY and 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: set WACTORZ_BIND_HOST, and startup refuses unless API_KEY is set too, or WACTORZ_EXPOSED_OK=1 says 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_KEY before 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
Installation Install with pip, configure, upgrade
Windows Windows and ARM64 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
Panagiotis Kasnesis

📆 💻
Lazaros Toumanidis
Lazaros Toumanidis

💻 🎨
Chris
Chris

💻 📓
Amalia Contiero
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.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wactorz 0.8.0
File Size Uploaded Provenance Actions
wactorz-0.8.0.tar.gz 6.6 MB With provenance Details for wactorz-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wactorz 0.8.0
File Interpreter ABI Platform Actions
wactorz-0.8.0-py3-none-any.whl Python 3 none any Details for wactorz-0.8.0-py3-none-any.whl

Total release size: 9.1 MB

Release files / wactorz-0.8.0.tar.gz

Download URL wactorz-0.8.0.tar.gz
Size 6.6 MB
Tags Source
SHA-256 checksum
How to use checksums
690bf33b14f8bbafe145cd81975388bd2ad823c59f2e4f032785f98dbd49e43b
BLAKE2b-256 checksum
How to use checksums
1c48e19e6696c651418022666c086525bc96091678c72c568d7d6bf8190f78e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 15, 2026.

Transparency log

Release files / wactorz-0.8.0-py3-none-any.whl

Download URL wactorz-0.8.0-py3-none-any.whl
Size 2.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
278526aed512196dadb749dd9324c42bfe8cfa23a9c73880f7b1afb6fdd2341c
BLAKE2b-256 checksum
How to use checksums
fcd44e117591c5a7e270e0c8683af4b37db75fc2076247389cb140185cb13b30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 15, 2026.

Transparency log

Security for wactorz 0.8.0

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.

Select from 2 files

Attestation for wactorz-0.8.0.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 Nov 15, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page