Skip to content

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.


Terminal window
git clone https://github.com/RunColony/colony.git
cd colony
./scripts/setup.sh # installs, builds, and links the `colony` command

CLI note: If you build manually (npm install && npm run build) instead of running ./scripts/setup.sh, colony won’t be on your PATH — substitute node packages/cli/dist/index.js in each command below, or run npm link inside packages/cli.


Not needed if deployment.mode is docker-compose in colony.config.yaml — Postgres is bundled.

For native or apple-container mode:

Terminal window
# 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 pgvector/pgvector:pg17
export DATABASE_URL="postgresql://colony:colony@localhost:5432/colony"

Migrations run automatically at agent startup.


Terminal window
colony init --generate

Set environment variables:

Terminal window
export GITHUB_TOKEN=ghp_...
export ANTHROPIC_API_KEY=sk-ant-... # not required under provider: gateway (see configuration.md#claudegatewayconfig)
export DATABASE_URL=postgresql://colony:colony@localhost:5432/colony # native / apple-container only

For Docker, copy .env.example to .env and set values there before running colony init or colony check (step 4) — host commands read this file.

For the complete field reference, see configuration.md.


Requires a colony.config.yaml from step 3 — run colony init -r only after config exists.

Terminal window
colony init -r your-org/your-repo
colony check # native mode pre-flight check
colony check --docker # docker-compose / apple-container pre-flight check

Run before docker compose up, colony check --docker validates config, credentials and the repository, and skips the in-container checks (config mount, DB connectivity, COLONY_REPO) with one warning. That is expected; re-run it after the containers start.

Run the start command for your deployment.mode (set in colony.config.yaml):

docker-compose:

Terminal window
docker compose build && docker compose up -d # .env was copied in step 3
colony check --docker # re-run: now includes in-container checks

apple-container:

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

native:

Terminal window
colony start

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


Dashboard: http://localhost:9106

Health endpoints:

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

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, except for slash commands, which are only delivered through the webhook receiver.

Use a tunnel to expose your local webhook receiver:

Cloudflare Tunnel (recommended):

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

ngrok (alternative):

Terminal window
ngrok http 9800

In your repository: Settings > Webhooks > Add webhook:

FieldValue
Payload URLYour tunnel or production URL + /webhook
Content typeapplication/json
SecretGenerate with openssl rand -hex 32
EventsSelect individual: Issues, Issue comments, Pull requests, Pull request reviews, Pull request review comments, Check runs, Check suites, Statuses, Workflow runs
webhook:
enabled: true
secret_env: WEBHOOK_SECRET
port: 9800

Set the secret:

Terminal window
# Docker — add to .env:
# WEBHOOK_SECRET=<secret>
# Native:
export WEBHOOK_SECRET=<secret>

Restart Colony to pick up the new config. Issue comments must be enabled for slash commands to work at all (plus Pull request reviews and Pull request review comments for commands posted on PRs). In docker-compose mode the webhook-receiver is behind an opt-in profile, so start it with docker compose --profile webhook up -d.


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.