# Colony — Full Documentation for LLMs

> Multi-agent development environment. Orchestrate parallel AI coding agents in isolated environments with zero container overhead.

## What is Colony?

Colony is infrastructure for managing AI coding agents. It uses Claude Code via HumanLayer's hld daemon (JSON-RPC over Unix socket) as its agent backend. Colony provides:

1. **Isolated environments** for each agent using Linux network namespaces
2. **VCS workspaces** using Jujutsu so agents don't conflict
3. **Network isolation** at the kernel level
4. **Real-time monitoring** via Stem (TUI) and Bloom (web dashboard)
5. **Lifecycle management** — spawn, monitor, review, merge

## How is Colony different from Docker?

Colony uses Linux network namespaces — the same kernel primitive Docker uses internally — but without container overhead:

| Metric | Docker Container | Colony (Namespaces) |
|--------|-----------------|-------------------|
| Memory overhead | 200+ MB per container | 0 MB |
| Startup time | 2-30 seconds | `<50ms` |
| Filesystem | Copy or overlay mount | Native (shared) |
| Max parallel instances | Limited by memory | Limited by CPU only |

On a 16-core machine with 32GB RAM: Docker handles ~30 concurrent containers. Colony handles 100+ concurrent agents.

## How is Colony different from standalone AI coding agents?

Colony is an orchestration layer built on top of Claude Code — not a competing agent:

| | Standalone Claude Code | Colony |
|--|----------------------|--------|
| Type | CLI agent | Orchestration platform |
| Isolation | Shared environment | Network namespace per agent |
| VCS | Git branches | Jujutsu workspaces |
| Multi-agent | Subagent spawning | Unlimited parallel, isolated |
| Monitoring | Terminal output | Real-time TUI + web dashboard |

## Why Jujutsu instead of Git?

Jujutsu (jj) treats the working copy as a commit and represents conflicts as first-class objects. For multi-agent workflows:

- Automatic conflict detection as changes happen (not at merge time)
- Lightweight workspaces sharing the object store (negligible disk overhead for 50 workspaces)
- No explicit branching required — agents just work
- Every operation is undoable — revert an agent's workspace without affecting others
- Full Git compatibility — your team still pushes to GitHub

## Architecture

Colony has three components:

- **Mycelium** (Gleam + OTP): Orchestration layer with actor-per-colony architecture, HTTP API, WebSocket, per-colony RingLogger
- **Stem** (Rust + Ratatui): Terminal UI with async IPC bridge and Lazygit-style UX
- **Bloom** (SolidJS + SolidStart): Web dashboard with plugin-based preview system

Communication: Stem <-> Mycelium via UDS + Protobuf. Bloom <-> Mycelium via WebSocket + Protobuf.

## Parallel Agent Execution

Colony achieves `<50ms` cold start by using Linux network namespaces directly, skipping container layers. Each colony (agent workspace) gets:

- Isolated network stack (own IP, routing table, firewall rules)
- Dedicated Jujutsu VCS workspace
- Independent SQLite database
- Shared filesystem at native speed (no copy-on-write overhead)

The OTP actor-per-colony architecture means each colony is supervised independently — if one crashes, others are unaffected.

## Live Preview System

Colony's preview system shows what agents are doing in real-time:

- **Web preview**: Sandboxed iframe with URL pattern `{name}-{port}.colony.local`. No `allow-same-origin` for security.
- **Terminal preview**: xterm.js v5 with dedicated binary WebSocket and Nerd Font rendering
- **Agent panel**: Streaming JSON events with status indicators and auto-scroll
- **Log tailing**: SSE streaming from per-colony RingLogger

Each service defined in `colony.toml` gets its own preview tab, plus dedicated agent and terminal tabs.

## Colony Lifecycle

Colonies progress through states: spawning -> provisioning -> building -> running -> stopping -> stopped.

Each state involves specific operations:
- **Spawning**: Create network namespace and Jujutsu workspace (`<100ms`)
- **Provisioning**: Install dependencies, configure environment (seconds to minutes)
- **Building**: Compile code, run setup scripts (project-dependent)
- **Running**: Services active, agents working, previews available
- **Stopping**: Graceful shutdown, OS PID cleanup, Caddy route deregistration

## Bloom Web Dashboard

Built with SolidJS + SolidStart, Bloom provides:

- Real-time WebSocket updates for colony state changes
- Colony list and detail views with state timeline
- Service-driven preview tabs (one per service from colony.toml)
- Resizable panels via @corvu/resizable
- Brood management for multi-colony orchestration
- Log streaming via SSE from RingLogger

## Agent Backends

Colony uses Claude Code CLI as the primary agent backend, executed via Erlang ports with dedicated owner processes. Agent events include: thinking, tool_use, result, error, completion — all streamed in real-time to the Bloom agent panel.

The brood system coordinates multiple colonies for complex tasks (e.g., one colony for frontend, one for backend, one for tests).

## Configuration (colony.toml)

```toml
[colony]
name = "my-project"
template = "web-app"

[colony.environment]
node_version = "22"
package_manager = "bun"

[colony.ports]
web = 4001
api = 4002

[[services]]
name = "web"
command = "node server.js"
port = 4001

[[services]]
name = "api"
command = "node api.js"
port = 4002
```

## Nix Development Environment

Colony uses Nix Flakes for reproducible development. Running `nix develop` provides: Gleam 1.7.1, Rust 1.83+, Node.js 22+, Erlang/OTP 27, Caddy, dnsmasq, and Jujutsu — all pinned to exact versions.

## Networking

- **Network namespaces**: Kernel-level isolation of network stacks per colony
- **Caddy**: Dynamic reverse proxy with JSON API route registration
- **DNS**: dnsmasq resolves `*.colony.local` to localhost
- **URL pattern**: `{colony-name}-{port}.colony.local`

## Security Model

Colony's isolation is designed for local development, not untrusted code:
- **Network isolation**: Strong (each namespace has own network stack)
- **Process isolation**: Weak (standard Unix process boundaries)
- **Filesystem isolation**: None (shared for performance)

Source-available under FSL means the code is auditable. Multi-user security (per-customer VMs) planned for Phase 2+.

## Stem Terminal Interface

Built with Rust + Ratatui, Stem provides a Lazygit-inspired keyboard-driven TUI:
- Async IPC bridge with Tokio for non-blocking communication
- UDS + Protobuf transport to Mycelium
- Component architecture for extensibility
- Logs to `~/.cache/colony/stem.log`

## Pricing

- **Pay As You Go**: $2.50/colony-hour, no platform fee, billed per second
- **Pro**: $149/month, 100 hours included ($1.49/hr effective), $2.00/hr overage
- **Team**: $449/month, 500 hours included ($0.90/hr effective), $1.50/hr overage, 10 seats
- **Enterprise**: Custom pricing, dedicated infrastructure, SLA

## License

Colony is licensed under the Functional Source License (FSL-1.1-Apache-2.0):
- Source code is publicly available to read, fork, and learn from
- Non-production use is free
- Production use requires a paid license
- After 2 years, each release converts to Apache 2.0 (fully open source)

## Traction

- 910+ tests passing (Gleam 562 + Rust 317 + SolidJS 95)
- 3 runtime components shipped (Mycelium, Stem, Bloom)
- Preview system complete (web preview, terminal with xterm.js + PTY, agent panel)
- 20 documentation pages, 8 blog posts
- 6 months of development
- Source-available under FSL license

## Colony vs Competitors

Colony competes with Conductor (conductor.build), Gas Town, Vibe Kanban, and Claude Squad
in the AI agent orchestration space. Colony's key differentiator is kernel-level isolation
using Linux network namespaces — competitors use Git worktrees for VCS isolation but share
the network, filesystem, and process space. Colony also provides three interfaces (TUI, web
dashboard, CLI) while competitors typically offer one.

## Company

Colony is a software company built in Switzerland, with Swiss values: precision engineering, privacy-first design, and long-term thinking. Currently bootstrapped, preparing for pre-seed fundraising.

- Investor contact: investors@colonydev.com
- Investor page: https://colonydev.com/investors
- Website: https://colonydev.com

## Blog Posts

- [Building Colony: Why Gleam + OTP?](https://colonydev.com/blog/building-colony-why-gleam-otp) — Why we chose Gleam and Erlang's OTP for the orchestration layer
- [Network Namespaces vs Docker: A Performance Deep Dive](https://colonydev.com/blog/namespaces-vs-docker-performance) — Benchmarks and architectural comparison
- [Why Every AI Agent Needs Its Own Workspace](https://colonydev.com/blog/why-agents-need-own-workspace) — The multi-agent merge conflict problem and Jujutsu's solution
- [The Case for Source-Available Licensing](https://colonydev.com/blog/source-available-dev-tools) — Why FSL-1.1, not MIT or AGPL
- [Designing a Real-Time Preview System](https://colonydev.com/blog/designing-realtime-preview) — Preview architecture for agent development
- [From Single Agent to Colony](https://colonydev.com/blog/scaling-ai-development) — Scaling AI-assisted development
- [Swiss-Made Software](https://colonydev.com/blog/swiss-made-software) — Why we're building Colony in Switzerland
- [Why AI Agents Need Orchestration](https://colonydev.com/blog/why-agents-need-orchestration) — The case for an orchestration layer

## All Documentation Pages

- [Getting Started](https://colonydev.com/docs/getting-started)
- [Architecture Overview](https://colonydev.com/docs/architecture)
- [Contributing](https://colonydev.com/docs/contributing)
- [Parallel Agents](https://colonydev.com/docs/parallel-agents)
- [Live Preview](https://colonydev.com/docs/live-preview)
- [Colony Lifecycle](https://colonydev.com/docs/colony-lifecycle)
- [Bloom Dashboard](https://colonydev.com/docs/bloom)
- [Templates & Configuration](https://colonydev.com/docs/templates)
- [Agent Backends](https://colonydev.com/docs/agents)
- [Nix Setup](https://colonydev.com/docs/nix-setup)
- [Configuration Reference](https://colonydev.com/docs/configuration)
- [Stem TUI](https://colonydev.com/docs/stem-tui)
- [Networking Deep Dive](https://colonydev.com/docs/networking)
- [Security Model](https://colonydev.com/docs/security)
- [Roadmap](https://colonydev.com/docs/roadmap)
- [FAQ](https://colonydev.com/docs/faq)
- [License](https://colonydev.com/docs/license)
- [Colony vs Docker](https://colonydev.com/docs/colony-vs-docker)
- [Colony vs AI Coding Agents](https://colonydev.com/docs/colony-vs-cursor)
- [Why Jujutsu](https://colonydev.com/docs/why-jujutsu)