Skip to content
workrex

Remote servers

Copy page

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.

devbox · Rex serverWorkflow illustration

Rex session

fix-login

Git branch and worktree

editor tabAgent block

Rex session

parser-tests

Git branch and worktree

editor tabAgent block
workrex add fix-login --remote devbox -p "Fix the redirect"
workrex add parser-tests --remote devbox -p "Test the parser"
workrex dashboard

Each task owns its files and Rex terminal IDs. The dashboard shows progress and opens the selected agent in Rex.app.

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 instead.

How it fits together

Section titled “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

Section titled “Quick start”

Add the server to your global config:

~/.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.

Then, from your project:

Terminal window
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:

Terminal window
workrex merge my-feature

Differences from local agents

Section titled “Differences from local agents”
  • Agents run directly on the server unless the sandbox is enabled. See 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.

Next

Section titled “Next”
  • Setting up a server: requirements, config, running on the server or in Docker, setup and doctor, which config the server uses, security.
  • Logins and secrets: logging agents in, importing credentials, the Claude token, environment variables.
  • Working with remote agents: commands on remote workspaces, rm and merge from a remote pane, sleep and disconnects, agents that start agents, server reboots.
  • Bringing work home: merging, operation logs, rebasing, remote pull, what doesn’t come home, pushing.
  • Maintenance and troubleshooting: upgrades, cleaning up, retiring a server, common problems, known limitations.