> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octomerge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a remote

> Let agents run commands and edit files on a machine without bringing your workspace to it, like ssh.

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](https://docs.octomerge.dev/get-started/add-worker.md)). On the machine, install the CLIs once with Bun, then sign in and start the remote:

```bash theme={null}
bun install --global --backend=copyfile @ricsam/r5d-worker@<version> @ricsam/r5dctl@<version> --registry https://npm.r5d.dev
r5d-worker auth --remote
r5d-worker start --remote --label gpu-box --description "GPU server for training runs"
```

**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](https://docs.octomerge.dev/get-started/add-worker.md) 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](https://docs.octomerge.dev/cli/r5dctl.md#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](https://docs.octomerge.dev/cli/r5dctl.md#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`:

```bash theme={null}
r5d-worker start --remote --label gpu-box --cwd ~/experiments
```

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](https://docs.octomerge.dev/get-started/add-worker.md#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](https://docs.octomerge.dev/get-started/add-worker.md#the-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](https://docs.octomerge.dev/get-started/worker-service.md)); [Start a worker on a cloud server](https://docs.octomerge.dev/get-started/cloud-server.md) 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.