# Remote servers

:::note[Experimental]
Remote servers are experimental. Try them out, and if something doesn't work or a workflow you need is missing, [open an issue on GitHub](https://github.com/raine/workmux/issues).
:::

workmux can run an agent on a Linux server you reach over SSH, such as a home server, a Proxmox VM or a cloud VM, while your other agents stay on the local machine. Each remote agent still gets a normal tmux window on the local machine, and shows up in the dashboard, the sidebar, `workmux status` and `workmux list` like a local one.

The agent keeps running while the local machine sleeps, loses its network or closes the window. When you come back, the window reconnects by itself. When the work is done, `workmux merge` brings it home and merges it on the local machine.

_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](/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. The local window is a live view of them.
- 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.
- workmux installs and updates its own copy on the server. You don't install workmux 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/workmux/config.yaml
remotes:
  devbox: # the name you use on the command line
    host: devbox # an ~/.ssh/config alias or user@host
```

Then, from your project:

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

The window opens on the local machine as usual. When the agent is done:

```bash
workmux merge my-feature
```

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

## Differences from local agents

- Agents run directly on the server unless the sandbox is enabled. See [server or Docker](/guide/remote/setup/#server-or-docker).
- Remote agents need tmux in window mode, and the dashboard can't create them.
- 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](/guide/remote/troubleshooting/#known-limitations).

## Next

- [Setting up a server](/guide/remote/setup/): requirements, config, running on the server or in Docker, `setup` and `doctor`, which config the server uses, security.
- [Logins and secrets](/guide/remote/logins/): logging agents in, importing credentials, the Claude token, environment variables.
- [Working with remote agents](/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](/guide/remote/git/): merging, operation logs, rebasing, `remote pull`, what doesn't come home, pushing.
- [Maintenance and troubleshooting](/guide/remote/troubleshooting/): upgrades, cleaning up, retiring a server, common problems, known limitations.