Setup Checklist
Setup Checklist
Section titled “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
Section titled “1. Clone and Build”git clone https://github.com/RunColony/colony.gitcd colony./scripts/setup.sh # installs, builds, and links the `colony` commandCLI note: If you build manually (
npm install && npm run build) instead of running./scripts/setup.sh,colonywon’t be on your PATH — substitutenode packages/cli/dist/index.jsin each command below, or runnpm linkinsidepackages/cli.
2. Database
Section titled “2. Database”Not needed if deployment.mode is docker-compose in colony.config.yaml — Postgres is bundled.
For native or apple-container mode:
# Option A: Neon (free tier)export DATABASE_URL="postgresql://user:pass@ep-xxx.aws.neon.tech/colony?sslmode=require"
# Option B: Local Dockerdocker run -d --name colony-pg -e POSTGRES_USER=colony -e POSTGRES_PASSWORD=colony -e POSTGRES_DB=colony -p 5432:5432 pgvector/pgvector:pg17export DATABASE_URL="postgresql://colony:colony@localhost:5432/colony"Migrations run automatically at agent startup.
3. Configure
Section titled “3. Configure”colony init --generateSet environment variables:
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 onlyFor 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.
4. Initialize and Start
Section titled “4. Initialize and Start”Requires a colony.config.yaml from step 3 — run colony init -r only after config exists.
colony init -r your-org/your-repocolony check # native mode pre-flight checkcolony check --docker # docker-compose / apple-container pre-flight checkRun 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:
docker compose build && docker compose up -d # .env was copied in step 3colony check --docker # re-run: now includes in-container checksapple-container:
./scripts/colony-container.sh build && ./scripts/colony-container.sh up -dnative:
colony startVerify: docker compose ps, ./scripts/colony-container.sh health, or colony status.
5. Verifying Health
Section titled “5. Verifying Health”Dashboard: http://localhost:9106
Health endpoints:
curl -sf http://localhost:9100/health # sprint-mastercurl -sf http://localhost:9200/health # workercurl -sf http://localhost:9106/health # monitor + dashboard6. Webhook Setup (Optional)
Section titled “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, except for slash commands, which are only delivered through the webhook receiver.
Local development
Section titled “Local development”Use a tunnel to expose your local webhook receiver:
Cloudflare Tunnel (recommended):
brew install cloudflaredcloudflared tunnel --url http://localhost:9800ngrok (alternative):
ngrok http 9800GitHub configuration
Section titled “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, Issue comments, Pull requests, Pull request reviews, Pull request review comments, Check runs, Check suites, Statuses, Workflow runs |
Config additions
Section titled “Config additions”webhook: enabled: true secret_env: WEBHOOK_SECRET port: 9800Set the secret:
# 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.
Next Steps
Section titled “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.