Skip to content

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.


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.

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

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:

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

3. 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:

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


Terminal window
node --version # should print v22.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:

Terminal window
# Install mise
curl https://mise.run | sh
# Restart your shell or source the rc mise updated (~/.bashrc, ~/.zshrc, etc.)
exec $SHELL
# Install Node 22 globally
mise use -g node@22
# Verify
node --version # should print v22.x or higher

nvm 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:

Terminal window
# macOS (Homebrew)
brew install node@22
# 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.


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=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. On services where vector is admin-only or untrusted (for example Azure Database for PostgreSQL Flexible Server, where only azure_pg_admin members may create it), an admin must run CREATE EXTENSION IF NOT EXISTS vector; (after allow-listing it in the provider console where required) before the first colony migrate apply. After that, migrations, including 099, run as the non-admin application role.

Option B: Local Docker Postgres

Terminal window
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:

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

Colony needs authenticated access to your repositories.

Personal Access Token (PAT) — quickest for evaluation

Section titled “Personal Access Token (PAT) — quickest for evaluation”
  1. Go to github.com/settings/tokens.
  2. Create a fine-grained or classic token.
  3. Required permissions:
Token typeRequired scope / permissions
Classic PATrepo scope
Fine-grained PATSee the permission table below

Fine-grained PAT permissions (select the target repo under Repository access):

Permission (fine-grained)AccessWhat breaks without it
ContentsRead & writeCannot clone, push branches, or open PRs
IssuesRead & writeCannot read issues, post comments, or manage labels
Pull requestsRead & writeCannot create, review, or merge PRs
MetadataReadGranted automatically by GitHub
AdministrationRead & writeOptional. Only needed for the branch-protection ruleset colony init creates; without it init skips branch protection
ChecksReadCI-gated auto-merge cannot read check runs
Commit statusesReadCI-gated auto-merge cannot read commit statuses
ActionsReadCI-gated auto-merge cannot read workflow runs
Dependabot alertsReadOptional. 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 colony check run always fails under a PAT. It is caught and logged as Could 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.

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.


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

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

Verify:

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

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

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

Terminal window
git --version

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


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.

Terminal window
# macOS
brew install --cask docker
# Linux — see https://docs.docker.com/engine/install/

Recommended resources:

ResourceMinimum
Memory8 GB
CPUs4
Disk50 GB

Requires macOS 15+ and Apple Silicon.

Terminal window
brew install container
container system start
container system property set build.rosetta false
DeploymentWorkersMemoryCPUsDisk
Single repo (eval)18 GB450 GB
Single repo (prod)2-316 GB8100 GB
Multi-repo3+32 GB16200 GB

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.

Terminal window
colony check

Return to Getting Started to configure and run Colony.