Connect a worker

A worker is a machine you own that runs agents for your organization. You can use the standalone rivets CLI on macOS, Linux, or Windows, or the worker bundled with the Mac app. Any member can register a worker. It belongs to them, and only they can use it until they share it.

Prerequisites

The worker machine needs:

• git 2.40 or later.
• Claude Code, Codex, or both, installed and signed in. For Claude Code, run claude auth login. For Codex, run codex login. The worker only offers the agents it finds and can authenticate.
• Tailscale (optional). Only needed for the opt-in direct terminal transport.

Once the CLI is installed, check everything at once:

rivets doctor

rivets doctor prints a table of what it found, including whether each agent CLI is signed in. It exits with status 1 if git is missing. It never installs anything unless you pass --yes, which on macOS allows it to run brew install --cask tailscale.

Register the worker

1. Open Settings › Workers and choose Add worker.
2. Enter a Worker name, for example ana-macbook.
3. Under Worker cluster, choose Create a new cluster and give it a name, or join an existing cluster. Members can join a cluster only if they already own a worker in it; owners can join any. See Clusters and routing.
4. Choose Register worker. In the Mac and iOS apps the button is Create.

Rivets shows Connect your worker with a one-line command that contains a one-time worker token. The token starts with rvw_.

Connect a Mac or Linux machine

Run the command on the machine you want to add:

curl -fsSL https://app.rivets.dev/install.sh \
  | RIVETS_TOKEN=rvw_... sh

The script:

1. Picks the build for the machine: macOS or Linux, arm64 or x64, glibc or musl.
2. Downloads the latest release and checks its SHA-256 checksum against the release manifest.
3. Installs rivets to ~/.local/bin and, if that directory is not on your PATH, adds it to your shell’s startup file.
4. Saves the connection for the Rivets site that served the script, and starts the worker as a background service.

The worker shows as online in Settings › Workers within a few seconds. The token is passed to the CLI on stdin, never as a command-line argument.

You can set these environment variables for the script, before sh:

Without RIVETS_TOKEN, the same script only installs or updates the CLI:

curl -fsSL https://app.rivets.dev/install.sh | sh

Connect a Windows PC

In Connect your worker, choose On Windows? Show the PowerShell command. The web app shows it first when your browser is on Windows. Run it in a normal PowerShell window, not as administrator, on the PC you want to add:

$env:RIVETS_TOKEN='rvw_...'
irm https://app.rivets.dev/install.ps1 | iex

The script:

1. Picks the x64 or arm64 build for the PC, using the operating system’s architecture, so an emulated PowerShell still gets the native build.
2. Downloads the latest release and checks its SHA-256 checksum against the release manifest.
3. Installs rivets.exe to %LOCALAPPDATA%\Programs\Rivets and adds that folder to your user PATH and to the window it ran in.
4. Connects the worker and starts it as the Rivets Worker Task Scheduler task, which runs at logon. See Background service.

It works in Windows PowerShell 5.1 and PowerShell 7. The token is passed to the CLI on stdin, and removed from the window’s environment first. If something fails, the script stops without closing your window. It warns when PowerShell is elevated, because the worker runs as the account that installs it.

Set these before irm, for example $env:RIVETS_WORKER_NAME='build-pc':

Without RIVETS_TOKEN, the same script only installs or updates the CLI:

irm https://app.rivets.dev/install.ps1 | iex

Connect with the CLI already installed

In Connect your worker, expand Already have the Rivets CLI? It shows a rivets connect command and the token on its own, with direct download links for Windows x64 and ARM64.

1. If you don’t have the CLI yet, download the build for your platform from downloads.frontier.sh/rivets/worker, name it rivets (rivets.exe on Windows), and put it on your PATH.
2. Run the command and paste the token at the Worker token (input hidden): prompt:

rivets connect --token-stdin

rivets connect saves the connection and starts the worker as a background service. To run the worker in the terminal instead, use rivets run --token-stdin.

Each build is a single executable that includes its own runtime. Every release publishes SHA256SUMS alongside the binaries.

Change a connected worker

The connection is saved. The URL, name, and options go to ~/.rivets/config.json, and the token to the OS credential store. Run rivets connect again with only the options you want to change, for example:

rivets connect --max-workers 4

To switch to a new token, run rivets connect --token-stdin and paste it.

Either way, rivets connect saves the change and restarts the background worker with it. If the worker is running jobs or terminals, it leaves the worker alone and says so. Run rivets install once the worker is idle, or rivets install --force to interrupt it.

Useful options

See the CLI reference for every flag.

Where the credentials live

The worker token is stored in the operating system’s credential store: Keychain on macOS, the Secret Service (libsecret) on Linux, and DPAPI on Windows. It never appears in ~/.rivets/config.json, a service definition, command-line arguments, or environment variables.

On enrollment, the worker also creates a signing key and binds it to the token. Every later request must be signed with that key. See Security.

Most Linux servers reached over SSH have no Secret Service. On such a machine, the first time the worker cannot store a credential there, it keeps the token and signing key in ~/.rivets/auth/credentials.json instead and prints a warning. The file is readable only by your user (mode 0600), but it is not encrypted. It protects against other users on the machine, not against root or someone with a copy of the disk. A worker whose credentials are already in the Secret Service never moves them to the file. On macOS and Windows there is no fallback: if the credential store is unavailable, the worker refuses to start.

rivets status shows where a worker’s credentials are stored.

What a worker can access

A worker runs agents under the OS account that started it. It has:

• Its own clones and worktrees under ~/.rivets/.
• Your agent CLI logins. Claude Code and Codex run with the credentials you signed in with, so usage counts against your subscription.
• Short-lived GitHub access for the repository a job is working on. Rivets hands a GitHub App installation token to each git command through a local credential helper. It is never written to disk.

A worker does not read your personal GitHub tokens, SSH keys, or existing git credential helpers.

Check the worker’s state

rivets status

rivets status prints the saved connection with the token redacted, where the credentials are stored, the background worker’s state and health, which agent CLIs it found and their versions, and the repositories and worktrees on disk.

The Mac app’s bundled worker

The Mac app includes a worker, so a Mac running Rivets can take tasks without the CLI. It belongs to whoever is signed in, and is shared like any other worker. Configure it under Settings › This Mac:

• Run this Mac as a background worker applies to the organization in the current window. Each organization you open in a Rivets window runs its own worker on this Mac, and keeps running it until you quit Rivets, even after its window closes. Turning the setting off lets that organization’s accepted tasks finish, then removes its worker. Other organizations keep theirs. Signing out removes them all.
• Concurrent tasks sets how many tasks each organization’s worker runs at once, from 1 to 32. The default is 12. Rivets queues additional tasks until a slot is free.
• Status shows what the worker is doing, and Restart worker restarts it. If it is running work, Rivets asks before interrupting it.
• Access sets who else may use this Mac’s worker. See Share a worker.

Other organizations on this Mac lists the workers this Mac is running for other windows, so a worker still finishing a closed window’s tasks stays visible.

When you quit Rivets, it stops its workers. If one is still running work, Rivets asks before stopping it. While the workers stop, a progress card appears over each window. If stopping takes more than a few seconds, the card offers Quit Anyway. If a worker cannot be stopped, the card says so and offers Keep Rivets Open or Quit Anyway.

The bundled worker updates together with the app. See Updates.

Share a worker

A new worker is available only to you. To let teammates run work on it, open Settings › Workers, choose Manage access, and pick Everyone in your organization, specific teams, or specific members. Teammates can watch tasks on your worker without access. They need it to start tasks, steer, or open terminals there. See Worker access.

Remove a worker

A worker’s owner, or an organization owner, can remove it. In Settings › Workers, choose Remove next to the worker. Its token stops authenticating immediately. Running jobs end as Worker was removed and are not transferred to another machine.

Removing a worker in Rivets does not uninstall anything on the machine. To stop the background service there, run rivets uninstall.