Run your Waldiez flows in isolated environments and stream AG2 logs/input/output via Redis.

Waldiez Runner enables executing flows in isolated Python virtual environments or containers, with full I/O streaming via Redis and task management via FastAPI + Taskiq.

Backed by:

• FastAPI for the HTTP API
• Taskiq for async task queuing and scheduling
• Redis for messaging and log/input/output streaming
• PostgreSQL for task and client persistence
• Waldiez + ag2 + FastStream for defining, executing, and streaming interactive flows in isolation

Follow these steps to get Waldiez Runner up and running in your development environment.

To launch the full development stack (API + Redis + Postgres + Nginx):

!!!Note This could take some minutes on the first run, as it installs all dependencies.

docker compose -f compose.dev.yaml up --build

This setup includes:

• API server (waldiez-runner)
• Redis + PostgreSQL
• Taskiq worker + scheduler
• Nginx reverse proxy
• A simple static example in examples/html

Once started, you can access:

• Static example UI: http://localhost
• API: http://localhost/docs (Swagger UI)

!!!Note Alternatively, you can open this project in VS Code with Dev Containers enabled — it uses most of the services (not nginx) via .devcontainer/compose.yaml.

When the server starts, it automatically generates a clients.json file in the project root.
This file contains two API clients:

• One for the clients-api audience (managing clients)
• One for the tasks-api audience (creating and interacting with tasks)

You'll need the tasks-api credentials to:

• Use the Swagger UI (try out endpoints under /api/v1/tasks)
• Submit tasks via curl or HTTP clients
• Use the example UI at http://localhost

!!!INFO On the example page, you’ll be asked to paste the base URL, client ID, and secret.
Use the values from clients.json (specifically the tasks-api entry).

🔐 See Clients & Authentication for more details.

For administrative operations, you'll need an admin-api audience client:

• View all tasks across all users: GET /api/v1/admin/tasks
• Monitor task activity across all clients
• Access administrative endpoints for oversight and management

!!!WARNING Admin endpoints require special authentication with the admin-api audience.
Regular tasks-api clients cannot access admin functionality.

The server automatically generates an admin client alongside the standard clients.
Check clients.json for the admin-api entry when it exists.

You can also run the server without any external dependencies (Redis/Postgres):

• SQLite for storage
• FakeRedis for message streams

make dev-no-reload

!!!Warning Do expect limitations in this mode, [Fake]Redis messages might not work as expected.

Or manually (what make dev-no-reload does):

# drop all tables and remove the .env file if it exists
python scripts/drop.py
# switch to local mode if not already
python scripts/toggle.py --mode local
# make sure the .env file is created and the database is initialized
python scripts/pre_start.py --dev
# make sure the first two Clients are created
python scripts/initial_data.py --dev
# start the server, the broker and the scheduler
python -m waldiez_runner --trusted-origins http://localhost:3000,http://localhost:8000 --trusted-hosts localhost --debug --no-force-ssl --no-redis --no-postgres --dev --all

You can now either use the Swagger UI at http://localhost:8000/docs or you can also serve the example on another port terminal:

cd examples/plain
python -m http.server 3000

Calling python -m http.server will start a simple HTTP server on port 3000, serving the files in the current directory. You can now access the example UI at http://localhost:3000.

Once the server is running, you can create and interact with tasks:

• Submit a task by uploading a .waldiez file via:

  • the example UI at http://localhost
  • or the Swagger UI at http://localhost/docs (POST /api/v1/tasks)

• Monitor task progress via:

  • the Swagger GET /api/v1/tasks/{task_id}
  • or the WebSocket endpoint /ws/{task_id} (see WebSocket)
  • Admin users: GET /api/v1/admin/tasks to view all tasks across all users

• Send input if the task requests it:

  • Use the input box in the example UI
  • Or call POST /api/v1/tasks/{task_id}/input

• Cancel or delete tasks using:

  • POST /api/v1/tasks/{task_id}/cancel
  • DELETE /api/v1/tasks/{task_id}

You can explore all available routes via the interactive API docs at /docs.

Thanks goes to these wonderful people (emoji key):

Panagiotis Kasnesis 📆 🔬	Lazaros Toumanidis 💻	Stella Ioannidou 📣 🎨	Amalia Contiero 💻 🐛	Christos Chatzigeorgiou 💻
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

This project is licensed under the Apache License, Version 2.0 (Apache-2.0).