cargo install colonizer-harness --locked && colonizer setup
# no Rust toolchain? curl -fsSL https://colonizer.dev/install.sh | sh
Not ready for unattended work on sensitive repositories. An external audit of v0.1.3 found four
ways past the wall that keeps secrets on the host, and they are not fixed yet
(docs/audit.md).
What it is
- A colony per task. Every task gets its own KVM microVM with a fresh git worktree and an agent
inside. The agent can do anything in there.
- Secrets stay home. The GitHub token never enters a colony, and the agent's API credential is
swapped in by the sandbox's host-side TLS proxy on the way out (trust model).
- One hop away. Every colony joins a private mesh with the machine that launched it, so its chat
and a real terminal are right there.
- Decisions, not prose. When the agent needs you, it asks with choices. When the work is done, your
machine, the mothership, commits it and opens the pull request.
- The open-source core. MIT, running on one machine today: Linux with KVM, an Apple Silicon Mac,
or Windows 11 through WSL2. The hosted Colonizer is not built yet.
Run it
You need git, gh, curl and tar. On Linux — or Windows 11 through
WSL2 — give your user /dev/kvm
(sudo usermod -aG kvm "$USER", then log out and back in) and install native Claude Code, which
colonies run. Install the latest release with a
Rust toolchain (1.88 or newer), or without one by piping the installer script instead — the crate is
on crates.io as colonizer-harness, and setup fetches that release's own installer for the version
it installed. Either way the release is checked against its SHA256SUMS and its build attestation,
and ~/.local/bin/colonizer is linked (if ~/.local/bin is not on your PATH, run that path); then:
colonizer # starts the mothership, prints a sign-in link and opens it
colonizer open # reprints the link
colonizer --help # the rest
To build from source (Node.js 20.19+ or 22.12+, and Rust 1.98+):
git clone https://github.com/Colonizer-dev/harness && cd harness
scripts/install.sh # builds everything into ./dist
dist/bin/colonizer
How it works
The colonizer binary on your machine is the mothership: it runs the web UI, a bundled Headscale and
userspace tailscaled, and the provider gateway. Each colony is a microVM running colonizer-agentd,
which supervises the agent runner (Claude Code by default) against /workspace. The agent contract is
JSON Lines on stdio, so an agent module can be written in anything. Colony output is untrusted until
the mothership has sanitized it and opened the pull request. The diagram is in
docs/vision.md; the design is in docs/architecture.md.
Docs
Development
Try the cockpit without a mothership: (cd web && npm run dev), then open
http://127.0.0.1:5173/?mock=1 for the UI against an in-browser mock backend. Every test suite and
script is in docs/development.md.
Contributing and license
See CONTRIBUTING.md and SECURITY.md. MIT, see LICENSE.
Vendor logos in the UI are CC0 artwork from Simple Icons; the marks stay their owners' trademarks. See
NOTICE.
