Getting Started with Colony

Getting Started with Colony

Go from git clone to watching Colony process its first issue in under 30 minutes.

Audience: A senior engineer comfortable with TypeScript, GitHub, and containers evaluating Colony on a test repo.

This is the single starting point for new users. Everything you need is on this page. Reference docs are linked for deeper dives but are never required reading:

• Installation Guide — Prerequisites deep-dive (platform-specific install commands, resource sizing)
• Configuration Reference — Complete field-level reference for all config options
• First Issue Tutorial — Extended guide for issue scoping, analyzer plans, slash commands, and gotchas
• Failure Modes Guide — Top 5 failure modes with symptoms, diagnosis, and fixes

CLI note: All colony commands use npx colony since the CLI is a workspace dependency. Alternatively, run npm link in packages/cli to make colony available globally.

---

Quickstart (~5 min)

The fastest path. One command launches an interactive wizard that walks you through each setup step:

git clone https://github.com/RunColony/colony.git
cd colony
npm install && npm run build

# Interactive wizard: prompts for API keys, config, database, and starts agents
npx colony quickstart

The wizard guides you through six phases:

🚀 Colony Quickstart

This wizard will guide you through setting up Colony step by step.

── Step 1: Environment
   Validate prerequisites and API keys

── Step 2: Repository
   Configure your target repository

── Step 3: Database
   Set up the Colony database

── Step 4: Cost Preview
   Understand and configure cost limits

── Step 5: Launch
   Write config, initialize repo, and start agents

── Step 6: First Issue
   Create a test issue to see Colony in action

The command is idempotent — running it again skips completed steps and detects already-running agents.

If quickstart completes successfully, skip to Step 6: Process Your First Issue.

If you prefer fine-grained control over each step, follow the manual setup below.

---

Manual Setup

1. Prerequisites (~5 min)

Before you begin:

• Node.js 20+ — node --version should print v20.x or higher
• Git — git --version
• Claude Code CLI — npm install -g @anthropic-ai/claude-code, then verify with claude --version
• Anthropic API key — get one at console.anthropic.com
• GitHub account with a test repository (public or private)

Platform-specific install commands

Node.js 20+

# macOS (Homebrew)
brew install node@20

# Other platforms — see https://nodejs.org

Git

git --version

If not installed: xcode-select --install (macOS) or your platform’s package manager.

Claude Code CLI

npm install -g @anthropic-ai/claude-code
claude --version

Container runtime setup (optional)

Colony can run as containers (Docker or Apple Container) or as native Node.js processes. Containers are recommended for production; native is fine for evaluation.

Docker Desktop

# macOS
brew install --cask docker

# Linux — see https://docs.docker.com/engine/install/

Apple Container (macOS only)

Requires macOS 15+ and Apple Silicon.

brew install container
container system start
container system property set build.rosetta false

Resource recommendations

Deployment	Workers	Memory	CPUs	Disk
Single repo (eval)	1	8 GB	4	50 GB
Single repo (prod)	2-3	16 GB	8	100 GB
Multi-repo	3+	32 GB	16	200 GB

For the full prerequisites reference, see Installation Guide.

Next: Choose your deployment mode.

---

2. Choose Deployment Mode (~1 min)

This affects how you set up the database and how Colony runs. Pick one before configuring anything else.

Mode	Best for	Database	How agents run
Docker Compose	First-time users, production	Bundled (included in compose)	docker compose up -d
Apple Container	macOS with Apple Silicon	External (Neon or local Docker)	./scripts/colony-container.sh up -d
Native	Quick local evaluation	External (Neon or local Docker)	npx colony start

Recommendation: Use Docker Compose for your first setup — it bundles Postgres and requires the least configuration. Use Native if you want the simplest possible evaluation without containers.

Next: Set up your database.

---

3. Database (~3 min)

Colony stores pipeline state in Postgres.

If you chose Docker Compose: Skip this step — Postgres is included. Jump to Step 4.

If you chose Native or Apple Container, pick one:

Option A: Neon (free hosted Postgres)

1. Sign up at neon.tech — free tier is sufficient.
2. Create a project and database.
3. Copy the connection string (includes ?sslmode=require).

export DATABASE_URL="postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/colony?sslmode=require"

Option B: Local Docker Postgres

docker run -d --name colony-pg -e POSTGRES_USER=colony -e POSTGRES_PASSWORD=colony -e POSTGRES_DB=colony -p 5432:5432 postgres:17-alpine
export DATABASE_URL="postgresql://colony:colony@localhost:5432/colony"

Migrations run automatically when agents start — no manual migration step needed.

Next: Configure Colony.

---

4. Configure (~5 min)

Clone and build

git clone https://github.com/RunColony/colony.git
cd colony
npm install && npm run build

Set up GitHub authentication

Colony needs access to your GitHub repository. For evaluation, a Personal Access Token is quickest:

1. Go to github.com/settings/tokens and create a token.
2. Required permissions: repo scope (classic) or Contents/Issues/Pull requests read-write (fine-grained).

For production use, a GitHub App provides higher rate limits and bot-attributed activity. See the GitHub App Setup Guide for instructions, including the dual-app setup needed for fully autonomous merging.

Generate config

Alternatively, copy the annotated example config and edit it directly:

cp colony.config.example.yaml colony.config.yaml

Every required field is marked with a # CHANGE THIS: comment. This is the fastest path if you prefer editing a file over an interactive wizard.

Or use the interactive wizard:

npx colony init --generate

This prompts for your repo, auth method, database URL, local repo path, review checks (auto-detected from your project), and Claude model preference. It writes colony.config.yaml.

For the complete field reference, see Configuration Reference.

Set environment variables

export GITHUB_TOKEN=ghp_your_token_here
export ANTHROPIC_API_KEY=sk-ant-your_key_here

# Skip if using Docker Compose (it bundles Postgres):
export DATABASE_URL=postgresql://colony:colony@localhost:5432/colony

Docker deployments: Copy .env.example to .env and set values there instead of exporting shell variables.

Next: Initialize your repo.

---

5. Initialize and Start (~5 min)

Initialize your repository

This creates Colony’s pipeline labels and branch protection on GitHub:

npx colony init -r your-org/your-repo

Expected output:

Initializing Colony for your-org/your-repo...
  ✓ Repository access validated
  ✓ XX pipeline labels created/verified
  ✓ Flag labels created/verified
  ✓ Branch protection ruleset configured

Run pre-flight check

npx colony doctor

Fix any failures before starting. Common issues:

Error	Fix
Cannot access your-org/your-repo	Check token has repo scope and repo name is correct
Claude CLI not found	npm install -g @anthropic-ai/claude-code
DATABASE_URL not set	Export the connection string or use Docker Compose

Start Colony

Docker Compose:

cp .env.example .env
# Edit .env — set GITHUB_TOKEN, ANTHROPIC_API_KEY

docker compose build
docker compose up -d

# Verify:
docker compose ps
# All services should show "running (healthy)"

Apple Container (macOS):

./scripts/colony-container.sh build
./scripts/colony-container.sh up -d

# Verify:
./scripts/colony-container.sh health

Native:

npx colony start

# Verify:
npx colony status

Health check endpoints (all deployment modes):

curl -sf http://localhost:9100/health  # sprint-master
curl -sf http://localhost:9200/health  # worker
curl -sf http://localhost:9106/health  # monitor + dashboard

Webhooks are optional. Colony works out of the box using polling (Sprint Master checks GitHub every 30 seconds). Webhooks provide near-instant response but aren’t needed for evaluation. See Webhook Setup to configure them later.

Next: Process your first issue.

---

6. Process Your First Issue (~5 min)

Tips for writing a well-scoped first issue

Colony works best on issues that are small, self-contained, and clearly described. For your first issue, pick something that:

• Has a single responsibility. One feature, one bug fix, or one refactor — not a combination.
• Has clear acceptance criteria. Describe what “done” looks like so the analyzer can write a concrete plan.
• Doesn’t require secrets or external services. Colony’s developer agent runs in an isolated worktree. It can read and write code, run build/test/lint commands, and interact with the local filesystem — but it cannot access external APIs, databases, or secret stores during implementation.
• Touches a small number of files. Fewer than 5–10 files is ideal for a first run. Large cross-cutting changes are better handled after you’re comfortable with the pipeline.

Size guidance: A good first issue changes 1–3 files and under 200 lines total. Larger changes are more likely to hit the turn limit or require re-implementation cycles before reaching human-review-ready.

Example issue

Title: Add a greeting utility function

Body:

Add a `greet(name: string): string` function to `src/utils.ts` that returns
`Hello, {name}!`.

Acceptance criteria:
- Function is exported from `src/utils.ts`
- Returns the greeting string with the provided name
- Unit test in `src/__tests__/utils.test.ts` covers the happy path

What to avoid for a first issue

• Vague descriptions (“improve the API” or “refactor the codebase”)
• Issues requiring environment variables or API keys at runtime
• Issues that depend on unreleased changes from other branches
• Large epics — save those for after you understand the pipeline

Create a test issue

On your test repo, create a GitHub issue:

• Title: Add a hello-world endpoint
• Body: Add a GET /hello endpoint that returns { "message": "Hello, World!" } as JSON.
• Label: colony:enqueue

The colony:enqueue label tells Sprint Master to pick up this issue. Colony’s default intake_mode: tagged setting means only issues explicitly labeled colony:enqueue enter the pipeline — this gives you full control over which issues Colony processes.

To add the label in the GitHub UI: open your issue, click Labels in the right sidebar, search for colony:enqueue, and select it. The label is applied immediately.

Note: The colony:enqueue label is created automatically when you run npx colony init on your repo. If you don’t see it, re-run npx colony init -r owner/repo. To automatically process all new issues without labeling, set intake_mode: all under agents.sprint_master in your config.

Timing expectation: Sprint Master polls every 30 seconds. Your issue may take up to 60 seconds to be picked up. Run npx colony status (or docker exec colony-sprint-master colony status) to verify agents are running. If nothing happens after 2 minutes, check logs with npx colony logs or docker compose logs -f.

Watch the pipeline

Open the dashboard at http://localhost:9106 for real-time pipeline status. The issue progresses through these states (visible as GitHub labels):

colony:enqueue → colony:new → colony:analyzing → colony:ready-for-dev → colony:in-development → colony:in-review → colony:human-review-ready

Stage	What Colony does	What you’ll see
new → analyzing	Sprint Master picks up the issue, enqueues analysis	Label changes to colony:analyzing
analyzing	Analyzer reads the issue, explores codebase, writes implementation plan	A comment appears on the issue with the plan
ready-for-dev	Analysis complete, development queued	Label changes to colony:ready-for-dev
in-development	Developer creates worktree, implements via Claude Code, opens PR	New branch colony/issue-N and a PR appear
in-review	Reviewer runs build/test/lint, then LLM code review	Review comments appear on the PR
human-review-ready	All automated checks passed — your turn	Review and merge the PR on GitHub

Detailed pipeline stage breakdown

colony:enqueue → colony:new

What happens: The Sprint Master picks up the issue on its next poll cycle (default: every 30 seconds). It creates a pipeline_issues row in Postgres and transitions the issue to new.

Where to look	What you’ll see
GitHub	The colony:enqueue label is replaced by colony:new
Dashboard (http://localhost:9106)	The issue appears in the pipeline view with state new
Logs	Sprint Master logs: intake: picked up issue #N

colony:new → colony:analyzing

What happens: The Sprint Master enqueues an analyze task in the work_tasks queue. A worker claims the task and runs the analyzer, which reads the issue body, explores the codebase, and writes an implementation plan.

Where to look	What you’ll see
GitHub	Label changes to colony:analyzing
Dashboard	Issue state updates to analyzing; worker activity shows the claimed task
Logs	Worker logs: claimed task analyze for issue #N

colony:analyzing → colony:ready-for-dev

What happens: The analyzer finishes and posts a comment on the issue with its implementation plan. The issue transitions to ready-for-dev, which enqueues a develop task.

Where to look	What you’ll see
GitHub	Label changes to colony:ready-for-dev. A new comment from Colony appears with the analysis plan
Dashboard	Issue state updates to ready-for-dev
Logs	Analyzer logs: analysis complete for issue #N

colony:ready-for-dev → colony:in-development

What happens: A worker claims the develop task. The developer agent creates a git worktree branched from origin/main, implements the changes using Claude Code, and opens a pull request.

Where to look	What you’ll see
GitHub	Label changes to colony:in-development. A new branch colony/issue-N appears. Eventually, a PR is opened
Dashboard	Issue state updates to in-development; worker activity shows active development
Logs	Developer logs: creating worktree for issue #N, then Claude Code session output

Timing: Development is the longest phase. A simple issue typically takes 2–5 minutes; more complex issues can take 10–30 minutes depending on the Claude model and issue complexity.

colony:in-development → colony:in-review

What happens: The developer opens a PR and transitions the issue to in-review, which enqueues a review task. A worker claims it and the reviewer runs deterministic checks (build, test, lint) followed by an LLM-powered code review.

Where to look	What you’ll see
GitHub	Label changes to colony:in-review. Review comments appear on the PR
Dashboard	Issue state updates to in-review
Logs	Reviewer logs: running checks for PR #N, then review verdict

colony:in-review → colony:human-review-ready

What happens: All automated checks passed and the reviewer’s LLM review is complete. The issue is now waiting for your approval.

Where to look	What you’ll see
GitHub	Label changes to colony:human-review-ready. The PR has Colony’s review comments and is ready for your review
Dashboard	Issue state updates to human-review-ready
Logs	Reviewer logs: review complete for PR #N, verdict: approve

Review cycle: If the reviewer finds issues, the PR goes through a colony:changes-requested → colony:in-development → colony:in-review cycle before reaching human-review-ready. Each cycle incorporates the previous review feedback.

Development timing: A simple issue typically takes 2-5 minutes. Complex issues can take 10-30 minutes. If the reviewer finds issues, the PR goes through a changes-requested → in-development → in-review cycle automatically.

Check progress

# Docker:
docker exec colony-sprint-master colony status
docker compose logs -f worker

# Native:
npx colony status
npx colony logs

Review and merge

Once the issue reaches human-review-ready, review the PR on GitHub. Colony took your issue from description to working code — a branch, tests (if applicable), and a pull request ready for your review.

For advanced topics (reading analyzer plans, slash commands, PR review workflow, and common gotchas), see First Issue Tutorial.

Cost Expectations

Each issue costs Anthropic API credits. Rough ranges based on issue complexity:

Complexity	Typical cost
Simple (add a field, fix a typo)	$1–3
Medium (new endpoint, refactor)	$5–15
Complex (new feature, large refactor)	$15–50

Before starting: run npx colony estimate to preview your projected monthly spend based on expected throughput and your config.

For evaluation: add claude.max_cost_per_issue: 10 to your colony.config.yaml to cap each issue at $10. If an issue hits the cap, it moves to colony:blocked and Colony posts a comment explaining the spend. Raise the cap in config and remove the colony:blocked label to retry. See claude.max_cost_per_issue for details.

After each issue: run npx colony inspect <issue> to review the per-issue cost breakdown and timeline.

---

7. What’s Next

You’ve seen Colony process a single issue. Here’s where to go:

• Process more issues — try different issue types and complexities. See First Issue Tutorial for scoping guidance.
• Enable autonomous merging — set auto_merge_on_approval: true in config (requires dual-app setup)
• Production deployment — Deployment Guide for hardened setup with monitoring, webhooks, and multi-repo support
• Non-TypeScript repos — Colony supports any language. Configure workspace.setup_command and review.checks, and add .colony/conventions.md. See the Rails example.
• Custom executors — SDK Guide for building your own pipeline stages
• Configuration — Configuration Reference for all options

Useful CLI commands

npx colony status              # Pipeline status and agent health
npx colony metrics             # Throughput, cycle times, success rates
npx colony inspect <issue>     # Per-issue cost and timeline
npx colony doctor              # Re-run setup validation
npx colony pause <issue>       # Temporarily pause an issue
npx colony resume <issue>      # Resume a paused issue
npx colony logs [agent]        # Tail agent logs
npx colony safestop            # Gracefully drain and stop all agents

---

Troubleshooting

Wrong GitHub permissions

Symptom: Cannot access your-org/your-repo or Authorization failed

Fix: Ensure your token or GitHub App has Contents, Issues, and Pull requests read-write permissions. For PATs, verify the repo scope is enabled.

Missing environment variables

Symptom: ANTHROPIC_API_KEY environment variable is not set or DATABASE_URL environment variable is not set

Fix: Export the missing variable, or add it to .env for Docker deployments. Run npx colony doctor to check all variables.

Database unreachable

Symptom: Cannot connect to Postgres at host:port

Fix:

• Docker Compose: check docker compose ps — the postgres service should be healthy
• External Postgres: verify the connection string in DATABASE_URL
• Neon: ensure ?sslmode=require in the connection string

Claude Code CLI not found

Symptom: npx colony doctor reports Claude CLI not found or failed

Fix: npm install -g @anthropic-ai/claude-code, then verify with claude --version.

Health check failures

Symptom: docker compose ps shows a service as unhealthy

Fix: Check service logs (docker compose logs <service>). Common causes: config not mounted, port conflicts, database not ready.

Issue stuck in a state

Symptom: Issue label doesn’t change after several minutes, or no worker activity appears.

Fix:

1. Run npx colony status to verify all agents are running.
2. Check if the issue has a colony:blocked label — if so, the is_blocked flag was set by a transient failure. Comment /colony:retry on the issue to clear it and retry.
3. Wait at least two poll cycles (60 seconds) — Sprint Master polls every 30 seconds.
4. Run npx colony doctor to verify connectivity and configuration.
5. Check logs with npx colony logs for specific errors.

Planning timeout / issue too large

Symptom: Issue stuck in colony:in-development for a long time, or Colony posts a comment saying the turn limit was reached.

Fix: Comment /colony:decompose on the issue to send it to the planner, which breaks it into smaller sub-issues. Alternatively, comment /colony:cancel to stop processing, then re-create the issue with a narrower scope. For your first issue, start with a single function, a simple bug fix, or a minor config change.

For comprehensive failure diagnosis, see Failure Modes Guide.

---

Validation Commands

Colony provides four commands for validating different aspects of your setup. Use the right one for the situation:

colony doctor — Pre-start validation. Checks config syntax, GitHub access, API key presence, Claude CLI availability, database connectivity, repo clone, labels, ports, and review check scripts. Run this before starting agents to catch setup problems early.

colony preflight — Post-start validation. Checks that migrations have been applied, required tables exist, intake mode is configured, epic config is valid, and workers are responding. Run this after starting agents to verify end-to-end pipeline readiness.

colony status --check — Runtime diagnostics. Verifies config is readable, GitHub connectivity is live, and colony labels are present on the repo. Run this during normal operation to confirm the pipeline is healthy.

colony validate-config — Debug aid. Validates config syntax and env var presence, checks workspace directories, and dumps the effective config after applying defaults and synthesis. Run this when you’re unsure what config Colony is actually using.