Ecosystem / NullBoiler

NullBoiler Workflow Orchestrator

Zig-based orchestration runtime for DAG-style workflows, step scheduling, worker dispatch, approvals, retries, and operational run/event APIs.

Quick Start API GitHub

18

API route patterns in `src/api.zig`

14

step types supported by engine

3

worker protocols (webhook/api_chat/openai_chat)

9

SQLite tables (core + advanced migrations)

Quick Start

git clone https://github.com/nullclaw/nullboiler.git
cd nullboiler
zig build -Doptimize=ReleaseSmall

# terminal 1: mock worker endpoint (from repo tests)
python3 tests/mock_worker.py 9999

# terminal 2: run orchestrator
./zig-out/bin/nullboiler --port 8080 --db /tmp/nullboiler.db

# register worker (webhook requires explicit URL path)
curl -s -X POST http://127.0.0.1:8080/workers \
  -H 'Content-Type: application/json' \
  -d '{"id":"test-worker-1","url":"http://127.0.0.1:9999/webhook","token":"dev","tags":["tester"],"max_concurrent":2}'

# create run
curl -s -X POST http://127.0.0.1:8080/runs \
  -H 'Content-Type: application/json' \
  -d '{"steps":[{"id":"step1","type":"task","worker_tags":["tester"],"prompt_template":"Hello {{input.name}}"}],"input":{"name":"World"}}'

Code-Derived Snapshot

Source basis: `src/main.zig`, `src/api.zig`, `src/engine.zig`, `src/workflow_validation.zig`, `src/worker_protocol.zig`, and migrations in `src/migrations`.

Core Step Types

`task`, `fan_out`, `map`, `reduce`, `condition`, `approval`, `transform`, `wait`, `router`, `loop`, `sub_workflow`, `debate`, `group_chat`, `saga`.

Auth Model

Optional global bearer auth via `--token` / `api_token`; `GET /health` and `GET /metrics` remain unauthenticated.

Workflow Validation

`POST /runs` rejects invalid graphs: duplicate step ids, unknown `depends_on`, missing required fields for `wait`, `router`, `saga`, `group_chat`, and invalid retry/timeout controls.

Worker Protocol Rules

`openai_chat` requires `model`; `webhook` URLs must include explicit path (for example `/webhook`); dispatch selects active workers by tag overlap and capacity.