Workers

Workers execute Colony’s pipeline tasks. Colony Cloud can provide managed capacity, accept BYO Worker registrations, or run both for an organization. The available pool and concurrency controls depend on the organization’s current plan and Worker-pool mode.

For capacity planning, rolling replacement, and self-host differences, use Operate and Scale Workers.

Understand Cloud Worker roles

• One Mayor coordinates intake and pipeline transitions across the connected repositories.
• Workers claim analyzer, planner, developer, reviewer, merger, and sweep tasks.
• A Worker executes one claimed task at a time.
• In multi-repository pool mode, Workers can serve any enabled repository in the tenant pool. Otherwise, deploy the repository-scoped commands shown by the dashboard.

Adding CPU or memory can help one task, but it does not make a single Worker execute multiple tasks concurrently. Increase the pool size or Worker count for parallel throughput.

Configure a multi-repository pool

When Worker Pool appears under Settings → Workers, the organization uses a tenant-scoped pool.

1. Set Pool size to the number of concurrent Workers the tenant may run.
2. Save the setting as an organization owner.
3. Confirm the Worker list converges to the intended size and each Worker reports a fresh heartbeat.
4. Watch queue wait, task duration, and provider/LLM limits before increasing it again.

Pool size is not a per-repository reservation. Eligible Workers serve enabled repositories according to queue and scheduling policy.

Register BYO Workers

Use BYO Workers when execution needs network access, hardware, or operational control that managed capacity does not provide.

1. Open Settings → Workers.
2. Under Registration Tokens, enter a name for one logical Worker group and click Generate.
3. Copy the token immediately. It is shown once and may be reused within that group.
4. Use the deploy commands shown beneath the new token. The dashboard generates the registry login, one Mayor command, and either a multi-repository Worker command or repository-scoped Worker commands for the current organization.
5. Wait for every process to register and report a fresh heartbeat before submitting work.

COLONY_CLOUD_URL defaults to https://app.runcolony.com. Set it only when the deployment should connect to a different Colony Cloud endpoint.

Caution

BYO Workers still use Colony Cloud for registration, configuration, task scheduling, provider credentials, and heartbeat. Placing a Worker in a private network does not create an air-gapped or self-hosted control plane.

Monitor Workers

The Worker table shows identity, repository scope, role, scheduling state, heartbeat freshness, current task, version, and execution health. Treat these states differently:

State	Meaning	Operator response
Online/active	Heartbeats are fresh and the Worker may claim tasks.	None unless queue or task metrics are abnormal.
Draining	The Worker is finishing its current claim and will not accept another.	Wait before stopping or replacing it.
Offline/stale	Heartbeats stopped.	Inspect the process and its claimed task.
LLM degraded	Worker is alive but its configured engine/provider is unavailable.	Correct the provider secret, entitlement, or network path.

Drain a Worker

Owners and administrators can click Drain. Colony sends a pending drain command on the Worker’s next heartbeat. The Worker finishes its current task, stops accepting new tasks, and reports draining state.

Drain before a planned image update, host shutdown, network change, or token rotation. Replace one Worker at a time when continuous capacity matters.

Reclaim an abandoned task

Reclaim task is available for an offline Worker. It releases that Worker’s current task to the queue so another Worker can claim it.

Caution

Use reclaim only when the old Worker is stopped or cannot finish. Reclaiming a healthy task can cause overlapping execution. Automatic orphan recovery already reclaims work after the heartbeat timeout.

Rotate or revoke a token

For a normal rotation:

1. Generate a replacement token.
2. Deploy replacement Workers and prove they can complete work.
3. Drain and stop Workers using the old token.
4. Revoke the old token.

Revocation takes effect on the affected processes’ next registration or heartbeat. For a compromised token, revoke immediately, then inspect and reclaim any abandoned tasks. See Rotate Credentials Without Stopping the Pipeline.

Scale safely

Scale only when eligible pending tasks wait while healthy Workers are busy. Idle Workers plus a growing queue indicate a routing, repository-scope, executor, budget, or provider problem rather than insufficient capacity.

SI tracks, external PR reviews, planning, review loops, and sweep tasks share capacity with ordinary implementation work. Check them before assuming user-filed issues are consuming the entire pool.