<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:
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.
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 theworker parameter:
shellruns a command there, in the remote’s working directory and shell.shell_poll,shell_writeandshell_cancelfollow the run without naming the remote again, andwaitwakes when it finishes.read,write,edit,ls,findandgrepwork on the remote’s files: absolute,~/and relative paths (from its working directory). Results name a remote file asgpu-box:/path, like scp.copy_filecopies 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_pageandbrowser_upload_filescan save to, or upload from, 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”.