#Colonizer

Colonize your backlog.

Colonizer sends coding agents out to settle your issues. Each one lands in its own colony, a real microVM with a fresh worktree, stays linked to home over a private mesh, and returns with a pull request you can trust. You stay in command: agents bring you decisions as choices, not walls of text.

#Why

Coding agents are good enough to work unsupervised for long stretches, but most setups make you choose between safety (sandboxed, slow, one at a time, constant approvals) and speed (an agent with your credentials loose on your laptop). Colonizer removes that trade-off:

• every task gets a disposable, hardware-isolated machine, so the agent can do anything inside it;
• credentials never enter it;
• you can run many at once and steer them with one click each.

#Vocabulary

Use the metaphor lightly in the product; plain words win whenever clarity is at stake.

#Principles

1. Real isolation by default. Colonies are KVM microVMs, not shared-kernel containers. Secrets are injected at the network edge and never exist inside a colony.
2. Decisions, not prose. When an agent needs a human, it asks with concrete choices (plus "Other"). A good question takes one click to answer.
3. Everything is a module. Sources, sandboxes, meshes, settlers, interfaces and publishers are swappable providers behind small contracts.
4. Local-first and self-contained. Runs on your hardware and ships its own dependencies, with no cloud account required. After install, the downloads are the colony images colonies run, the optional bundles you switch on (such as Headroom), the pinned OpenCode binary when a colony runs that agent module, and a release check every six hours, which you can switch off.
5. Scale out, stay close. Many colonies run in parallel; the mesh keeps each one a hop away for chat, terminals and previews.
6. Trust, then verify. Colony output is untrusted data until the mothership has sanitized and published it, and a human has reviewed the pull request.

These are the design. Where the code does not yet meet the security and trust claims, audit.md says so; where something this page describes or the website illustrates has not been built yet, gaps.md says so, with its tracking issue where one is filed.

#Horizon, and where it stands

Checked against the code on main. Built means merged and usable; partly says which part; not built means nothing runs yet.

#Two things, and which is which

Two labels are used everywhere below, and they set the tense of the sentence around them:

• SHIPPING: merged, in this repository, and exercised on a real machine.
• PLANNED: named, not specified, not started.

#Shape

#The argument, in five points

1. A colony is a machine, not a container. Each task runs in a KVM microVM (microsandbox, libkrun) with its own kernel. The agent runs without permission prompts because there is nothing on the other side of the wall worth protecting.

2. Secrets stay home. Git objects are mounted read-only, so the agent can read history but not rewrite it. The mothership commits, pushes and opens the pull request after the microVM is gone, and it treats everything the colony left behind as untrusted: .git is rewritten, nested repositories are removed, and git runs with hooks and fsmonitor disabled.

3. Every colony is one hop away. The mothership runs its own Headscale and a userspace tailscaled, both bundled. Every colony joins with a single-use key. The network is separate from any tailnet the machine is already on. The mothership can reach colonies, and colonies can't reach each other. One narrow UDP rule per colony keeps WireGuard direct (about 1 ms) instead of relayed.

4. Decisions, not prose. Agents bring you choices. Your job is to pick one, not to parse a paragraph that ends in a question mark.

5. Everything is a module. Source, sandbox, mesh, agent, interfaces and publish are providers behind small contracts, selected in the UI and saved in modules.json. The agent contract is a JSON Lines protocol on stdio, so an agent module can be written in anything.

The agent modules so far. An org can pick which installed agent module its colonies launch on (Org settings → Agent module; without a pick, the mothership's agent choice applies):

#A question, from inside a colony

Real, from a colony working on this repository. Unedited apart from line breaks.

{"type": "question", "seq": 14,
 "question_id": "toolu_01Kz2S34mniQ6KJ476Twd2X3",
 "questions": [{
   "header": "README tweak", "multi_select": false,
   "question": "Which small README improvement do you prefer?",
   "options": [
     {"label": "Add a table of contents",
      "description": "Insert a short linked ToC near the top (Requirements, Install, Trust model, Configuration, Development, Run as a service) so readers can jump to a section in this fairly long README."},
     {"label": "Add a Quick Start block",
      "description": "Add a 3-line 'Quick Start' snippet right under the intro paragraph (clone, install.sh --install, open the URL) so skimmers get running before reading Requirements/Trust model/Configuration."}
   ]}]}

The web UI renders that as a card with both options and an Other… answer. One click sends question_answered back through the mothership, over the mesh, to the agent that is waiting for it.

Agents never ask in plain text. The Claude Code module routes AskUserQuestion into this event, and if a turn still ends on a plain-text question, the runner holds the turn open and has the agent ask again as a card. Autopilot can't publish in the middle of a question.

#Roadmap, in public

The roadmap is the issue tracker. There is no private version of it. On top of it, the v0.1.3 audit sets four release checkpoints (docs/audit.md).

#Brand

• Name: Colonizer, at colonizer.dev.
• Voice: calm, technical, confident; a touch of frontier and space flavor, used sparingly.
• Look: deep-space neutrals with one beacon-orange accent; a simple hexagon outpost mark.