wactorz 0.5.0

Actor-model multi-agent framework — spawn, coordinate and monitor AI agents at runtime

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.

---

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

---

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

---

LLM Configuration

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)
# For OpenAI-compatible endpoints (Groq, Together, vLLM…), set OPENAI_URL to redirect
LLM_API_KEY=your-key-here

---

Repository Map

Path	What lives there
wactorz/	Python actor runtime, built-in agents, interfaces, monitoring, HA integration
frontend/	Vite + TypeScript card dashboard
mobile/	Flutter companion app
ha-addon/	Home Assistant Supervisor addon
docs/	Markdown docs source
infra/	Mosquitto, Prometheus, OpenTelemetry, 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
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
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
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.

---

License

Apache 2.0. Free to use, modify, and distribute.