Remote servers

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.

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.

~/code/api

☾Local machine asleep

Your machinetmux · gitsshdevboxnode · docker

☾ lid closed · 34 min

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

• 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:

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

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:

workmux merge my-feature

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

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.