Skip to main content
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

  1. 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 --config names). Run start once in the terminal too, to see the worker connect, then stop it with Ctrl+C.
  2. Find where r5d-worker, bun and node are: command -v r5d-worker bun node. r5d-worker is 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 names r5d-worker by its full path, and its PATH must hold Bun’s directory for commands, the directory of bun, which runs the worker, and those of node and npm, which run its launcher and its updates. Update CLIs also looks for r5d-worker on that PATH.
  3. To let agents build and run containers, run the service as a user who can use Docker (see Docker, and below).
What the service manager needs to know about the worker:
  • It updates itself. The installed r5d-worker is 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 logout on 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 on PATH (or in ~/.bun/bin), r5d-worker exits 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’s killall bun or pkill -u stops 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 with workspace_lock_unverified, exits with 1 and shows the reason in Settings → Workers. If no other worker runs with the same --root and label, add --archive-workspace-lock to the service’s r5d-worker start once (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:
Then:
The journal records when each line was written (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 with User= 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):
Then:
launchd records no times in the log file, so each line the worker writes there starts with the time it was written, in UTC (The worker’s log). The agent starts when you log in. launchd has no counterpart of systemd’s 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.