AI agents that don't stop when you close the tab.
Docs | Installation | Architecture | Home Assistant Addon | Issues
Wactorz runs LLM-driven agents as long-lived actors on the hardware you already have - a Raspberry Pi in the garage, 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. State persists across restarts and you can move an agent to a different machine without losing it.
It runs 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 - it's 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 for offline use.
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
export LLM_MODEL=claude-sonnet-4-6
export LLM_API_KEY=your-key-here
python -m wactorzDashboard: 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 llama3Windows setup is in docs/windows.md; the full set of deployment options lives in docs/deployment.md.
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
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"]
| 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 |
| MCP server | wactorz-mcp |
| Flutter app | iOS/Android companion app for agents, chat, and activity feed |
| Home Assistant addon | One-click install inside the HA Supervisor |
Set these three env vars in .env or export them in your shell:
# Options: anthropic | openai | ollama | nim | gemini | none
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)
LLM_API_KEY=your-key-here| Path | What lives there |
|---|---|
wactorz/ |
Python actor runtime, built-in agents, interfaces, monitoring, HA integration |
frontend/ |
Vite + TypeScript + Babylon.js dashboard |
rust/ |
Rust backend crates and MQTT/interface support |
mobile/ |
Flutter companion app |
ha-addon/ |
Home Assistant Supervisor addon |
docs/ |
Markdown docs source |
infra/ |
Mosquitto, Prometheus, OpenTelemetry, Fuseki, nginx, and HA configs |
tests/ |
Python test suite and backend parity harness |
| 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 |
| 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, native binary, systemd, staging, HA addon |
| Prometheus | Metrics and monitoring |
| Technical reference | Deeper internals |
Panagiotis Kasnesis 📆 💻 |
Lazaros Toumanidis 💻 🎨 |
Chris 💻 📓 |
Amalia Contiero 💻 📣 |
Contributions of any kind are welcome. See CONTRIBUTING.md to get started.
| What | How |
|---|---|
| Found a bug | Open an issue |
| Have an idea | Start a discussion |
| Want to code | Fork, branch, and open a PR against main |
| 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.
Apache 2.0. Free to use, modify, and distribute.