Background service

Running rivets worker connect in a terminal works, but the worker stops when the terminal closes. Install it as a background service instead. The service runs as your user, needs no administrator rights, and opens no listening ports.

Install the service

Connect the worker once in the foreground so its configuration is saved, then install the service:

rivets worker connect --token-stdin
rivets worker install

install runs the same saved-configuration rivets worker connect you would run by hand. It is safe to run again: it only updates service definitions that Rivets created, and it leaves unrelated files alone. If creating or starting the service fails, Rivets restores the previous definition and state.

The token is never written into the service definition. The service reads ~/.rivets/config.json at start and loads the token from the OS credential store.

Service types

Platform	Service	Location
macOS	User LaunchAgent	`~/Library/LaunchAgents/com.rivets.worker.plist`
Linux	systemd user unit	`${XDG_CONFIG_HOME:-~/.config}/systemd/user/rivets-worker.service`
Windows	Task Scheduler task named `Rivets Worker`, runs at logon	Runner files under `~/.rivets/service`

Windows uses Task Scheduler rather than a Windows Service because the worker needs your signed-in CLI credentials and your developer tools on PATH.

Commands

Command	What it does
`rivets worker install`	Install, or safely update, and start the service.
`rivets worker status`	Show the service state and the worker’s health.
`rivets worker restart`	Restart only when the worker is idle.
`rivets worker logs`	Print a redacted, bounded tail of the service log.
`rivets worker stop`	Stop the service when idle and keep it from starting at login. It stays installed.
`rivets worker uninstall`	Stop and remove the Rivets-managed service when idle.

Status

rivets worker status reports whether the service is installed, enabled, and running, plus the worker’s health: protocol compatibility, last heartbeat, active jobs, open terminals, and any degraded reason. The worker refreshes this health snapshot every 30 seconds and on every meaningful change.

Stop and start again

stop stops the service and disables it at login, but keeps the definition in place. Run install to start it again. On macOS this avoids the “App Background Activity” notification that re-creating a LaunchAgent would trigger each time.

Uninstall

uninstall removes only the service definition (and on Windows, its runner). Logs, worker configuration, signing keys, repositories, worktrees, and health history are kept. To remove everything, see Cleaning up.

Idle protection and –force

install (when a service is already running), restart, stop, and uninstall refuse to interrupt work. They proceed only when the worker’s health confirms it has no active jobs or terminals, and no events still waiting to be delivered. If the worker has not written a fresh health snapshot yet, they fail safe.

Pass --force when you intend to interrupt active or unknown work:

rivets worker restart --force

Logs

rivets worker logs --lines 200

--lines defaults to 100 and is capped at 1,000. Log lines are redacted when written and again when printed: bearer tokens, worker tokens, credential URLs, and the configured token are stripped.

The combined log is ~/.rivets/logs/worker.log and rotates to worker.log.1. worker.out.log and worker.err.log capture anything the service manager writes directly.

Configure without a foreground run

rivets worker configure saves a service configuration without starting the daemon, which is useful for provisioning machines with a script. It reads a JSON object from stdin, so the token never appears in command-line arguments:

rivets worker configure --name build-box-1 --max-workers 4 < worker-config.json
rivets worker install

--name is required, up to 200 characters. --max-workers is optional.

Key	Type	Meaning
`url`	string, required	The Rivets URL. Must be `https://`.
`token`	string, required	The one-time `rvw_` worker token.
`directTransport`	boolean	`true` enables the Tailscale direct transport.
`loopbackTransport`	boolean	`false` sends same-machine terminal traffic through the relay.
`autoUpdate`	boolean	`false` turns off unattended updates.
`projectScripts`	boolean	`false` stops the worker running repository scripts.

{
  "url": "https://app.rivets.dev",
  "token": "rvw_...",
  "autoUpdate": true
}

The token is stored in the OS credential store. The input is capped at 16 KB.