Setup Checklist

This page is a commands-only reference checklist for returning users. First-time users: start at Getting Started — it covers everything on one page.

1. Clone and Build

git clone https://github.com/RunColony/colony.git
cd colony
npm install && npm run build

2. Database

Skip if using Docker Compose (Postgres is bundled).

# Option A: Neon (free tier)
export DATABASE_URL="postgresql://user:pass@ep-xxx.aws.neon.tech/colony?sslmode=require"

# Option B: Local Docker
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 at agent startup.

3. Configure

npx colony init --generate

Set environment variables:

export GITHUB_TOKEN=ghp_...
export ANTHROPIC_API_KEY=sk-ant-...
export DATABASE_URL=postgresql://colony:colony@localhost:5432/colony  # skip for Docker Compose

For Docker, copy .env.example to .env and set values there.

For the complete field reference, see configuration.md.

4. Initialize and Start

npx colony init -r your-org/your-repo
npx colony doctor                        # pre-flight check

Docker Compose:

cp .env.example .env && docker compose build && docker compose up -d

Apple Container:

./scripts/colony-container.sh build && ./scripts/colony-container.sh up -d

Native:

npx colony start

Verify: docker compose ps, ./scripts/colony-container.sh health, or npx colony status.

5. Verifying Health

Dashboard: http://localhost:9106

Health endpoints:

curl -sf http://localhost:9100/health   # sprint-master
curl -sf http://localhost:9200/health   # worker
curl -sf http://localhost:9106/health   # monitor + dashboard

6. Webhook Setup (Optional)

Webhooks provide near-instant response to GitHub events. Without them, Colony polls every 30 seconds. Polling is the default and works well — webhooks are additive.

Local development

Use a tunnel to expose your local webhook receiver:

Cloudflare Tunnel (recommended):

brew install cloudflared
cloudflared tunnel --url http://localhost:9800

ngrok (alternative):

ngrok http 9800

GitHub configuration

In your repository: Settings > Webhooks > Add webhook:

Field	Value
Payload URL	Your tunnel or production URL + `/webhook`
Content type	`application/json`
Secret	Generate with `openssl rand -hex 32`
Events	Select individual: Issues, Pull requests, Pull request reviews

Config additions

webhook:
  enabled: true
  secret_env: WEBHOOK_SECRET
  port: 9800

For Docker/Apple Container, add dispatch_host:

webhook:
  enabled: true
  secret_env: WEBHOOK_SECRET
  port: 9800
  dispatch_host: host.docker.internal

Set the secret:

# Docker — add to .env:
# WEBHOOK_SECRET=<secret>

# Native:
export WEBHOOK_SECRET=<secret>

Restart Colony to pick up the new config.

Next Steps

Label a GitHub issue with colony:enqueue and watch Colony process it. See getting-started.md for the full walkthrough, or the First Issue Tutorial for detailed guidance on scoping and reviewing.

For production hardening, see the Deployment Guide.