Wheel

They always say "don't reinvent the wheel" — sometimes you have to.

Wheel is a per-project, per-user container that runs Claude Code / Codex agents as child processes, wired to each other and to tables, endpoints, scripts, MCP servers, vaults and chests on a visual board.

• docs/ARCHITECTURE.md — the shared contract every team builds against. Read it first.
• docs/PROTOCOL.md — engine control plane + wheel CLI (SDK/Engine team)
• docs/API.md — api.wheel.dev (API team)
• docs/TESTPLAN.md — acceptance criteria (QA)
• redteam/ — threat model and findings (ADVERSARY)

Workflow: one worktree per team under /Users/metatron/wheel-wt/<role>, merge to main after make check.

Running Wheel

Wheel is source-available (PolyForm Noncommercial 1.0.0) — free to use, modify, and share for any noncommercial purpose.

Fastest way to get going — Docker Engine + git, nothing else:

docker build -f docker/Dockerfile.wheeld -t wheeld .
docker run -d --name wheeld --stop-timeout 30 -v wheel-data:/data -p 127.0.0.1:8080:8080 wheeld
(umask 077; docker exec wheeld cat /data/operator-token > ~/.wheel-token)
export WHEEL_TOKEN_FILE=~/.wheel-token

Then drive it with that token:

wh() { local path=$1; shift
       curl -fsS -H @<(printf 'x-auth-token: %s\n' "$(cat "${WHEEL_TOKEN_FILE:-$HOME/.wheel/operator-token}")") \
            -H 'content-type: application/json' "http://127.0.0.1:8080$path" "$@"; }

P=$(wh /v1/projects -d '{"name":"hello"}' | jq -r .id)            # a project; its engine starts with it

wh /v1/projects/$P/board/apply -d '{"board": {
  "nodes": [ {"name": "keys",   "type": "vault", "config": {"keys": []}},
             {"name": "worker", "type": "agent", "config": {"harness": "claude", "system_prompt": "Be brief."}} ],
  "wires": [ {"from": "worker", "to": "keys", "type": "read"} ] }}'

id() { wh /v1/projects/$P/engine/v1/board | jq -r --arg n "$1" '.nodes[] | select(.name == $n) | .id'; }
printf '{"value":"%s"}' "$ANTHROPIC_API_KEY" | wh /v1/projects/$P/engine/v1/vault/$(id keys)/ANTHROPIC_API_KEY -X PUT -d @-
wh /v1/projects/$P/engine/v1/agents/$(id worker)/start -X POST
wh /v1/projects/$P/engine/v1/agents/$(id worker)/send -d '{"body": "Say hello."}'
wh "/v1/projects/$P/engine/v1/agents/$(id worker)/log?limit=50"

Want the board UI too? WHEEL_API_URL=http://127.0.0.1:8080 npx wheel-web (needs Node 22+).

Building wheeld from source, the board UI in depth, production deployment (systemd, reverse proxy, signup, Railway/VM/Kubernetes), signing an agent in via OAuth instead of an API key, and the full board-authoring reference (node/wire shapes, dry_run, the HTTP gate, converting a saved board back into a spec): docs/SETUP.md.

Agents and credentials

Agents are Claude Code / Codex processes. Give them credentials through a vault node (one per account; wire the agent to it) or the agent's Authenticate panel (in-browser login, claude setup-token, or an API key). See docs/ARCHITECTURE.md for the model and docs/WHEEL-ON-WHEEL.md for a board that develops Wheel itself.

Development

Wheel develops itself; there is a cloud board (template available for free) that handles each moving piece separately so that the agents can figure out what they need and build it themselves. If you want to contribute to wheel, you can clone it and get started in the crates/, web/, or docker/ directory.

Legal disclaimer, asshole

Wheel is independent, original work. It shares no code, assets, copy, designs, or other protected material with any other product, and it wasn't built using anyone's confidential or proprietary information.

Ideas aren't ownable; expression is. Wheel is my own expression of ideas that are common to this category of tooling. If you think otherwise, the contact address is in the LICENSE — put it in writing.