Installation Guide

This is a prerequisites reference document with platform-specific install commands and resource sizing. For the end-to-end setup walkthrough, start at Getting Started.

Everything you need installed before running Colony: Node.js, Postgres, GitHub auth, Claude Code CLI, and an optional container runtime.

Windows

Colony’s setup script and CLI require a POSIX shell environment. On Windows, run everything inside WSL2 (Windows Subsystem for Linux). Native Windows shells (Git Bash, MSYS2, Cygwin) are not supported.

1. Install WSL2

# Run in Windows PowerShell or Command Prompt (as Administrator)
wsl --install -d Ubuntu

Restart your machine when prompted, then open the Ubuntu terminal from the Start menu.

2. Install Node inside WSL

Use mise to install Node inside WSL — do not use the Windows-native Node or any Node installed outside WSL, because it cannot access Linux paths:

# Inside your WSL terminal
curl https://mise.run | sh
exec $SHELL
mise use -g node@20
node --version  # should print v20.x or higher

3. Keep your repos inside the WSL filesystem

Clone Colony and your target repositories inside the WSL filesystem (~/ or /home/...) — not under /mnt/c/ or other Windows-mounted paths:

# Good — inside WSL filesystem
cd ~
git clone https://github.com/RunColony/colony.git
cd colony
./scripts/setup.sh

# Avoid — Windows-mounted NTFS path (slow git I/O, breaks worktree operations)
# cd /mnt/c/Users/yourname/projects/colony

Git worktree operations on NTFS-mounted paths (/mnt/c/...) are 10–50× slower and can cause spurious failures in the developer agent. Always use the native WSL filesystem.

1. Node.js 20+

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

If not installed, the recommended approach is mise (Linux/macOS) — it installs Node into your home directory so npm install -g and npm link work without sudo, avoiding the EACCES errors common with system-managed Node:

# 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: nvm install 20 && nvm use 20. ./scripts/setup.sh detects mise/nvm/asdf/volta and skips the npm-prefix workaround when present.

Alternatively, use a system-installed Node:

# macOS (Homebrew)
brew install node@20

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

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

Warning (Linux apt/yum Node): System-installed Node sets the npm global prefix to a root-owned directory. Don’t fix EACCES errors with sudo npm install -g — that leaves root-owned files that break later non-sudo installs. Use mise instead, or configure a user prefix: mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH. ./scripts/setup.sh detects this case and configures the prefix automatically.

2. PostgreSQL

Colony stores pipeline state in Postgres. If deployment.mode is docker-compose in your colony.config.yaml, Postgres is bundled — skip this section.

Option A: Neon free tier (quickest)

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

pgvector required: Colony uses the vector extension for semantic embeddings. Neon enables pgvector by default — no extra step needed. For other managed providers (RDS, Cloud SQL, Supabase, etc.) you may need to run CREATE EXTENSION IF NOT EXISTS vector; once on your database, or enable pgvector via the provider’s console before running migrations.

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 \
  pgvector/pgvector:pg17

Verify:

psql postgresql://colony:colony@localhost:5432/colony -c "SELECT 1;"

3. GitHub Authentication

Colony needs authenticated access to your repositories.

Personal Access Token (PAT) — quickest for evaluation

Go to github.com/settings/tokens.
Create a fine-grained or classic token.
Required permissions:

Token type	Required scope / permissions
Classic PAT	`repo` scope
Fine-grained PAT	`contents` (read & write), `issues` (read & write), `pull_requests` (read & write)

Trade-off: PATs are tied to your personal account. All Colony activity appears as you. Rate limits are lower than GitHub Apps.

GitHub App — recommended for ongoing use

Provides fine-grained permissions, higher rate limits, and bot-attributed activity. See the GitHub App Setup Guide for step-by-step instructions.

For autonomous merging (no human approval), see the dual-app section.

4. Anthropic API Key

Colony’s agents use Claude for LLM-powered work.

Sign up at console.anthropic.com.
Create an API key.

Verify:

echo $ANTHROPIC_API_KEY | head -c 10   # should print sk-ant-api

5. Claude Code CLI

Colony’s developer and analyzer agents shell out to claude for implementation.

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

6. Git

git --version

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

7. Container Runtime (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. This section is only needed if deployment.mode is docker-compose or apple-container in your colony.config.yaml.

Docker Desktop

# macOS
brew install --cask docker

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

Recommended resources:

Resource	Minimum
Memory	8 GB
CPUs	4
Disk	50 GB

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

8. Environment Variables

The three variables every Colony deployment needs are GITHUB_TOKEN (or GitHub App credentials configured in colony.config.yaml), ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN for Pro/Max subscribers), and DATABASE_URL for native and apple-container modes — docker-compose mode provides DATABASE_URL automatically via the bundled Postgres container. When routing through an AI gateway (provider: gateway), ANTHROPIC_API_KEY is replaced by the gateway auth token — see ClaudeGatewayConfig.

For the full variable reference — including optional variables for webhooks, the dashboard, the MCP server, and multi-container deployments — see Environment Variables.

Validate everything

npx colony check

Next Steps

Return to Getting Started to configure and run Colony.