# Remote servers

:::note[Experimental]
Remote servers are experimental. Keep the relevant `remote doctor` output and a reproducible command when reporting a failure.
:::

Workrex runs agents on an SSH-reachable Linux server while other agents stay
local. Each remote workspace owns a native session on the server's Rex instance, with its configured terminal blocks.
Rex.app shows those terminals directly; the dashboard, sidebar, `status`, and
`list` show them alongside local agents.

Agents keep running when your machine sleeps or disconnects. Reconnect Rex.app
and use `workrex open <handle>` to show a workspace again. `workrex merge`
brings its commits home and merges locally.

_Animation: An agent starts on devbox, keeps working while the local machine sleeps, and merges home._

Use a remote server when:

- agents need more CPU, memory or disk than your machine should give them
- agents should keep working while your machine sleeps or is offline
- you want to run more agents in parallel than your machine handles comfortably

If you only want to isolate agents on the local machine, use the [sandbox](https://kong109.github.io/workrex/guide/sandbox/) instead.

## How it fits together

- The worktree, its panes and the agent run on the server, either directly or in a Docker container. Rex.app connects directly to the server's Rex instance.
- The local machine stays the source of truth for Git. A new workspace starts from a local commit, unpushed commits included, and its work comes back with `merge` or `remote pull`. The server never talks to your Git hosting.
- workrex installs and updates its own copy on the server. You don't install workrex there yourself.
- Remote agents appear in every view labelled `handle@remote`, for example `my-feature@devbox`.

## Quick start

Add the server to your global config:

```yaml
# ~/.config/workrex/config.yaml
remotes:
  devbox: # the name you use on the command line
    host: devbox # an ~/.ssh/config alias or user@host
```

These are the Workrex configuration paths. See [configuration](https://kong109.github.io/workrex/guide/configuration/).

Then, from your project:

```bash
workrex remote setup devbox        # install workrex on the server
workrex remote doctor devbox       # check everything an agent needs
workrex remote login devbox claude # log the agent in on the server
workrex add my-feature --remote devbox -p "Implement the parser"
```

The native session appears under the server in Rex.app. When the agent is done:

```bash
workrex merge my-feature
```

:::caution[Put the branch before a bare `--remote`]
`--remote` takes an optional name, so in `workrex add --remote my-feature` the branch is read as the remote name. Write `workrex add my-feature --remote`, or name the remote: `workrex add --remote devbox my-feature`.
:::

## Differences from local agents

- Agents run directly on the server unless the sandbox is enabled. See [server or Docker](https://kong109.github.io/workrex/guide/remote/setup/#server-or-docker).
- The server must run Rex and be reachable by Rex.app. Remote layout options are described in the setup guide.
- Agents on the server can't push. Bring the work home and push from the local machine.
- Files ignored by Git, such as `node_modules` or build output, don't come home.
- `rename`, `path`, `run` and `sync-files` don't work on remote workspaces.

The full list is under [known limitations](https://kong109.github.io/workrex/guide/remote/troubleshooting/#known-limitations).

## Next

- [Setting up a server](https://kong109.github.io/workrex/guide/remote/setup/): requirements, config, running on the server or in Docker, `setup` and `doctor`, which config the server uses, security.
- [Logins and secrets](https://kong109.github.io/workrex/guide/remote/logins/): logging agents in, importing credentials, the Claude token, environment variables.
- [Working with remote agents](https://kong109.github.io/workrex/guide/remote/usage/): commands on remote workspaces, `rm` and `merge` from a remote pane, sleep and disconnects, agents that start agents, server reboots.
- [Bringing work home](https://kong109.github.io/workrex/guide/remote/git/): merging, operation logs, rebasing, `remote pull`, what doesn't come home, pushing.
- [Maintenance and troubleshooting](https://kong109.github.io/workrex/guide/remote/troubleshooting/): upgrades, cleaning up, retiring a server, common problems, known limitations.