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. Only organization owners can register and remove workers.
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, runcodex login. The worker only offers the agents it finds and can authenticate. - Tailscale (optional). Only needed for the opt-in direct terminal transport.
Check everything at once:
rivets doctorrivets doctor prints a table of what it found. 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.
Download the standalone worker
Download the worker for your platform from downloads.frontier.sh/rivets/worker.
| Platform | Architectures | Notes |
|---|---|---|
| macOS | arm64, x64 | Developer ID signed and notarized |
| Linux (glibc) | arm64, x64 | |
| Linux (musl) | arm64, x64 | |
| Windows | arm64, x64 |
Each build is a single executable that includes its own runtime. Every release publishes SHA256SUMS alongside the binaries.
Register the worker
- Open Settings › Workers and choose Add worker.
- Enter a Worker name, for example
ana-macbook. - Under Worker cluster, choose Create a new cluster and give it a name, or join an existing cluster. See Clusters and routing.
- Choose Register worker.
Rivets shows two things: a connect command and a one-time worker token that starts with rvw_.
Connect
Run the command on the worker machine and paste the token into the hidden prompt:
rivets worker connect --token-stdinThe worker enrolls with Rivets, then runs in the foreground and waits for jobs. It shows as online in Settings › Workers.
After the first run, the URL and name are saved, so you can reconnect with no flags:
rivets worker connectTo keep the worker running after you close the terminal, install it as a background service. See Background service.
Useful options
| Flag | What it does |
|---|---|
--name <name> |
Display name for this worker. Defaults to the machine’s hostname. |
--max-workers <count> |
Maximum number of tasks this worker runs at once. Defaults to unlimited. |
--no-scripts |
Never run a repository’s .rivets/settings.toml scripts on this worker. |
--no-auto-update |
Never update this worker unattended. |
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. If no secure store is available, the worker refuses to start rather than fall back to a plaintext file.
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.
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 statusrivets status prints the saved configuration with the token redacted, 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. Configure it under Settings › This Mac:
- Run this Mac as a background worker keeps the Mac accepting tasks after you close the Rivets window. Turning it off, or signing out, lets accepted tasks finish and then removes the service.
- Concurrent tasks sets how many tasks run at once, from 1 to 32. The default is 12. Rivets queues additional tasks until a slot is free.
The bundled worker updates together with the app. See Updates.
Remove a worker
In Settings › Workers, choose Remove next to the worker. Its token stops authenticating immediately. Running work is not transferred to another machine.