wactorz 0.5.2

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.

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.

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
export LLM_MODEL=claude-sonnet-4-6
export LLM_API_KEY=your-key-here

python -m wactorz

Dashboard: http://localhost:8888.

[!WARNING] Run Wactorz only on a trusted local network. The dashboard, REST API, and MQTT broker are unauthenticated by default, and agents can execute code. Do not expose ports 8888, 8000, or 1883 to the internet or an untrusted LAN. See Security before deploying anywhere shared.

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

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

# 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.
LLM_TEMPERATURE=0

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. Treat the current release as alpha from a security standpoint and deploy accordingly.

Threat model — what to assume today:

• The monitor dashboard, REST API, WebSocket, and MQTT broker are unauthenticated by default. Anyone who can reach those ports can spawn, control, and delete agents.
• Agents can execute code (the planner generates and runs Python; remote nodes run spawned code over SSH/MQTT). Anyone who can reach the control plane can run code on the host and on any connected node.
• The bundled MQTT broker ships with anonymous access for local development.

Deployment rules:

• ✅ Run on a trusted local network you control (a home LAN, a private VLAN).
• ✅ Prefer the Home Assistant add-on, which keeps the UI behind HA's ingress auth.
• ❌ Do not expose ports 8888 (dashboard), 8000 (REST/WS), or 1883/9001 (MQTT) to the internet or a shared/untrusted network.
• ❌ Do not run it as a multi-user or multi-tenant service yet.
• If you must reach it remotely, put it behind a VPN or an authenticating reverse proxy — never a bare port-forward.

Found a security issue? Please see SECURITY.md rather than opening a public issue.

Repository Map

Documentation

Contributors

Panagiotis Kasnesis 📆 💻

Lazaros Toumanidis 💻 🎨

Chris 💻 📓

Amalia Contiero 💻 📣

Contributions of any kind are welcome. See CONTRIBUTING.md to get started.

Contributing

Read CONTRIBUTING.md for setup instructions, code style, and the PR process.

License

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