r5d-worker start runs until you stop it. To keep a worker running without a terminal, start it with the machine and start it again when it fails, run the same command from your system’s service manager: systemd on Linux, launchd on macOS. Its life vest already brings back a worker that was stopped, crashed or hangs; the service manager starts the machine’s worker at boot and brings back the life vest itself. The examples run the r5d-worker that Bun installed (Connect a worker); copy your environment’s --base-url from Settings → Workers in place of https://r5d.dev.
Before you start
-
Install the CLIs on the machine as Settings → Workers shows, as the user the service will run as, then sign in as that user, in a terminal:
The service starts with that sign-in (
~/.config/r5d/r5dctl/config.json, or the file--confignames). Runstartonce in the terminal too, to see the worker connect, then stop it with Ctrl+C. -
Find where
r5d-worker,bunandnodeare:command -v r5d-worker bun node.r5d-workeris in Bun’s directory for commands,~/.bun/bin(bun pm bin -g). A service does not read your shell’s startup files, so the service namesr5d-workerby its full path, and itsPATHmust hold Bun’s directory for commands, the directory ofbun, which runs the worker, and those ofnodeandnpm, which run its launcher and its updates. Update CLIs also looks forr5d-workeron thatPATH. - To let agents build and run containers, run the service as a user who can use Docker (see Docker, and below).
- It updates itself. The installed
r5d-workeris the worker’s launcher: it starts the version the worker updated to, also after a restart, so the service needs no edit for an update. Installing another version with Bun changes what the next start runs. - Exit codes. A missing or refused sign-in exits with 78: no credential for the server, or one that was revoked (
auth logouton any r5d client of the machine, or Settings → CLI & API), lost the access a worker needs, or names a label another sign-in’s worker holds. Starting again does not help until you sign in again, so don’t restart on 78. Every other failure, such as a server that cannot be reached at start, exits with 1 and is worth a retry. Without Bun onPATH(or in~/.bun/bin),r5d-workerexits with 127 and says how to install it. - Stopping. On a stop the worker ends its commands and terminals, then exits; give it a minute and a half before the service manager kills it (the examples below do).
- Restart after any exit. The worker’s life vest restarts the worker, but it stops like any process on a stray
SIGTERM: an agent’skillall bunorpkill -ustops it cleanly, with exit code 0. So the examples restart it after any exit but a stop by the service manager and a refused sign-in. - Killed outright. A worker killed outright (
kill -9, the out-of-memory killer, a power cut, a stop that outlasts the service manager’s wait, or its life vest after it hung) cannot release its workspace’s lock. The lock names the worker’s process, so the next start sees that it no longer runs, moves the lock aside and carries on; its log says so in one line, and the commands that were running are listed as ended, or with an unknown outcome when nothing recorded how they ended. A lock that an older r5d-worker release left doesn’t say which process held it: unless the machine restarted since, the start refuses withworkspace_lock_unverified, exits with 1 and shows the reason in Settings → Workers. If no other worker runs with the same--rootand label, add--archive-workspace-lockto the service’sr5d-worker startonce (or run that start in a terminal, which asks) and restart the service. Another worker that still holds the lock is named (authority_busy), and the service starts once that one stops. A remote holds no workspace, so it has no such lock.
Linux: systemd
As root, save this as/etc/systemd/system/r5d-worker.service, with your user, label and paths:
journalctl -o short-iso-precise shows it to the microsecond), so the worker writes its lines there without the time it otherwise starts them with (The worker’s log).
When the sign-in is refused, systemctl status r5d-worker shows the service failed with status=78/CONFIG, and the log says why and which command signs in again. Run that command as the service’s user, then sudo systemctl start r5d-worker.
Without root, run it as a user service: save the unit as ~/.config/systemd/user/r5d-worker.service without the User= line and with WantedBy=default.target, then systemctl --user daemon-reload, systemctl --user enable --now r5d-worker, and loginctl enable-linger $USER so that it runs while you are not logged in. journalctl --user -u r5d-worker -f shows its log.
Docker
A service withUser= gets that user’s groups each time it starts: once the user is in the docker group (sudo usermod -aG docker alice), sudo systemctl restart r5d-worker gives the worker, and the agents’ commands it runs, access to Docker. To give the group to the service alone, without adding the user to it, add SupplementaryGroups=docker to the [Service] section instead.
A user service runs in your own systemd instance (user@<uid>.service), which keeps the groups it started with. After adding yourself to the docker group, restart that instance (sudo systemctl restart user@$(id -u), which stops your other user services too) or reboot; with lingering on, logging in again doesn’t restart it.
Agents find docker in /usr/bin, where Linux packages put it (Docker).
macOS: launchd
Save this as~/Library/LaunchAgents/dev.r5d.worker.plist, with your label, home directory and paths (command -v r5d-worker shows where the installed CLI is; /opt/homebrew/bin holds Homebrew’s Bun and Node.js):
RestartPreventExitStatus: with KeepAlive on, it starts the worker again after any exit, 78 included, at most once per ThrottleInterval seconds (10 by default, 60 above). So after a refused sign-in the log shows the refusal once a minute until you sign in again (r5d-worker auth in a terminal; the next start then connects) or unload the agent with launchctl bootout, which is also how you stop it. ExitTimeOut gives a stopping worker the same minute and a half as the systemd unit: by default launchd kills a job 20 seconds after asking it to stop. On macOS the life vest can’t resume itself: a stop of every process of your user, which also freezes your desktop, stops it too.
The agent runs as you, so the worker can use the Docker Desktop or OrbStack you run. Agents find docker in /usr/local/bin, which the PATH above includes: let Docker Desktop install its command-line tools for the system (Settings → Advanced), or OrbStack install its tools there (Docker).
r5d-browser can run the same way on a Mac: a second agent, with its own label (dev.r5d.browser), log file and the installed r5d-browser start with the --base-url Settings → Browser shows. A missing or refused sign-in ends it with 78 too.