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 — Progressive-disclosure guide: Essential fields (Tier 1), recommended tuning (Tier 2), and advanced options (Tier 3)
• 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: The bootstrap script (./scripts/setup.sh) links colony as a global command so every example below works as written. If you bootstrap manually instead, colony won’t be on your PATH — substitute node packages/cli/dist/index.js in each command, or run npm link inside packages/cli yourself.

---

Quickstart (~5 min)

The fastest path. The bootstrap script installs deps, builds, links the colony CLI globally, and installs the Claude Code CLI in one go. Then the interactive wizard takes over.

Prerequisite: Node 20+. On Linux, install via mise (curl https://mise.run | sh && exec $SHELL && mise use -g node@20) or nvm to avoid EACCES on global installs. macOS Homebrew Node works too. See Prerequisites for details.

git clone https://github.com/RunColony/colony.git
cd colony
./scripts/setup.sh

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

./scripts/setup.sh is idempotent and handles every install gotcha — including configuring a user-owned npm prefix on Linux when system Node has a root-owned global, and installing @anthropic-ai/claude-code (required by Colony workers). If the script updates your shell rc (~/.bashrc / ~/.zshrc), it will print a source command to refresh PATH before running colony quickstart.

Skipping the bootstrap script means handling these yourself: npm install && npm run build && (cd packages/cli && npm link) && npm install -g @anthropic-ai/claude-code. On Linux with system Node, expect EACCES errors unless you’ve configured ~/.npm-global first (or installed Node via mise/nvm).

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; choose deployment mode (Docker Compose, Apple Container, or Native)

── Step 2: Repository
   Configure your target repository

── Step 3: Database
   Set up the Colony database

── Step 4: Cost Preview
   Select Claude models with cost tradeoff explanations; set per-issue and daily 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

If the wizard is interrupted (Ctrl-C, terminal closed), re-running colony quickstart will detect the previous session and ask whether to resume. Partial progress within an interrupted phase is preserved — e.g., if you Ctrl-C while answering the Anthropic key prompt, the wizard remembers your earlier choices (deployment mode, GitHub auth method, GitHub App ID/Installation ID, Node/git/Claude CLI checks) and only re-asks the questions that hadn’t been answered yet.

Credentials are not persisted to disk for security. On resume, you will be re-prompted for any token that isn’t already in your environment:

• GITHUB_TOKEN — re-export before running, or re-paste at the prompt
• ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN — same. If you paste an sk-ant-oat... token, the wizard routes it to CLAUDE_CODE_OAUTH_TOKEN and writes auth_mode: oauth-token in your config
• GitHub App private key path is remembered, but the key itself is read fresh each run from the path you provided

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. Recommended: install via mise (Linux/macOS) so global installs work without sudo.

• Git — git --version

• Anthropic credentials — one of:

  • API key (sk-ant-api...) from console.anthropic.com — pay-as-you-go billing
  • OAuth token (sk-ant-oat...) from claude setup-token — uses your Claude Pro/Max subscription

  The quickstart wizard auto-detects which form you paste and configures Colony accordingly.

• GitHub account with a test repository (public or private)

Claude Code CLI: No manual step required. ./scripts/setup.sh installs @anthropic-ai/claude-code for you as part of the bootstrap.

Recommended: install Node via mise (Linux/macOS)

mise installs Node into your home directory, which makes npm install -g and npm link work without sudo and without the EACCES errors you’ll hit with apt/yum-installed Node on Linux.

# Install mise
curl https://mise.run | sh

# Restart your shell or source the rc mise updated (~/.bashrc, ~/.zshrc, etc.)
exec $SHELL

# Install Node 20 globally
mise use -g node@20

# Verify
node --version   # should print v20.x or higher

nvm works equivalently if you prefer (nvm install 20 && nvm use 20). ./scripts/setup.sh detects mise / nvm / asdf / volta and skips the npm-prefix workaround when present.

Alternative: system Node (with caveats)

If you must use a system-installed Node (apt, brew, etc.), ./scripts/setup.sh will detect that the global npm prefix is not writable and automatically reconfigure npm to use ~/.npm-global so subsequent global installs don’t EACCES.

# macOS (Homebrew)
brew install node@20

# Ubuntu/Debian — but mise is strongly preferred
sudo apt install nodejs npm

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

Warning: If you have previously run sudo npm install -g <anything>, you may have root-owned files inside ~/.npm-global or /usr/local/lib/node_modules that will EACCES on subsequent global installs. ./scripts/setup.sh detects this and prints fix instructions.

Other prerequisites

Git

git --version

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

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)	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
./scripts/setup.sh

./scripts/setup.sh installs dependencies, builds all packages, configures a user-owned npm prefix if needed (Linux apt-installed Node ships with a root-owned global prefix that EACCESes on npm link), and links the colony CLI globally.

If your shell rc was updated, the script will print a source command to refresh PATH in the current shell.

If you want to run the steps yourself: npm install && npm run build && (cd packages/cli && npm link). On Linux you will likely hit EACCES on the final step — either re-run with the bootstrap script or first configure a user prefix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.

Set up GitHub authentication

Colony needs access to your GitHub repository. Pick one auth method — PAT and GitHub App are mutually exclusive in the config.

Personal Access Token (PAT) — quickest for evaluation

1. Go to github.com/settings/tokens.
2. Choose Generate new token (classic) or Generate new token → Fine-grained. Either type works; the table below shows what to grant for each.
3. Configure scopes / permissions:

Token type	Required permissions
Classic PAT	Enable the repo scope (covers everything Colony needs)
Fine-grained PAT	Repository access: select the target repo. Permissions: Contents (Read & write), Issues (Read & write), Pull requests (Read & write)

4. Set an expiration that matches your evaluation window.
5. Copy the token immediately — GitHub only shows it once.
6. Export it as GITHUB_TOKEN (or let colony quickstart prompt for it):

export GITHUB_TOKEN=ghp_your_token_here

PATs are tied to your personal account, so all Colony activity appears as you, and rate limits are lower than a GitHub App. Fine for evaluation; switch to App auth before going to production.

GitHub App — recommended for production

Provides fine-grained permissions, higher rate limits, and bot-attributed activity. See the GitHub App Setup Guide for step-by-step instructions (creating the App, generating a private key, finding the Installation ID). For fully autonomous merging, see dual-app setup.

When colony quickstart asks “GitHub authentication method”, choose GitHub App and have these ready: App ID, Installation ID, and the path to the .pem private key.

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:

colony init --generate

This prompts for your repo, auth method, database URL, optional local clone path (for stack auto-detection — workers clone fresh inside containers at runtime), review checks, and Claude model preference. It writes colony.config.yaml.

Docker Compose mode: the target repository lives entirely inside containers. Workers clone it fresh at startup, and singleton agents (sprint-master, monitor, webhook-receiver) operate via the GitHub API + Postgres without needing on-disk repo access. The wizard offers an optional “Local clone path” prompt only so it can auto-detect your project’s tech stack and review commands — leave it empty if you’d rather skip detection and edit colony.config.yaml manually.

Native mode (no containers) still requires a local clone — Colony processes run on the host and operate directly on that clone.

For the essential fields you must set, see Tier 1: Essential Configuration. For all fields, see the full Configuration Reference.

Set environment variables

export GITHUB_TOKEN=ghp_your_token_here

# Pick ONE of these — quickstart auto-detects which form was pasted:
export ANTHROPIC_API_KEY=sk-ant-api_your_key_here          # API key (console.anthropic.com)
# OR
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat_your_token_here  # OAuth token (`claude setup-token`)

# 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.

OAuth tokens (sk-ant-oat...) use your Claude Pro/Max subscription instead of pay-as-you-go API credits. Generate one with claude setup-token. When you use one, your colony.config.yaml will include claude.auth_mode: oauth-token and claude.oauth_token_env: CLAUDE_CODE_OAUTH_TOKEN.

Next: Initialize your repo.

---

5. Initialize and Start (~5 min)

Initialize your repository

This creates Colony’s pipeline labels and branch protection on GitHub. Requires a colony.config.yaml already created in step 4 — running this before generating config produces a descriptive error with remediation options.

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

colony check

Fix any failures before starting — misconfigured review checks are the most common cause of wasted API credits on first run. Common issues:

Error	Fix
Cannot access your-org/your-repo	Check token has repo scope and repo name is correct
Claude CLI not found	Re-run ./scripts/setup.sh (it installs 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:

colony start

# Verify:
colony status

The quickstart wizard writes your credentials to .env in the Colony directory. This file is loaded automatically by colony start. Add .env to your .gitignore to avoid committing secrets.

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.

Docker Compose: webhook-receiver is not started by default. To enable it, run docker compose --profile webhook up -d and set webhook.enabled: true in your config. See Webhook Setup for full setup instructions.

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 colony init on your repo. If you don’t see it, re-run 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 colony status (or docker exec colony-sprint-master colony status) to verify agents are running. If nothing happens after 2 minutes, check logs with 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:
colony status
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 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 comment /colony:retry on the issue to retry. See claude.max_cost_per_issue for details.

After each issue: run 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:

• Greenfield repos — use colony bootstrap <stack> <name> to scaffold a new Colony-managed repo with conventions, .gitignore patches, and GitHub labels pre-configured. See Bootstrap Guide.
• Process more issues — try different issue types and complexities. See First Issue Tutorial for scoping guidance.
• Connect an editor via MCP — run colony mcp to expose Colony pipeline tools in Claude Code, Cursor, or any MCP-compatible editor. See MCP Server (Editor Integration) below.
• Seed the pipeline from a plan — use colony plan import <path> or the colony_import_plan MCP tool to bulk-file issues from a superpowers plan. See Plan Import Guide.
• Enable autonomous merging — set auto_merge_on_approval: true in config (requires dual-app setup)
• Enable webhooks (Docker Compose) — run docker compose --profile webhook up -d and set webhook.enabled: true in your config for near-instant event response instead of polling. See Webhook 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 — start at Tier 1 for first-time setup

Useful CLI commands

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

MCP Server (Editor Integration)

The Colony MCP server exposes pipeline tools directly inside MCP-compatible editors — query issue status, file new issues, trigger retries, and manage the pipeline without leaving your editor.

Start the server:

colony mcp

This reads DATABASE_URL and GITHUB_TOKEN from your environment (or Colony config) and launches the MCP stdio server. Configure your editor to run this command as the MCP server process.

Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "colony": {
      "command": "colony",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "colony": {
      "command": "colony",
      "args": ["mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Available tools: colony_status, colony_issues, colony_file_issue, colony_estimate, colony_review, colony_pause, colony_cancel, colony_retry, colony_tracks, colony_import_plan, colony_why. See packages/mcp/README.md for the full tool reference and example conversations.

---

Troubleshooting

Quick fix: Run colony check --fix to automatically remediate the most common setup issues — missing tool config exclusions, placeholder repo_dir, and missing environment variables. It prompts before any destructive change.

Wrong GitHub permissions

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

Fix: See GitHub Authentication in the installation guide for the exact required scopes and permissions.

Anthropic API key rejected with invalid x-api-key (HTTP 401)

Symptom: Anthropic API key rejected (HTTP 401): {"error":{"type":"authentication_error","message":"invalid x-api-key"}}

Cause: You pasted a Claude OAuth token (sk-ant-oat..., issued by claude setup-token) into a slot expecting a regular API key (sk-ant-api...). The two use different HTTP auth schemes — OAuth tokens require Authorization: Bearer, not x-api-key.

Fix: Re-run colony quickstart (or re-export your token). The wizard now auto-detects the sk-ant-oat prefix and routes the value to CLAUDE_CODE_OAUTH_TOKEN with auth_mode: oauth-token. If your colony.config.yaml was already written incorrectly, edit it to:

claude:
  auth_mode: oauth-token
  oauth_token_env: CLAUDE_CODE_OAUTH_TOKEN

and export CLAUDE_CODE_OAUTH_TOKEN (not ANTHROPIC_API_KEY).

If you started from colony.config.example.yaml, the commented auth block at the top of its claude: section already contains these exact fields — uncomment them instead of editing from scratch.

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 colony check to check all variables.

If agents fail after a terminal restart with GITHUB_TOKEN is not set, check if .env exists in your Colony directory. If it does, colony start loads it automatically — the error may indicate the file was deleted or moved. Re-run colony quickstart to regenerate it, or manually create .env with your credentials.

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: colony check reports Claude CLI not found or failed

Fix: Re-run ./scripts/setup.sh from the colony repo root — it installs @anthropic-ai/claude-code and verifies claude --version. If you’d rather install it yourself, npm install -g @anthropic-ai/claude-code works but may EACCES on Linux with system Node; see the Prerequisites section for the mise/nvm path.

npm EACCES errors during setup

Symptom: ./scripts/setup.sh or npm install -g ... fails with EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...' or similar.

Cause: System-installed Node (apt, yum) sets the npm global prefix to a root-owned directory. Don’t fix this with sudo — that leaves root-owned files in your home dir that EACCES on later non-sudo installs.

Fix (recommended): Install Node via mise so the prefix lives under your home directory:

curl https://mise.run | sh
exec $SHELL
mise use -g node@20
rm -rf node_modules                       # drop anything installed against the old Node
./scripts/setup.sh

Fix (if you’ve already used sudo npm install -g): root-owned files may remain in ~/.npm-global or /usr/local/lib/node_modules. Reclaim ownership and re-run:

sudo chown -R "$(id -u):$(id -g)" ~/.npm-global
./scripts/setup.sh

npm error config prefix cannot be changed from project config

Symptom: Every npm command in the colony repo prints npm error config prefix cannot be changed from project config: /path/to/colony/.npmrc. Commands may still complete, but the error is noisy and breaks scripts that parse npm output.

Cause: A stray prefix=... line landed in a project-level .npmrc at the colony repo root. npm refuses prefix overrides from project config (only user/global are allowed). Some npm versions silently route npm config set prefix to project location when invoked inside a workspace, even though --location=user is supposed to be the default.

Fix:

# Inspect the offending file
cat /path/to/colony/.npmrc

# If it only contains the prefix line, remove the file entirely
rm /path/to/colony/.npmrc

# If it contains other settings you want to keep, strip just the prefix line
sed -i '/^prefix\s*=/d' /path/to/colony/.npmrc

Then re-run ./scripts/setup.sh. The current script detects this case at the start of step 4 and cleans it up automatically; this manual fix is only needed if you set the prefix outside the bootstrap script.

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 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 colony check to verify connectivity and configuration.
5. Check logs with 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.

Quickstart wizard failure mid-setup

Symptom: The wizard fails partway through (e.g., config write fails, agent won’t start) and you’re unsure what state Colony left behind.

Fix: When a wizard step fails, the runner prompts “Would you like to roll back changes made so far?” — answer yes to undo any config files written, containers started, or labels created during the session. After rollback, fix the root cause (check logs, verify env vars) and re-run colony quickstart. The wizard will prompt to resume from the last successful phase.

For comprehensive failure diagnosis, see Failure Modes Guide.

---

Validation Commands

Run colony check at any time to validate your setup. It runs six progressive stages — config, credentials, database, repository, labels, and runtime — and skips the runtime stage with a clear message when agents aren’t running.

colony check                    # Full validation (all stages)
colony check --stage config     # Single stage (config, credentials, database, repository, labels, runtime)
colony check --fix              # Auto-remediate common failures (prompts before any destructive change)

The legacy commands colony doctor, colony preflight, and colony validate-config are aliases for specific stages of colony check and will continue to work, but colony check is the recommended entry point.