Installation Guide

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.

---

1. Node.js 20+

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

If not installed:

# macOS (Homebrew)
brew install node@20

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

---

2. PostgreSQL

Colony stores pipeline state in Postgres. If using Docker Compose to run Colony, 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

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

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

1. Go to github.com/settings/tokens.
2. Create a fine-grained or classic token.
3. Required scopes:
   • Classic: repo scope
   • Fine-grained: Contents, Issues, 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.

1. Sign up at console.anthropic.com.
2. 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.

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

Variable	Required By	Description
DATABASE_URL	sprint-master, workers	Postgres connection string
ANTHROPIC_API_KEY	workers	Anthropic API key for Claude
GITHUB_TOKEN	sprint-master, workers	GitHub PAT (not needed with GitHub App auth)
WEBHOOK_SECRET	webhook-receiver	HMAC secret for webhook verification (optional)

Set in your shell or in .env for Docker deployments.

Validate everything

npx colony doctor

---

Next Steps

Return to Getting Started to configure and run Colony.