03 / QUICK START

From source to a run you can replay.

The shortest local path through the engine: clone, build, set up the run environment, start a governed workflow, and inspect its record.

Local · self-hosted · no hosted control plane required
Release status. AiOverload is still being prepared for its public engine release. The commands below describe the repository’s local development path, not a packaged or supported production release. Check the current evidence and limitations before deploying it to real workloads.

BEFORE YOU START

Bring a small, explicit toolchain.

The stamped engine tree contains 111 Go packages and targets Go 1.26, with NATS JetStream as the event backbone. You also need Git and a local environment capable of running the engine’s worker and gateway dependencies.

Requirement Why it is there
Git Fetch the source and reviewed workflow definitions
Go 1.26 toolchain Build the engine binaries from the stamped tree
NATS JetStream Durable ordered events and run state
Supported agent/provider credentials Only for workflows that call those providers
Docker, for the docker runtime Required when using the container execution boundary

Do not treat the default development profile as hardened: loopback NATS is unauthenticated unless the opt-in hardened profile is configured.

01 / BUILD

Clone and build the control plane.

TERMINAL
git clone https://github.com/JohGirard/AiOverload.git
cd AiOverload
make build
./bin/aioctl setup

make build produces the local engine binaries, including aioctl, the server, worker, sidecar, and tools. aioctl setup is the repository’s local setup entry point; follow any environment-specific instructions it prints rather than assuming credentials or services already exist.

02 / RUN

Start from a versioned workflow.

The registry contains the workflows served by the engine. This example uses the reflex review loop named in the stamped registry:

./bin/aioctl run registry/workflows/dev-review-loop-reflex.yaml

A risky step may intentionally stop in step.held. That is the governance layer working, not a stalled process. Inspect the reason and risk before deciding whether to approve, constrain, or reject it.

./bin/aioctl approve <run-id> <step-id> \
  --input "review ok — do not push"

Replace the placeholders with the actual run and held-step identifiers printed by your local engine.

03 / VERIFY

Replay the decision trail.

Once the run has events, use its identifier to reconstruct the ordered record:

./bin/aioctl replay <run-id>

Look for the definition hash, step transitions, held events, approvals, and final state. If the narrative in an operator screen disagrees with the event record, the event record is the source of truth — and the discrepancy is a bug.

WHAT YOU CAN RUN

Workflows present at the stamped commit.

Served from registry/workflows/:

code-review-cascadedev-review-loop-reflexdev-review-looplive-probemanager-epicpostmortem

Examples under examples/ are demonstrations, not the served registry. The full, generated inventory and its source commit are on the status page.

READ NEXT

Understand the engine

Go beyond the commands: contracts, the gate, the gateway, event sourcing, and replay.