Clusters and routing

Every worker belongs to a cluster, a named pool of machines. When you create a task or an automation, Rivets either routes it automatically or keeps it inside the cluster you pin. This page explains how that choice is made and how to see which workers have capacity left.

Clusters

You choose a cluster when you register a worker in Settings › Workers › Add worker: either Create a new cluster with a name, or join an existing one. Use clusters to separate machines that should do different work, for example a team’s shared build boxes and individual laptops.

Routing a task

The Worker cluster menu in the New task dialog offers Auto and every cluster in your organization.

Auto

Auto picks the best available worker for the task. Rivets considers only workers that are online, can run the agent you chose, are shared with you, and whose owner can read the repository. It then prefers them in this order:

1. This Mac’s own worker, if you are creating the task in the Mac app and that worker is connected.
2. Workers with a free slot, ahead of workers that are already running as many tasks as they allow.
3. Among those, workers that reach Rivets through the same Cloudflare location as you.
4. The rest, spread in proportion to how many free slots each has.

Pinned to a cluster

Each cluster in the menu shows how many of its online workers can work on the selected repository. On the web it also shows their total slots, for example 2 · 8 slots. A cluster with no such worker cannot be picked, and shows Offline when none of its workers is online.

When you pick a cluster, the task runs only on a worker in that cluster. A pin never falls back to a worker outside the cluster. If no worker in it is online and able to run the agent, the task cannot start. Pinning a cluster with no worker you can use is refused. See Worker access.

Automations

Automations route the same way, as their creator. Each run uses Auto or the automation’s pinned cluster. A pinned run with no available worker fails immediately, without retrying elsewhere. See Automations.

Capacity

A standalone worker runs an unlimited number of tasks at once unless you cap it with --max-workers, from 1 to 32:

rivets connect --max-workers 4

The Mac app’s bundled worker defaults to 12 concurrent tasks. Change it from 1 to 32 under Settings › This Mac.

Auto routing spreads tasks by free slots, and an uncapped worker counts as having 1,000. Next to capped workers at the same location, it takes nearly every Auto task. Cap your workers if you want Auto to share work between them.

Provider health and subscription usage

Each worker checks its agent CLIs continuously, including whether they are signed in, and reports the result. An agent that is missing or signed out is not offered on that worker.

Because agents run on your own subscriptions, each worker also reports how much of its Claude and Codex allowance is left. Home shows this in every client:

• Session and weekly windows. Each window shows the percentage used and when it resets.
• Model-scoped windows. When Claude applies a weekly limit to one model family, it appears as a separate window under Claude’s own name for that model.

A window the provider has not reported is shown as unknown rather than empty. You can refresh the numbers on demand from Home for workers that support it.

When a worker disconnects

Rivets checks each worker’s connection every 30 seconds and shows it as offline when it has not answered for a minute. A worker whose connection silently stalls reconnects on its own within about 40 seconds.

A worker can lose its connection in the middle of a turn without losing the turn. It keeps every event the server has not yet acknowledged in a durable queue on disk and delivers it after reconnecting. Meanwhile the task shows Worker offline · paused.

If the worker does not come back, use Continue on another worker in the task header. Rivets picks another compatible worker, stops the old run, creates a linked task with the latest file changes applied, and imports the conversation so far. See Agents and models.

Removing a worker

Removing a worker in Settings › Workers revokes its token immediately. Work that was running on it is not moved to another machine.