GuiBibeau/solos-swarm

solos-swarm runs AI coding agents on Linux under a governed kernel. A broker makes every model call for the agents,
so no agent holds a key. It holds each call's cost against a budget in integer microUSD, settles it from the
provider's reported usage, and refuses calls while the operator pauses. Agents run in bubblewrap sandboxes, and every
event goes to a hash-chained log. One Rust workspace builds one binary, solos-swarm, with two modes on that kernel.
## Try it
You need Linux or a Linux VM, and Rust 1.96.0. The smoke command needs no key, no network and no sandbox.
sh
cargo build --locked --release
./target/release/solos-swarm smoke --dir work/smoke
The second command prints one JSON line with "verdict":"PASS" and "live_spend":0. Every entry in checks has
"ok":true: claim, settle_once, no_held_budget, pause_refuses_model, unpause_admits, drain_settles,
drain_holds_nothing and resume_keeps_ledger. It runs the binary's own broker, ledger, pause gate, drain and resume
against a scripted provider.
## Numbers
A recorded live run from 2026-04-12 on deepseek-chat (run live-20260412-132831), not a target. Source:
docs/BENCHMARKS.md.
## Two modes
Swarm mode (solos-swarm run) is a batch run: one Goal, 1 to 30 sandboxed Pi agents, a deadline and one
artifact. Each agent claims a Task, posts progress to a shared Board and submits a Finding, and a coordinator
combines the Findings into the artifact. The broker holds each call's worst-case cost against the Goal's budget and
the Task's envelope, then settles the reported usage, with cache hits at the cache price. scripts/remote.py operates
runs on a Linux host over SSH, with immutable candidates, stable and canary channels, pause, drain and doctor.
Agent mode (solos-swarm agent serve) is an always-on agent. It takes requests from Discord, Slack, GitHub,
schedules and MCP hosts such as Claude Code and Codex. A Router model judges each request, and accepted work becomes
a Ticket that runs on a sandboxed worker (Pi or Claude Code) or on a governed swarm. A worker's commands can run on
a remote node of yours. The agent answers in the thread the request came from.
On GitHub it acts as the bot of its own GitHub App (solos-bot in production). A worker commits in a clone, and
its ready report becomes a pull request that the host pushes and opens. No token reaches a worker.
Workers use vault logins and API keys without seeing their values, and browse with a headless browser that signs
every step. solos-swarm agent trail checks those steps with public keys only.
The agent keeps memos: facts and lessons the owner writes or workers propose, which a separate review call keeps
or rejects. A proposal that quotes outside text is never reviewed: it waits for the owner. A daily dream checks the
memos against the day's transcripts.
agent status, agent health, agent prune, agent stop and a web dashboard of Tickets serve the operator.
The two modes share the model gateway (src/gateway/: prices, providers, the upstream request and the pause gate),
the harness port (src/harness.rs), the sandbox builder (src/bwrap.rs) and run_code (src/code.rs). A swarm is
also one way agent mode runs a Ticket. Agent mode's domain is the pure crate crates/agent-core, and its SQLite