# Colonizer

> Colonizer turns GitHub issues into pull requests. Each task gets a coding
> agent (Claude Code today) inside its own disposable KVM microVM with a fresh
> git worktree, linked to your machine over a private mesh. The host, not the
> microVM, commits, pushes and opens the pull request. The open-source core,
> the harness, is MIT and runs on one Linux machine today. Everything beyond
> one machine is planned and not built. This file keeps the two apart so that
> a machine reader does not describe a planned feature as available.

Site: https://colonizer.dev/
Source: https://github.com/Colonizer-dev/harness
Organization: https://github.com/Colonizer-dev
License: MIT (the harness)
Maker: Factory Zero (https://factory0.ventures)
Contact: contact@colonizer.dev
Tagline: Colonize your backlog.
Price: the harness is free and open source; you run it on your own machine with
your own keys. Nothing is hosted, and nothing beyond the harness has a price,
published or estimated.
Requirements: Linux x86_64 with /dev/kvm readable and writable by your user,
microsandbox, git, gh, Node.js 20 or newer, a Rust toolchain, and a native
Claude Code install. No macOS.

## Status labels

- **Shipping**: merged, in the public repository, and exercised on a real
  machine. Present tense is used only for these.
- **Planned**: named, not specified, not started.

## Vocabulary

- Mothership: the Colonizer app on your machine. Holds credentials, git, the
  mesh control plane, and publishes results.
- Colony: one session. A microVM, a git worktree and an agent, on one task.
  Disposable.
- Settler: the agent module working inside a colony. Claude Code today.
- Frontier: your backlog of issues and repositories.
- Mesh: the private network linking every colony to the mothership, separate
  from any tailnet you already use.
- Return: bringing a colony's work home as a pull request.

## Shipping today (the harness)

- Colonies from a GitHub issue or a repository, each on its own branch in a
  fresh git worktree, in its own microsandbox microVM (libkrun, KVM, its own
  kernel).
- Chat with the agent. Its questions always arrive as multiple-choice cards with
  an "Other…" answer; a plain-text question is sent back to be asked as a card.
- A terminal inside the same microVM.
- A private mesh: bundled Headscale plus a userspace tailscaled. The mothership
  reaches colonies; colonies cannot reach each other. Single-use pre-auth keys,
  nodes deleted when the colony ends.
- Publish: after the microVM is removed, the host commits, pushes and opens the
  pull request. Autopilot can do it when a turn ends with changes and no open
  question.
- Modules, one provider per kind: source `github`, sandbox `microsandbox`, mesh
  `headscale` (or a loopback port), agent `claude-code`, interfaces (chat,
  terminal), publish `github-pr`. Stored in `~/.config/colonizer/modules.json`
  and edited in Settings → Modules.
- The agent contract is JSON Lines on stdio (`colonizer-runner/1`), so an agent
  module can be written in any language.
- Packaging: `scripts/install.sh` bundles pinned, sha256-verified Headscale and
  Tailscale, the static `colonizer-agentd`, the agent modules and the web UI
  into one directory. Nothing is downloaded at runtime.
- Web UI on 127.0.0.1:7878 by default, with Host and Origin checks.

## Trust model

- GitHub token: host only. Commit, push and `gh pr create` run on the host after
  the colony is gone.
- Claude token: host only. The colony sees a placeholder; microsandbox's TLS
  proxy substitutes the real value for api.anthropic.com only.
- Worktree mounted read-write at /workspace. Git objects and worktree metadata
  mounted read-only, so `git status`, `diff` and `log` work inside a colony and
  commits do not.
- Colony output is untrusted until published: `.git` rewritten, nested `.git`
  removed, host git runs without hooks or fsmonitor, `pr.md` must be a regular
  file.
- colonizer-agentd requires a per-colony bearer token, even inside the mesh.

## What it does not do yet

- One machine, Linux x86_64 with KVM. No macOS, no remote hosts.
- One agent and one forge: Claude Code and GitHub.
- The web UI has no login. It binds to loopback and should stay there.
- Not yet run end to end: opening a pull request from a colony, and
  `install.sh --install`. Both are implemented.
- No CI, no releases, nothing published to crates.io or npm.

## Planned, not built

- A model router: route each request to a model by intent, size and risk, with
  per-colony budgets and a hard cap. Today a colony runs the model set in the
  Claude Code module's settings.
- More settlers behind the same runner protocol: Codex, OpenCode, a DeepSeek
  harness.
- Providers beyond Anthropic: OpenAI, DeepSeek, Google, OpenRouter, local models.
- Remote outposts and a fleet view: other machines join the mesh and host
  colonies. There is a waitlist at https://colonizer.dev/#waitlist.
- More frontiers: GitLab, Linear and Jira; review comments as follow-up tasks.
- Guardrails: per-colony budgets, network policies and approval rules as modules.
- Dev-server previews over the mesh.
- A teams offering. There is no price; the site says to email.

## The page

The site is one page. The colony window in section 01 is labelled an
illustration: its issue titles, chat and terminal lines are examples, not a
recording. The quickstart terminal replays output lines printed by
`scripts/install.sh` and `crates/colonizer/src/main.rs`.

## Links

- README: https://github.com/Colonizer-dev/harness#readme
- Architecture: https://github.com/Colonizer-dev/harness/blob/main/docs/architecture.md
- Protocol: https://github.com/Colonizer-dev/harness/blob/main/docs/protocol.md
- Vision: https://github.com/Colonizer-dev/harness/blob/main/docs/vision.md
- Trust model: https://github.com/Colonizer-dev/harness#trust-model