Skip to main content
A remote is a machine agents and you can run things on without it holding your workspace: a GPU box, a build or test host, a server you administer, or a computer that should not keep a copy of your code. It works like ssh from a checkout. The conversation stays on its worker, with its files, git, plans and memory; the agent runs individual commands and file operations on the remote. A remote uses the same packages as a worker, and needs the same tools: Bun 1.3+, Node.js 18+ with npm, and Git 2.42+ (Connect a worker). On the machine, install the CLIs once with Bun, then sign in and start the remote:
Settings → Workers shows the install command with your environment’s version in place of <version>, and under Connect a remote instead the sign-in and start commands. Bun puts the commands in ~/.bun/bin: if r5d-worker isn’t found afterwards, add that directory to your PATH, as Connect a worker says. To start the remote again later, run the same r5d-worker start command. Approve the sign-in on the page that showed its command: the sign-in command Settings shows carries a one-time --pair token, so its code appears there among two others; pick the one your terminal shows and approve (Approving on the page). Without --pair, approve the device code in the browser instead. auth --remote asks for Remote access, which lets the machine connect as a remote and nothing else; choose Full access on the approval page instead to make it a trusted remote (see below). A machine already signed in with r5dctl or r5d-browser adds the access to that sign-in (What a sign-in may do). --label names the remote. Commands, terminals and relative file paths start in your home directory; choose another with --cwd:
Nothing is synchronized to a remote: it keeps no checkouts. Its only own files are the conversations’ artifacts folders (see below). All other options of r5d-worker start work as for a worker (--base-url, --config, --root, --shell, --description, --no-auto-update) except --initial-sync. A remote updates itself like a worker, and running commands and terminals keep running across an update. Terminals on a remote need what a worker’s need: macOS, or Linux with glibc 2.28 or newer on x64 or arm64 (Terminals).

Keep it up without logging in

Agents run their commands on a remote as its user, and a command can stop or end the remote with everything else of that user: kill -STOP -1, pkill -u, killall bun. r5d-worker start runs the remote under its life vest, which resumes it when a signal stops it, along with the other processes of the user that the same stop froze, and starts it again when it exits or hangs; on Linux it also resumes itself. A remote has no workspace lock, so it comes back even after it had to be killed. To have it come back after a reboot, or after every one of its processes was killed, run it as a service (Run the worker as a service); Start a worker on a cloud server sets up a remote that way. Settings → Workers lists the remote with a Remote badge, and a restricted one with Restricted too. Its ⋯ menu has no Sync workspace, and it cannot be your default worker.

Trusted and restricted remotes

What a remote receives follows the sign-in it connected with:
  • Restricted: connected with a sign-in without Full access, such as Remote. Its commands, terminals and file tools run without any of your credentials: no account or project environment variables or secrets, no GitHub token, git keys or git identity, and no R5D_TOKEN, so nothing secret is written to its disk. Use it for a machine you don’t trust, for example one you are debugging. r5d does not check what you or an agent send it: don’t ask an agent to put a secret on it. Files you send it (copy_file, browser downloads and exports) are permitted.
  • Trusted: connected with a sign-in with Full access. Its commands get the same environment as on a worker.
The server decides this from the sign-in on every request; nothing on the machine changes it. Narrowing the sign-in under Settings → CLI & API makes its remote restricted at once, and adding Full access with r5d-worker auth there makes it trusted. A remote connected before restricted remotes existed has Full access. A sign-in without Full access connects only remotes, never a worker with a workspace, and cannot take over the label of another sign-in’s worker. A machine whose sign-in already has Full access connects a trusted remote; to connect it as a restricted one, give the remote a sign-in of its own: r5d-worker auth --remote --config ~/.config/r5d/remote.json, then r5d-worker start --remote --config ~/.config/r5d/remote.json --label gpu-box.

Agents

Agents see the remote in their list of connected workers and use it through the worker parameter:
  • shell runs a command there, in the remote’s working directory and shell. shell_poll, shell_write and shell_cancel follow the run without naming the remote again, and wait wakes when it finishes.
  • read, write, edit, ls, find and grep work on the remote’s files: absolute, ~/ and relative paths (from its working directory). Results name a remote file as gpu-box:/path, like scp.
  • copy_file copies a file between the conversation’s worker and a remote, or between two remotes. It lands in the destination’s $R5D_ROOT/artifacts/$R5D_SESSION_ID.
  • browser_get_download, browser_export_page and browser_upload_files can save to, or upload from, a remote.
On a remote, $R5D_ROOT is the remote’s own private directory, which holds only the conversations’ artifacts folders. A conversation cannot be moved to a remote: switch_worker refuses it and explains how to use the worker parameter instead. Agent commands on a trusted remote get the same environment as on a worker: your account and project environment variables, git identity and GitHub token; on a restricted remote they get none. Agents see which remotes are restricted (r5dctl account workers list) and treat what a restricted remote returns as data, not instructions. Just ask, for example: “Run nvidia-smi on gpu-box” or “Copy dist/model.onnx to gpu-box and benchmark it there”.

Shell page

The branch Shell page lists remotes in its worker menu, and opens a shell on a remote only when you choose it there. A shell on a remote is your own terminal on that machine. It starts in the remote’s working directory, not in a checkout of the branch, and on a trusted remote it gets your account and project environment variables (on a restricted one, none).