Installation Guide
Installation Guide
Section titled “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
Section titled “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
Section titled “1. Install WSL2”# Run in Windows PowerShell or Command Prompt (as Administrator)wsl --install -d UbuntuRestart your machine when prompted, then open the Ubuntu terminal from the Start menu.
2. Install Node inside WSL
Section titled “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 terminalcurl https://mise.run | shexec $SHELLmise use -g node@22node --version # should print v22.x or higher3. Keep your repos inside the WSL filesystem
Section titled “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 filesystemcd ~git clone https://github.com/RunColony/colony.gitcd colony./scripts/setup.sh
# Avoid — Windows-mounted NTFS path (slow git I/O, breaks worktree operations)# cd /mnt/c/Users/yourname/projects/colonyGit 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 22+
Section titled “1. Node.js 22+”node --version # should print v22.x or higherIf 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 misecurl https://mise.run | sh
# Restart your shell or source the rc mise updated (~/.bashrc, ~/.zshrc, etc.)exec $SHELL
# Install Node 22 globallymise use -g node@22
# Verifynode --version # should print v22.x or highernvm works equivalently: nvm install 22 && nvm use 22. ./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@22
# Ubuntu/Debian — mise is strongly preferredsudo apt install nodejs npm
# Other platforms — see https://nodejs.orgWarning (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-globaland add~/.npm-global/binto your PATH../scripts/setup.shdetects this case and configures the prefix automatically.
2. PostgreSQL
Section titled “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)
Sign up at neon.tech. Copy the connection string from the dashboard:
postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/colony?sslmode=requirepgvector required: Colony uses the
vectorextension 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 runCREATE EXTENSION IF NOT EXISTS vector;once on your database, or enable pgvector via the provider’s console before running migrations. On services wherevectoris admin-only or untrusted (for example Azure Database for PostgreSQL Flexible Server, where onlyazure_pg_adminmembers may create it), an admin must runCREATE EXTENSION IF NOT EXISTS vector;(after allow-listing it in the provider console where required) before the firstcolony migrate apply. After that, migrations, including 099, run as the non-admin application role.
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:pg17Verify:
psql postgresql://colony:colony@localhost:5432/colony -c "SELECT 1;"3. GitHub Authentication
Section titled “3. GitHub Authentication”Colony needs authenticated access to your repositories.
Personal Access Token (PAT) — quickest for evaluation
Section titled “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 | See the permission table below |
Fine-grained PAT permissions (select the target repo under Repository access):
| Permission (fine-grained) | Access | What breaks without it |
|---|---|---|
| Contents | Read & write | Cannot clone, push branches, or open PRs |
| Issues | Read & write | Cannot read issues, post comments, or manage labels |
| Pull requests | Read & write | Cannot create, review, or merge PRs |
| Metadata | Read | Granted automatically by GitHub |
| Administration | Read & write | Optional. Only needed for the branch-protection ruleset colony init creates; without it init skips branch protection |
| Checks | Read | CI-gated auto-merge cannot read check runs |
| Commit statuses | Read | CI-gated auto-merge cannot read commit statuses |
| Actions | Read | CI-gated auto-merge cannot read workflow runs |
| Dependabot alerts | Read | Optional. colony check warns, and security-PR prioritisation is unavailable |
For a classic PAT, the repo scope covers all of the above; the Administration permission corresponds to the repo admin role.
Limitations of PAT auth:
- GitHub only allows GitHub Apps to create check runs, so the reviewer’s
colonycheck run always fails under a PAT. It is caught and logged asCould not post check run; this is expected. - A PR author cannot APPROVE or REQUEST_CHANGES on their own PR, so formal PR reviews fail when the same PAT both opens and reviews PRs.
For full functionality, use a GitHub App — see github-app-setup.md.
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
Section titled “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
Section titled “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-api5. Claude Code CLI
Section titled “5. Claude Code CLI”Colony’s developer and analyzer agents shell out to claude for implementation.
npm install -g @anthropic-ai/claude-codeclaude --version6. Git
Section titled “6. Git”git --versionIf not installed: xcode-select --install (macOS) or your platform’s package manager.
7. Container Runtime (Optional)
Section titled “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
Section titled “Docker Desktop”# macOSbrew 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)
Section titled “Apple Container (macOS only)”Requires macOS 15+ and Apple Silicon.
brew install containercontainer system startcontainer system property set build.rosetta falseResource Recommendations
Section titled “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
Section titled “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
Section titled “Validate everything”colony checkNext Steps
Section titled “Next Steps”Return to Getting Started to configure and run Colony.