Environment Variables Reference
Environment Variables Reference
Section titled “Environment Variables Reference”This is the single source of truth for every environment variable Colony reads. Variables are grouped by whether they are required for Colony to start or gated behind an optional feature.
Deployment modes:
docker-composebundles Postgres and wiresDATABASE_URLautomatically;nativeandapple-containerrequire an external Postgres instance. Where a variable’s requirement differs by mode that is noted in the Deployment mode(s) column.
Always Required
Section titled “Always Required”These variables must be set before Colony agents will start.
| Variable | Required by | Deployment mode(s) | Purpose | Example / how to generate |
|---|---|---|---|---|
GITHUB_TOKEN | sprint-master, workers | All modes (not needed with GitHub App auth) | GitHub personal access token for API access. Omit if using GitHub App authentication — the App private key is specified in config instead. | ghp_… — generate at github.com/settings/tokens with repo scope (classic) or Contents / Issues / Pull Requests read-write (fine-grained) |
ANTHROPIC_API_KEY | workers | All modes | Anthropic API key used by the Claude Code CLI (developer, analyzer, reviewer agents). Mutually exclusive with CLAUDE_CODE_OAUTH_TOKEN — set exactly one. | sk-ant-api… — generate at console.anthropic.com |
DATABASE_URL | sprint-master, workers | native and apple-container only | Postgres connection string for the pipeline state store. In docker-compose mode, the bundled Postgres container sets this automatically — leave it unset in .env. | postgresql://user:pass@host:5432/colony or postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/colony?sslmode=require |
Optional / Feature-Gated
Section titled “Optional / Feature-Gated”These variables are not required for a basic Colony deployment but enable specific features or override defaults.
| Variable | Required by | Deployment mode(s) | Purpose | Example / how to generate |
|---|---|---|---|---|
CLAUDE_CODE_OAUTH_TOKEN | workers | All modes | Alternative to ANTHROPIC_API_KEY for users with a Claude Pro or Max subscription. Uses OAuth token billing instead of pay-as-you-go API credits. Requires claude.auth_mode: oauth-token in colony.config.yaml. | sk-ant-oat… — run claude setup-token |
ANTHROPIC_BASE_URL | sprint-master, workers | All modes | Overrides the Anthropic API endpoint used by the Claude Code CLI. Set to your gateway or proxy base URL (e.g. a TrueFoundry or LiteLLM endpoint). Claude Code appends /v1/messages for requests. When unset, traffic goes to api.anthropic.com. | https://your-gateway.example.com/anthropic |
ANTHROPIC_AUTH_TOKEN | sprint-master, workers | All modes | Bearer token forwarded by the Claude Code CLI to the gateway endpoint named by ANTHROPIC_BASE_URL. Use when the gateway accepts a fixed bearer token. For gateways that require a custom-named variable (e.g. TRUEFOUNDRY_API_KEY), see the Gateway / LLM Proxy section. | Any gateway API token |
ANTHROPIC_CUSTOM_HEADERS | sprint-master, workers | All modes | Additional HTTP headers sent with every Claude Code request, as one Name: Value pair per line (use \n to separate multiple pairs). For gateway routing or tenant headers. Credentials belong in ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY, not here. | X-Org-Route: prod |
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS | sprint-master, workers | All modes | Set to true to disable Claude Code experimental beta features. Useful for gateways that do not support Anthropic beta API surfaces. | true |
POSTGRES_PASSWORD | bundled Postgres container | docker-compose only | Password for the Compose-managed Postgres container. Defaults to colony if unset. Change this before production deployments. | Any strong password |
OPENAI_API_KEY | workers | All modes | API key for the OpenAI / Codex engine. Only required when any agent is configured with engine: codex in colony.config.yaml. The environment variable name is configurable via codex.api_key_env (default: OPENAI_API_KEY). | sk-… — generate at platform.openai.com |
WEBHOOK_SECRET | webhook-receiver | All modes | HMAC secret Colony uses to validate the signature on incoming GitHub webhook payloads. Must match the secret configured in your GitHub webhook settings. If unset, webhook signature validation is skipped. | openssl rand -hex 32 |
COLONY_INTERNAL_SECRET | webhook-receiver | All modes | Shared secret enabling the trusted-payload POST /internal/webhook endpoint used by Colony Cloud. Verified via constant-time comparison against the x-colony-internal-secret request header. When unset, the endpoint returns 404 (feature disabled). | openssl rand -hex 32 |
COLONY_DASHBOARD_PASSWORD | monitor | All modes | Password for the monitor dashboard (port 9106). Browser login uses a form-based session (COLONY_SESSION cookie); programmatic/CLI clients use an Authorization: Basic header as a fallback. If unset, the dashboard has no authentication — restrict port access in that case. Enable by setting agents.monitor.auth.password_env: COLONY_DASHBOARD_PASSWORD in config. | Any strong password |
DASHBOARD_DIST_DIR | monitor | All modes | Overrides the resolved path to the built dashboard static assets served by the monitor. Useful when the dashboard is built to a non-default location. If unset, defaults to the package-relative dashboard/dist directory. | /app/dashboard/dist |
MCP_TRANSPORT | mcp | All modes | Selects the MCP server transport: stdio (default, used by the local colony mcp command) or http (central HTTP server). When set to http, MCP_AUTH_TOKEN is required. | http |
MCP_AUTH_TOKEN | mcp (central HTTP server) | All modes | Bearer token required by the central MCP HTTP server when the optional mcp Compose profile is enabled. Not needed for the default local stdio mode (colony mcp). | openssl rand -hex 32 |
MCP_PORT | mcp (central HTTP server) | All modes | Port the central MCP HTTP server listens on. Default: 9300. | 9300 |
MCP_PATH | mcp (central HTTP server) | All modes | URL path for the central MCP HTTP endpoint. Default: /mcp. | /mcp |
MCP_HOST | mcp (central HTTP server) | All modes | Bind host for the central MCP HTTP server. Default: 0.0.0.0. | 127.0.0.1 |
MCP_LOG_LEVEL | mcp | All modes | Pino log level for the MCP server process. Default: info. Accepts standard Pino log levels: trace, debug, info, warn, error, fatal. | debug |
COLONY_HEALTH_TIMEOUT | scripts/colony-container.sh | apple-container mode | Health-check timeout in seconds used by the colony-container.sh deploy/restart script. Increase if worker containers take longer than the default to clone repos and install dependencies. Default: 120. | 300 |
COLONY_RUNTIME | cli | All modes | Overrides container runtime detection. Values: docker, container (Apple Container), or auto (default). | docker |
NODE_OPTIONS | all Node.js processes | All modes | Passed directly to Node.js at process startup. Use to raise the V8 heap limit for large codebases. | --max-old-space-size=4096 |
COLONY_INTERNAL_WORKER_ID | worker | All modes | Unique worker identifier used in multi-container deployments to prevent task-reclaim races. Set by the container orchestrator, not by operators. The default derivation (worker-<repoKey>-0) is identical across containers in the same pool; this variable makes each container’s ID distinct. | Set automatically by the orchestrator |
COLONY_CLOUD_TOKEN | cli (colony auth login) | All modes | Colony Cloud API token fallback for colony auth login. When set, skips the interactive token prompt. Can also be passed via --token. | Colony Cloud API token |
COLONY_CLOUD_URL | cli (colony auth login) | All modes | Colony Cloud API base URL fallback for colony auth login. Defaults to the production Colony Cloud URL (https://app.runcolony.com). Override when targeting a different Colony Cloud instance. | https://app.runcolony.com |
COLONY_GIT_SHA | cli (canary suite), worker | All modes | Fallback Colony git SHA recorded in canary run records. The live git rev-parse HEAD is used when available; COLONY_GIT_SHA is consulted only when the git command fails (e.g., a checkout without git history), defaulting to unknown when both are unavailable — this fallback behavior is specific to the canary-suite path. Also read directly by workers (no git rev-parse fallback, since a worker’s cwd is a target-repo worktree, not the Colony checkout) and reported as their build_id on registration. Unset means the worker reports no build_id (NULL), not a default of "unknown" — that worker is then excluded from fleet build-skew detection (WorkerPoolSnapshot.skewedWorkerIds, colony_worker_build_skew), since its build cannot be compared. Bake a real value into worker images via docker compose build --build-arg COLONY_GIT_SHA=$(git rev-parse HEAD) (see Dockerfile / docker-compose.yml) to enable skew detection. | abc1234def567890 |
COLONY_EXPECTED_BUILD | monitor | All modes | Declares the expected build identifier for the fleet, read once at monitor startup. Workers whose reported build_id (from COLONY_GIT_SHA) differs are flagged in WorkerPoolSnapshot.skewedWorkerIds and the colony_worker_build_skew Prometheus gauge. Unset by default (no skew detection). | abc1234def567890 |
COLONY_REPO | worker | All container modes (docker-compose, apple-container) | Pins a worker container to a single repository (owner/repo). In single-repo container deployments, the worker auto-derives this value from the config if the variable is unset — no manual configuration needed. In multi-repo configurations, every worker container must set this explicitly — if it is missing, the worker starts but logs a warning and claims no tasks, causing a silent task queue stall. Mutually exclusive with COLONY_TENANT. | your-org/your-repo |
COLONY_TENANT | worker | All container modes (docker-compose, apple-container) | Puts a worker container into nomad mode: the worker claims tasks from any repository in the specified tenant (external_id) using a cross-repo claim loop (claimNextTaskForTenant). Scale by adding more containers — pool_size is ignored in nomad mode (exactly one claim loop per process). Mutually exclusive with COLONY_REPO. | your-tenant-id |
COLONY_MULTI_REPO | all processes | All modes | Converts the multi-repo startup error in resolveConfig() into a warning, allowing Colony to start with more than one repository in the config. Self-hosted multi-repo orchestration is not supported — this escape hatch exists for Colony Cloud and advanced users who accept the caveats. See runcolony.com for supported multi-repo operation. | true |
NODE_ENV | mcp | All modes | Standard Node.js environment mode (development or production). Controls pretty-print vs JSON logging in the MCP server. Not an operator-configured setting — set by the process environment or your container runtime. | production |
COLONY_AGENT | core (config.ts) | docker-compose only | Set by docker-compose.yml for each service to signal a container environment. Used by isContainerEnvironment() alongside /.dockerenv detection. Not an operator setting — set automatically by Compose. | Set automatically by Compose |
COLONY_DRAIN_SHARED_SECRET | worker | All modes | Shared secret for the /drain endpoint on workers, enabling graceful shutdown from Colony Cloud. Not needed for self-hosted deployments. | openssl rand -hex 32 |
PLANNER_PUBLISH_GRACE_MS | sprint-master | All modes | Advanced tuning. Grace period (ms) before treating a newly-created epic child issue as dependency-blocked. Increase if the sprint-master races ahead of the newly-posted child. Default: 60000. | 60000 |
BRANCH_LINGER_GRACE_MS | sprint-master, monitor | All modes | Advanced tuning. Grace period (ms) a dependency branch is allowed to linger after merging before the blocked issue is unblocked. Default: 300000. | 300000 |
DEPENDENCY_FLAP_WINDOW_MS | sprint-master | All modes | Advanced tuning. Sliding window (ms) within which repeated dependency resolutions count as flapping and trigger a back-off. Default: 30000. | 30000 |
EPIC_CHILD_MERGE_GRACE_MS | sprint-master | All modes | Advanced tuning. Grace period (ms) an epic child issue may remain unmerged before the sprint-master triggers epic finalization. Default: 1800000 (30 min). | 1800000 |
Shell vs .env by Deployment Mode
Section titled “Shell vs .env by Deployment Mode”native and apple-container modes: Export variables in your shell before running Colony, or add export VAR=value lines to your ~/.bashrc / ~/.zshrc / ~/.profile so they survive terminal restarts.
export GITHUB_TOKEN=ghp_…export ANTHROPIC_API_KEY=sk-ant-api…export DATABASE_URL=postgresql://colony:colony@localhost:5432/colonydocker-compose mode: Copy .env.example to .env in the Colony directory and set values there. Docker Compose reads .env automatically and injects variables into every container. Do not commit .env — it contains secrets.
cp .env.example .env# Edit .env — set GITHUB_TOKEN, ANTHROPIC_API_KEY, and any optional variables