https://github.com/nullclaw/nullboiler
https://github.com/nullclaw/nullboiler
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/nullclaw/nullboiler
- Owner: nullclaw
- Created: 2026-03-01T10:12:01.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-09T16:17:02.000Z (3 months ago)
- Last Synced: 2026-03-09T21:42:40.125Z (3 months ago)
- Language: Zig
- Size: 2.76 MB
- Stars: 8
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# NullBoiler
NullBoiler is an orchestration engine for AI agents.
It is intentionally narrow: it decides what should run, when it should run, and which worker should execute it.
It does not replace the task tracker and it does not replace the agent runtime.
You do not need all components together.
Choose only the pieces required for your workflow.
## Design Principle
`tracker = source of truth`
`orchestrator = policy engine`
`agent = executor`
### 1) Tracker: [nulltickets](https://github.com/nullclaw/nulltickets)
Use nulltickets as the authoritative task system for AI agents:
- Stores tasks, states, priorities, and ownership.
- Preserves durable history of task lifecycle.
- Acts as the canonical queue/source of truth for pending work.
### 2) Orchestrator: [nullboiler](https://github.com/nullclaw/nullboiler)
Use nullboiler to apply orchestration policy:
- Pulls/selects work from tracker or another source.
- Applies scheduling and routing strategies.
- Enforces concurrency limits, retries, and backoff policies.
- Dispatches work to one or many agents/workers.
NullBoiler should not become a task tracker or artifact database.
### 3) Agent Runtime: [nullclaw](https://github.com/nullclaw/nullclaw) or another compatible worker
Use an agent runtime as the execution engine:
- Receives a concrete task/job to run.
- Executes tools, code, and model interactions.
- Returns execution outputs/events back to the orchestrator/tracker flow.
`nullclaw` is the reference runtime, but `nullboiler` can also orchestrate other compatible workers
(for example OpenClaw/OpenAI-compatible, ZeroClaw, or PicoClaw via bridge).
Agents should execute work, not own global orchestration policy.
## Why This Separation Exists
Teams often try to move tracker and artifact responsibilities into the orchestrator.
This project keeps boundaries strict on purpose:
- Tracker owns durable truth.
- Orchestrator owns coordination policy.
- Agent owns execution.
This keeps the architecture modular, simpler to reason about, and easier to evolve.
## Supported Compositions
- `nullclaw` only: single-agent direct execution.
- `nullboiler + nullclaw`: orchestrated execution without dedicated tracker.
- `nullboiler + other compatible agents`: orchestrated execution without `nullclaw` dependency.
- `nulltickets + nullclaw`: tracker-driven execution loop.
- `nulltickets + nullboiler + nullclaw`: full multi-agent orchestration with durable task source.
See additional integration docs in [`docs/`](./docs).
## Workflow Graph Features
The orchestration graph runtime supports:
- `task`, `agent`, `route`, `interrupt`, `send`, `transform`, and `subgraph` nodes
- run replay, checkpoint forking, breakpoint interrupts, and post-start state injection
- `send` fan-out with canonical `items_key` and configurable `output_key`
- task/agent output shaping via `output_key` and `output_mapping`
- template access to `state.*`, `input.*`, `item.*`, `config.*`, and `store..`
- `transform.store_updates` for writing durable workflow memory back to NullTickets
Store-backed templates and `store_updates` require a NullTickets base URL. The
runtime resolves it from workflow fields such as `tracker_url` or from run config
(`config.tracker_url` / `config.tracker_api_token`), which are injected into
state as `__config`.
## Config Location
- Default config path: `~/.nullboiler/config.json`
- Override instance home with `NULLBOILER_HOME=/path/to/dir`
- Override config file directly with `--config /path/to/config.json`
When `NULLBOILER_HOME` is set, `nullboiler` reads `config.json` from that directory and
resolves relative paths like `db`, `strategies_dir`, `tracker.workflows_dir`, and
`tracker.workspace.root` relative to that config file.