waldiez/wactorz

By waldiez

•Updated about 14 hours ago

Wactorz is an actor-model multi-agent framework for real-world automation, IoT, and physical AI.

Image

2.2K

Overview Tags

waldiez/wactorz repository overview

⁠Wactorz

Actor-model multi-agent AI framework for Python - built for IoT, edge, and 24/7 autonomous workloads.

Agents run as independent asyncio actors, communicate over MQTT, and are supervised with Erlang/OTP-style ONE_FOR_ONE restart semantics. The LLM can write and spawn new agents at runtime without restarting the process.

⁠What it does

Long-running agents - designed to run 24/7; each actor has its own message loop, heartbeat, and crash-recovery
Distributed across nodes - deploy remote_runner.py (a single file, no install) to any Raspberry Pi or edge device; agents on remote nodes appear in the central dashboard alongside local ones
Auto-spawning - describe what you need in chat and the planner generates and spawns agents on the fly from LLM-generated Python
Agent discovery - agents publish capability manifests over MQTT; the orchestrator routes tasks automatically
Supervision + self-healing - crashed actors are restarted automatically; dynamic agents survive full process restarts via a persistent spawn registry (SQLite)
Centralized persistence - three-tier store (SQLite / Redis / Pickle) shared across all actors; persist(key, value) routes automatically
IoT-native - MQTT is the universal bus between agents, the dashboard, Home Assistant, and any external device or service

⁠Included


Built-in agents	MainActor, PlannerAgent, DynamicAgent, CatalogAgent, HomeAssistantAgent, MonitorAgent
Interfaces	CLI, REST API, Discord, Telegram, WhatsApp, MCP
LLM providers	Anthropic, OpenAI, Gemini, Ollama, NIM
Web dashboard	Live agent status, heartbeats, logs, chat - `http://localhost:8888`
Prometheus metrics	Built-in `/metrics` endpoint

⁠Quickstart

Prerequisite: Docker Desktop⁠ installed and running.

Option A - Terminal + Compose (recommended)⁠
Option B - Docker Desktop + Terminal⁠

⁠Option A - Terminal + Compose (recommended)

⁠1. Create a project folder

mkdir wactorz
cd wactorz

⁠2. Create three files inside that folder

Windows tip: open Notepad, paste the content, then Save As - set Save as type to All Files and type the filename exactly as shown.

mosquitto.conf

listener 1883
listener 9001
protocol websockets
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest stdout

compose.yaml

name: wactorz

services:
  mosquitto:
    image: eclipse-mosquitto:2.0
    container_name: wactorz-mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - mosquitto-data:/mosquitto/data
    networks:
      - wactorz-net
    healthcheck:
      test: ["CMD", "mosquitto_sub", "-t", "$$SYS/#", "-C", "1", "-i", "hc", "-W", "3"]
      interval: 10s
      timeout: 5s
      retries: 5

  wactorz:
    image: waldiez/wactorz:latest
    container_name: wactorz
    restart: unless-stopped
    env_file:
      - .env
    environment:
      MQTT_HOST: mosquitto
      MQTT_PORT: "1883"
    ports:
      - "8000:8000"
      - "8888:8888"
    networks:
      - wactorz-net
    depends_on:
      mosquitto:
        condition: service_healthy

networks:
  wactorz-net:

volumes:
  mosquitto-data:

.env - uncomment the provider you want to use:

# Anthropic (Claude) - default
LLM_API_KEY=sk-ant-...
LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-4-6

# OpenAI
# LLM_API_KEY=sk-...
# LLM_PROVIDER=openai
# LLM_MODEL=gpt-4o

# Ollama (local)
# LLM_PROVIDER=ollama
# LLM_MODEL=llama3

⁠3. Start

docker compose up -d

Images are pulled automatically on first run.

⁠4. Open

	URL
Monitor UI	`http://localhost:8888`
REST API	`http://localhost:8000`

To stop: docker compose down

⁠Option B - Docker Desktop + Terminal

⁠Step 1 - Create a project folder

mkdir wactorz
cd wactorz
Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/waldiez/wactorz/main/.env.template" `
  -OutFile ".env.template"
Copy-Item .env.template .env

⁠Step 2 - Edit `.env`

notepad .env

Fill in at minimum your LLM key and provider. Make sure these Docker-specific values are set:

MQTT_HOST=wactorz-mosquitto
PORT=8000
MONITOR_PORT=8888

Port conflict? On some Windows machines port 8888 is reserved by a system service. If the monitor UI is unreachable, change MONITOR_PORT to any free port (e.g. 8887) and use that port in Step 4.

⁠Step 3 - Start Mosquitto

[System.IO.File]::WriteAllText(
  (Join-Path (Get-Location) "mosquitto.conf"),
  "listener 1883`nlistener 9001`nprotocol websockets`nallow_anonymous true`npersistence true`npersistence_location /mosquitto/data/`nlog_dest stdout`n",
  [System.Text.UTF8Encoding]::new($false)
)

docker network create wactorz-net
docker run -d --name wactorz-mosquitto `
  --network wactorz-net `
  -p "1883:1883" `
  -p "9001:9001" `
  -v "${PWD}\mosquitto.conf:/mosquitto/config/mosquitto.conf" `
  eclipse-mosquitto:2.0

If wactorz-net already exists, the network create line will error - that is OK.

⁠Step 4 - Start Wactorz

docker run -d --name wactorz `
  --network wactorz-net `
  -p "8000:8000" `
  -p "8888:8888" `
  --env-file "${PWD}\.env" `
  -e MQTT_HOST=wactorz-mosquitto `
  waldiez/wactorz:latest

Open http://localhost:8888.

⁠Links

GitHub⁠ · PyPI⁠ · Docs⁠ · Issues⁠ · Apache-2.0

Tag summary

Recent tags

Content type