Getting Started

Colony is a multi-agent development environment that orchestrates AI agents to build software collaboratively. This guide will help you get up and running in minutes.

Prerequisites

Before you begin, make sure you have:

• Nix with flakes enabled (all other tools are provided by the flake)
• An Anthropic API key (set ANTHROPIC_API_KEY in your environment)

Installation

Clone the Colony repository and set up the development environment:

git clone https://github.com/your-org/colony.git
cd colony
make init    # Install deps, generate proto, setup DNS
make dev     # Start all services (Mycelium + Bloom + Caddy + hld)

The Nix flake provides all dependencies:

• Gleam 1.14.0 (Mycelium backend)
• Rust 1.93+ (Stem TUI)
• Bun 1.3+ (Bloom web dashboard)
• Erlang/OTP 27
• Caddy, dnsmasq, overmind, jujutsu

Start Colony

make dev starts all services via overmind (Procfile-based process manager):

• Mycelium — Gleam orchestrator on port 8000
• Bloom — SolidJS dashboard on port 3000
• Caddy — Reverse proxy for *.colony.local subdomains
• hld — HumanLayer agent daemon

Verify Mycelium is running:

curl http://localhost:8000/health
# {"status":"healthy"}

Your First Colony

Spawn a colony via the HTTP API:

curl -X POST http://localhost:8000/api/colonies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-colony",
    "repo_url": "https://github.com/user/my-app",
    "branch": "main"
  }'

The colony will clone the repo, read colony.toml for service definitions, and start services automatically.

What Just Happened?

When you spawned the colony, Colony:

1. Cloned the repository — into /tmp/colony-{id}
2. Parsed colony.toml — read service definitions and configuration
3. Provisioned the environment — set up tools and dependencies
4. Registered Caddy routes — set up hello-colony-{port}.colony.local per service
5. Spawned an OTP actor — dedicated actor managing the colony lifecycle
6. Started services — each [services.*] entry from colony.toml
7. Started logging — ring buffer capturing all colony activity

Access Your Colony

With DNS configured, access your colony services at their registered subdomains (e.g., hello-colony-4001.colony.local). Without DNS, use localhost with the service port directly.

Next Steps

Now that you have a running colony:

• Learn about colony lifecycle — Understanding spawn, stop, and delete
• Explore the Bloom dashboard — Web UI for managing colonies
• Configure templates — Create custom colony templates
• Set up agent backends — Connect Claude Code or other AI agents
• Read the architecture guide — Deep dive into how Colony works

Getting Help

• Documentation: Browse the full docs
• Blog: Read architecture posts
• Issues: Report bugs on GitHub
• Community: Join discussions on Discord (link coming soon)

Welcome to Colony! Let’s build something amazing together.