Skip to main content
A new account starts with no workers. A worker runs commands and retains project workbenches on your own Mac, Linux machine, or VPS. The machine needs Bun 1.3 or newer, Node.js 18 or newer with npm, and Git 2.42 or newer: Bun installs and runs the worker; Node.js runs its command’s launcher, r5dctl and the worker’s terminals; npm installs its automatic updates; and Git keeps its workspace. Install the CLIs on the machine once with Bun, then sign in and start the worker:
Settings → Workers shows these commands with the exact version your environment runs in place of <version>, and its --base-url; copy them from there. r5d’s CLIs come from r5d.dev’s own npm registry, npm.r5d.dev, which also passes their dependencies through from npmjs.com, so --registry https://npm.r5d.dev is all Bun needs. The install needs no root access: it gives you the r5d-worker and r5dctl commands in Bun’s directory for them, ~/.bun/bin (bun pm bin -g shows it). --backend=copyfile makes Bun copy the package files: by default its global install hard-links them from its cache, and the worker refuses to run from hard-linked package files. auth alone is auth login. To start the worker again later, run the same r5d-worker start command: it needs no registry. On a machine without Bun, r5d-worker says how to install it. Bun’s own installer puts ~/.bun/bin on your PATH; a Bun from Homebrew or npm doesn’t. If r5d-worker isn’t found after the install, or command -v r5d-worker shows an older copy elsewhere (such as one npm installed), put that directory first on your PATH, for example with export PATH="$HOME/.bun/bin:$PATH" in ~/.zshrc or ~/.bashrc. To keep the worker running in the background and across reboots, run it as a service: Run the worker as a service. The worker runs Git as /usr/bin/git, whatever else is on your PATH, so that is the Git that must be 2.42 or newer; /usr/bin/git --version shows it. Debian 13, Ubuntu 24.04 and newer releases ship one. Debian 12’s Git 2.39 and Ubuntu 22.04’s Git 2.34 are too old: a newer git package, such as the git-core PPA’s on Ubuntu, replaces it at /usr/bin/git. On a Mac, /usr/bin/git is the Git of Xcode or its Command Line Tools; update them if it is older. A worker with an older Git still starts, says so in its log and synchronizes its workspace, but it cannot handle tracked files over 128 MiB or Git LFS pointers: r5dctl workspace status names that limitation until /usr/bin/git is updated and the worker restarted. Approve the sign-in on the page that showed its command. The auth command Settings → Workers and the onboarding show carries a one-time --pair token, so the code r5d-worker auth prints appears on that page among two others: pick the one your terminal shows and approve (Approving on the page). Without --pair, approve the matching device code in the browser instead. A worker needs a sign-in with Full access, which r5d-worker auth asks for: a worker holds your workspace and runs agents with all your credentials, so run one only on a machine you trust. Signing in authorizes r5d on the machine for every r5d command: r5d-worker auth, r5dctl auth login and r5d-browser auth save the same credential, shared by r5dctl, the worker and the browser on that machine. A machine that already signed in with one of them is asked only to add Full access to that sign-in, and the other clients there keep working (What a sign-in may do). Signing in starts nothing; r5d-worker start connects the worker, and --label names it. Use a separate label for each machine; do not copy a worker’s retained data directory to another machine while it is connected. If a copy does run, the worker started last serves the label: the other one stops taking work, names in its log the host that took the label over, and waits for you to stop it (starting it again takes the label back). To move a label to a new machine, stop the old worker, then sign in on the new machine (if it has not) and start the worker there with the same label: it takes over the label. A worker that stops gives its label up, so the new one connects at once. One that did not stop (it crashed, or its machine lost its network or went away) keeps the label until 45 seconds after its last check-in: the new worker says so, waits, and connects then. While the old worker still runs, the new one keeps waiting: stop the old one, or give the new one another label. On a machine, r5d-worker auth status (or r5dctl auth status) shows whose sign-in it holds and what it allows, and auth logout on any of the three revokes it: the worker and the browser on that machine can then no longer connect until you sign in again. You can also revoke it under Settings → CLI & API → Authorized devices, which has the same effect. For stage or another installation, keep its credential in its own configuration file and name the same file and base URL in both commands:
auth saves the credential together with the server it was issued for. The worker connects to --base-url, else the --config file’s server, else R5D_BASE_URL, else the default configuration’s (~/.config/r5d/r5dctl/config.json). Its credential is --token, else the --config file’s, else R5D_TOKEN, else the default configuration’s. A file named with --config replaces the R5D_* variables entirely. A saved or inherited credential is only sent to the server it was issued for: when the chosen credential belongs to another server, the worker stops before contacting anything and names both servers. When a server refuses the credential, at start or later because it was revoked or lost Full access, the worker says where it came from and how to sign in again, and stops with exit code 78, so that a service manager does not start it again until you have. An agent’s shell carries R5D_BASE_URL and R5D_TOKEN, the conversation’s own credential for the environment the agent runs in. That credential never connects a worker. To start a worker from an agent’s shell, sign in with --config as above and pass the same --config. Open Settings → Workers to confirm the worker is connected. Select it in the conversation’s worker menu: your next message moves the conversation there (Moving a chat to another worker), also when its current worker is offline or was removed. r5d verifies the actual destination workbench and publishes source changes before completing a transfer; stop active commands before changing workers.

Enroll a machine with a token

A server or container that nobody signs in on, such as one a cloud template or a script starts, connects with a one-time enrollment token instead of auth. In Settings → Workers → Enrollment tokens, or in the onboarding’s Host step, enter the machine’s worker label, choose what it connects as, and create a token:
  • Worker: a worker with a workspace, with Full access for that worker only. Agents there run with your secrets, so use it only for a machine you trust.
  • Remote: a remote for agents’ commands and file tools, which receives none of your secrets.
The page shows the token only once, in the commands that use it: copy them before you leave the page. On the machine, install the CLIs as above, then run:
auth --enroll exchanges the token for the machine’s sign-in, with no approval and no browser, and saves it as auth does. If it can’t save the configuration file, it says so before it uses the token. A remote then starts with start --remote --label gpu-server. A token works once, within an hour of its creation, for its label only. Revoke a token that is still open in Settings → Workers. Once used, it is that machine’s sign-in, listed under Settings → CLI & API → Authorized devices with the badge Only gpu-server; revoking it there disconnects the machine. The enrolled sign-in connects only that worker, as the token chose. It can’t connect another label or a browser, use r5dctl, approve sign-ins or create API keys, and no later auth login adds to it. To use r5dctl or r5d-browser on the same machine, sign them in with a configuration file of their own (--config, as above). On a machine enrolled for that label already, auth --enroll changes nothing and leaves the token unused, so a boot script or a container’s entrypoint can run both commands on every start; keep ~/.config/r5d on a volume, so that a new container for the same worker needs no new token. On a machine enrolled for another label, or signed in otherwise, it refuses, says which, and shows how to sign out first (auth logout) or enroll with a configuration file of its own. A token of another r5d, and an expired, used or revoked one, is refused with what to do. An r5d-worker from before enrollment tokens refuses --enroll and signs nothing in: install the version the page shows. For a new cloud server, Settings → Workers also writes a cloud-init or Terraform/OpenTofu file around the token, which sets the server up and connects it on its first boot: Start a worker on a cloud server.

Docker

Run the worker as a user who can use Docker, so that agents can build and run containers on it. The worker starts without Docker too; agents then can’t use containers there.
  • Linux: a member of the docker group: sudo usermod -aG docker $USER. The change applies from your next login, so start the worker from a new login (or a new service start; see Run the worker as a service).
  • macOS: the user who runs Docker Desktop or OrbStack.
Agents look for commands in /usr/local/bin, /usr/bin and /bin only, after r5d’s own, so docker must be in one of them. Linux packages put it in /usr/bin. On macOS, Docker Desktop links it into /usr/local/bin when its command-line tools are installed for the system (Settings → Advanced, System), and OrbStack when you allow it to install its tools there; otherwise they are in ~/.docker/bin or ~/.orbstack/bin, where agents don’t look, and terminals on the Shell page find them only through your PATH. Docker access amounts to root access on that machine: one more reason to run a worker only on a machine you trust.

Tools agents find

Settings → Workers shows each worker’s tools (open the worker): the versions of git, Node.js and Bun that agents’ commands run, and whether Docker works there. A worker checks them where agents look, in /usr/local/bin, /usr/bin and /bin, as its own user, so a tool only in your PATH’s other directories, such as Homebrew’s /opt/homebrew/bin, ~/.bun/bin or ~/.nvm, shows as not found where agents look: agents can’t run it by name there. Link it into /usr/local/bin if agents need it (this may need sudo). On a worker whose shell is zsh, agents’ commands also read ~/.zshenv, which can add directories to their PATH; the check doesn’t, so a tool found only that way shows as not found. For Docker, the worker runs docker version:
  • Docker and its version: it works, and agents can build and run containers on that worker.
  • Docker found, but…: docker is there, but this user can’t use it. The reason says why: no permission on its socket (on Linux, add the user to the docker group and start the worker from a new login, see Docker), its daemon isn’t running (start Docker Desktop or OrbStack, or the docker service), or it didn’t answer within 5 seconds. Docker’s own message is shown below it.
  • Docker not found where agents look: there is no docker there. A worker in a container has none.
The worker checks when it starts and again after it reconnects, at most every five minutes; restart it to check again at once, for example after you installed a tool. A worker on a release from before tools were reported shows them as Unknown, which says nothing about what the machine has: it reports them once it updates. r5dctl --json account workers list returns them too, as identity.tools.

Terminals

Terminals (the Shell page and r5dctl shell) work on macOS and on Linux with glibc 2.28 or newer (Debian 10, Ubuntu 20.04, RHEL 8 and newer), on x64 and arm64: the worker ships prebuilt binaries for them, so the machine needs no compiler. On musl systems such as Alpine Linux, and on other CPUs, the worker still connects and runs agent commands and file tools, but opens no terminals: it says so when it starts, and the Shell page shows the reason when you open one. An automatic update never takes terminals away from a worker that has them. Bun doesn’t run node-pty’s install scripts (bun pm untrusted lists them): the worker needs neither, since node-pty, which opens the terminals, ships its binaries prebuilt.

Describe a worker

Give each worker a one-line description of what it is for, such as “Mac with Xcode and the iOS simulator” or “GPU server for training runs”. Agents read the descriptions of your connected workers when they decide where to run something or which worker to switch to, and every worker menu shows them. Set it when you start the worker:
or edit it in Settings → Workers (open the worker, then the pencil next to its description), or with r5dctl account workers set my-laptop --description "…". A description is at most 200 characters on one line; an empty one clears it. r5d keeps it for the worker’s label, so later starts without --description keep it, and an edit in Settings stays when the worker restarts with the same --description (automatic updates included). Starting the worker with a different --description replaces it. Agents can change it too, with r5dctl in their shell (Agents use r5dctl like you).

Command slots

A worker runs a limited number of agent commands at once: its command slots, 16 unless you choose another number. Every conversation on the worker shares them; terminals (the Shell page and r5dctl shell, -c commands included) have 8 slots of their own. A command that finds every slot in use is refused before it starts, without affecting what already runs; the agent is told the limit and starts it again later. Builds, servers and polling commands each hold a slot until they end, so a worker that runs several agents, each with sub-agents, fills its slots quickly. Sub-agents start on the worker of the conversation that starts them, so the slots also set how many sub-agents a conversation on the worker can have queued, running or waiting at once: as many as the worker has slots, less one for the conversation itself (15 with the default 16). A further sub-agent is refused before anything is created, and the agent starts it once one of the others finishes. Raising the slots lets each conversation on the worker have more sub-agents; lowering them below what a conversation already has stops none of them, and it starts more once enough have finished. Choose the number for each worker in Settings → Workers (open the worker, then Edit next to Command slots), or with r5dctl account workers set my-laptop --command-slots 32: from 1 to 100, or default for 16. The worker applies it within seconds. Commands that already run are not affected: with fewer slots than running commands, new commands are refused until enough of them have ended. A worker whose shells still belong to a keeper of an earlier release (see Automatic updates) applies the new number once that keeper is replaced, the next time the worker starts while nothing runs; Settings says so until then. Agents can change command slots too, with r5dctl in their shell. Each worker reports the load of its machine beside its slots: the CPU load average and how many CPUs it may use, the memory in use (a container’s own limit when it runs in one), and the space on the disk that holds its root. Memory in use is what the system cannot give to new work without swapping: on Linux, all but what the kernel reports available; on a Mac, its wired and compressed memory, the share that memory_pressure does not count as free, since macOS makes room for new work by dropping caches and compressing app memory. Settings → Workers and the conversation’s worker menu show them with the slots in use, so you can tell whether a machine has room for more commands before you raise its slots, and which worker has free slots before you send a prompt. r5dctl account workers list shows them too, and agents read them there when they choose a worker.

Agents running at once

Your account runs a limited number of agents at once, set by your plan, and an r5d server also limits how many run at once for all of its accounts together. The conversation’s worker menu shows how many of yours run now, your limit, and how many the server runs. When your limit or the server’s is reached, new prompts, wakes and sub-agents wait in a queue and start by themselves, in turn, as runs end; nothing is refused. Another account at its limit never holds yours back. An agent that waits (for its sub-agents, a command or a wake) holds no run while it waits.

Choose a default worker

In Settings → Workers, choose a Default worker. This is saved to your account and survives reloads. Change it there at any time, or select No default worker / Clear default to remove the preference. New chats preselect your default when it is eligible, even with several workers connected. The dialog of a launch link prefers the link’s worker, the project’s launch default and your last choice there before your default. Choose another worker in the conversation’s worker menu to override it for that session only; this does not change your saved default or move existing conversations. A pending send or launch keeps its original worker when you retry. If no default is set, or it is disconnected, removed, or still preparing its workspace, r5d selects the sole eligible worker or asks you to choose when several are available. With no eligible workers, connect one before sending. r5d records a connected worker’s check-in at least every 20 seconds. A worker whose last recorded check-in is 35 seconds old is shown as Not responding, with when it was last seen. You can still select it; work sent to it waits until it responds or is disconnected. Once its last recorded check-in is 45 seconds old it is Disconnected and cannot be selected until it reconnects. The r5d-browser status follows the same rules. The branch Shell page opens its shell on the worker chosen in the menu at the top of the page, and opening a shell on a worker prepares the branch’s checkout there. Opened from a chat (Expand on the chat’s Shell panel, or Shell in the chat’s header where the window has no room for the panel; on a phone, in its menu), the page uses the chat’s worker and shows the chat’s shell, as the panel does. Otherwise it chooses by itself only when the choice is clear: the worker this browser tab used for the branch before, or your only worker. With several workers, also ones that aren’t connected now, it opens no shell until you choose one; your default worker doesn’t choose it. The Git page reads the server-synced checkout and does not require a worker selection. Keep the worker process running. A server deployment or temporary network outage reconnects its transport while local processes and source remain on the machine. Stopping or rebooting the worker itself is different: unfinished commands may need reconciliation on restart. Retained work is stored under ~/.local/share/r5d/personal by default; --root (or R5D_WORKER_ROOT) chooses another private directory. Several workers may share a root. A root inside another worker’s root, inside an agent’s workspace (R5D_ROOT), or inside a .r5d directory (which marks the legacy worker’s data) is refused.

Shell

Terminals and agent commands run in the worker’s shell: your login shell ($SHELL, or the one your account is set up with) when it is bash or zsh. A login shell that is plain sh is replaced by bash where bash is installed, and one that is neither bash, zsh nor sh (fish, for example) or that is not installed falls back to bash, then sh. To choose another, start the worker with --shell, naming bash, zsh or sh or the path to one:
A terminal starts the shell as a terminal window does, so it reads your startup files (~/.zshrc or ~/.bashrc). Commands, including r5dctl shell -c and the agent’s, run with -c and skip them. Settings → Workers shows each worker’s shell and why it was chosen (open the worker, then its version details), and agents are told which shell each connected worker uses. A single terminal or agent command can ask for bash, zsh or sh instead (r5dctl shell --shell bash); a shell the worker does not have falls back to bash, then sh.

Changes made while the worker was stopped

While a worker is stopped, its checkouts can change: files edited directly on the machine, or a branch another worker published in the meantime. --initial-sync says what the start does with those changes:
  • --initial-sync merge, the default, merges them with the server’s copy. When both sides changed the same lines, or lines next to each other (Git counts those as a conflict too), a conflict remediation opens on the worker, as for a running worker. A worker that has never synchronized this workspace makes its first copy instead: a file already on its disk that differs from the server’s copy stops it for a review, so neither version is lost.
  • --initial-sync reset deletes every project checkout on the worker and copies it afresh from the server, like rm -rf followed by a fresh copy. Everything in the checkouts that the server does not have is deleted: unpublished changes, and ignored files such as node_modules/ and .env. No backup is kept. Reinstall dependencies and recreate local configuration such as .env afterwards. The worker resets its checkouts one at a time while it starts synchronizing, so changes made in a checkout while the worker was stopped may still reach your other workers before the reset reaches that checkout, and are then kept rather than deleted. Where they overlap changes made meanwhile, a conflict remediation opens on the worker instead: the reset still replaces the checkout with the server’s copy, but the worker’s other chats stay paused until the remediation finishes.
The reset applies to that start only: later starts, including automatic update restarts, merge. The account workspace around the checkouts is not reset. r5dctl workspace reset resets the checkouts of a running worker the same way. If a reset stops part way, for example because the server could not be reached or a file could not be deleted, the checkout shows as blocked in r5dctl workspace status (reset_unfinished, with what stopped it). Nothing needs to be done unless the message names a cause to fix: the worker finishes the reset the next time the checkout is used or its history is synchronized, and when it starts.

The worker’s log

r5d-worker start writes its log to its output: the terminal it runs in, a file you send it to, or where a service puts it. The worker, its life vest and its keeper, which runs the shells and terminals, write to it, and each line starts with the time it was written, in UTC:
A log that records the time of each line itself gets the lines without it, so that no line shows two: systemd’s journal (journalctl shows the times) and a container’s log (docker logs -t, kubectl logs --timestamps). To decide yourself, set R5D_LOG_TIMESTAMPS in the worker’s environment: on adds the time to every line, wherever the log goes, and off to none. A keeper an earlier release started writes its lines without the time until the worker replaces it (Automatic updates).

The life vest

Agents’ commands run as the worker’s own user, so a command can stop or end the worker together with everything else of that user, by mistake or not: kill -STOP -1, pkill -u, killall bun (on Ubuntu, even kill -STOP -1234 run from a program means -1). A stopped worker never exits, so nothing would notice it. r5d-worker start therefore runs the worker under a life vest: the process you start watches the worker, which it runs as a second process, and brings it back without anyone logging in to the machine:
  • Stopped. Every 2 seconds it checks. When it finds the worker or its keeper (which runs the shells and terminals) stopped, it resumes them, along with every other process of the user that the same stop froze, such as agents’ dev servers. A process that was already stopped before stays stopped. On Linux the life vest also resumes itself, so a stop of every process of the user doesn’t keep it stopped; on macOS it can’t, and such a stop freezes your whole session anyway.
  • Exited. A worker that exits by itself (a crash, a kill, a failed start) is started again after 2 seconds, then after longer waits, up to 5 minutes, while it keeps failing.
  • Hung. A worker whose heartbeat stops for 2 minutes, or whose connection loop stops for 10, is stopped (killed when it doesn’t stop within 2 more minutes) and started again. A worker killed outright leaves its workspace lock, and its next start moves the lock aside, since the process that held it no longer runs (Run the worker as a service); a remote has no such lock.
It updates with the worker. Ctrl+C, SIGTERM or a closed terminal stop both, and a refused sign-in ends both with exit code 78. A workspace lock that an older release left, which can’t say whether its worker still runs, is asked about in the terminal you started the worker from: move it aside and start, or exit (exit code 79). On Linux, Ctrl+Z doesn’t keep the worker suspended: the life vest resumes it, in the background. Nothing on the machine survives a kill -9 of every process of its user; to have the worker come back from that too, run it as a service, which restarts it. Settings → Workers shows in a worker’s details what its life vest last did and when, for example “Resumed it after a signal stopped it (17 processes) · 2 minutes ago”.

Automatic updates

A worker updates itself; r5d-worker start needs no extra option. While connected, it checks for the environment’s selected release once a minute and downloads it in the background. Once the update is ready, new shells and workspace operations wait while the worker finishes the workspace operations already running, then it restarts into the new release. Running shells, terminals and long-running servers keep running and move to the updated worker; agents pause at their next step and continue after the switch. Settings → Workers shows download status, pending updates and failed attempts, and the outcome of the worker’s last update: the version it updated to, or the version it failed to install and how many times. The worker’s shells and terminals belong to a separate keeper process, which Settings lists with its own version. A keeper started by an earlier release keeps running across updates so that your shells survive; the worker replaces it the next time it starts while nothing runs, and Settings notes the older keeper until then. The worker and its bundled r5dctl switch together. Credentials, labels and workspace files stay in place. The worker briefly disconnects and reconnects, and failed installations leave the current version running and retry after five minutes. Automatic restarts do not repeat an initial --initial-sync reset. Updates use npm and private version directories beneath the worker’s state root; they do not need root access or replace globally installed commands. They download from the npm registry your r5d environment names (npm.r5d.dev for r5d.dev). Your terminal’s separate global r5dctl installation remains managed by your package manager. The installed r5d-worker stays the worker’s launcher: on later starts, including when a service starts it, it runs the updated version. Installing another version with Bun replaces the launcher, and the next start runs that version. To turn automatic updates off, start the worker once with --no-auto-update, using the same label, environment and root:
The choice is saved locally for that worker, so later starts without the option keep updates off. Start it once with --auto-update to turn them back on. A worker installed before automatic updates were on by default needs one more manual upgrade (Update CLIs below, then a restart); from then on it updates itself, unless you turned updates off with --no-auto-update.

Updating and syncing from Settings

In Settings → Workers, a connected worker’s ⋯ menu can also update its CLIs on demand with Update CLIs, and publish its workspace with Sync workspace. Both run on the server and the worker rather than in the browser. Their progress stays visible after a reload and in other tabs, and a Sync shows each worktree as it is published. An installation can take a few minutes. When it finishes, stop active commands and restart r5d-worker to use the new version. Update CLIs installs the CLIs on the worker’s machine the way the r5d-worker on the worker’s PATH was installed: with Bun’s global install (bun install --global --backend=copyfile) when it is Bun’s, else with npm install -g, so no second copy ends up where your PATH doesn’t look. The manual update command Settings shows follows the same rule. Update CLIs is offered for a worker that runs those installed CLIs; for a worker started another way, the worker’s details show the install command, after which you start the installed r5d-worker. A worker with automatic updates applies updates by itself, so Settings shows its update status instead of Update CLIs. If the worker disconnects while an update or sync runs, Settings says so, and the work continues when the worker reconnects. A failed installation or a version mismatch shows what to do next, such as running the manual update command on that machine.

Update available and Update required

An older worker usually keeps working: Settings marks it Update available and it updates when it can. Occasionally a release of r5d needs a newer worker than the one a machine runs. Settings then marks that worker Update required, says why, and shows the step that resolves it: an automatic update already in progress, Update CLIs, or a command to run on that machine. Until it updates, the worker takes no new shells, terminals or workspace operations, and conversations cannot switch to it; the worker menu in a conversation shows it as unavailable with the reason. Shells and servers it already runs keep running, you can still read its files and output, stop its processes, and update it. When the reason is its keeper (the process that owns its shells), let those shells finish and restart the worker. A browser can be marked Update required the same way; it then takes no new actions until you install the shown version and restart it. When a release of r5d needs newer workers, connected workers and browsers with automatic updates download the new version ahead of time and switch to it together with r5d itself. During the switch, new shells and workspace operations wait (usually under a minute; agents pause at their next step and continue by themselves), while running shells and servers keep running. A browser restarts after its current action and keeps Chrome open. A worker that was offline, or that has automatic updates turned off, is marked Update required when it reconnects. To update it by hand on that machine: stop it, install the version Settings shows (Settings also shows the command), and run r5d-worker start again with the same options. Use the same steps with r5d-browser for a browser. Account environment entries and secret files are delivered only to commands for your account. Updates apply to newly started commands. Revoke the machine’s sign-in under Settings → CLI & API → Authorized devices when it should no longer connect; that signs out its worker, its browser and r5dctl together. You provide and pay for the worker machine and your model access. Configure your own model provider in Settings → Models, with the models you want to use, before sending a prompt.