Working with remote agents

Commands on remote workspaces

Remote workspaces use the usual commands. Run them from the project on the local machine and name the workspace by its handle.

Command	On a remote workspace
close	Closes the local window only. The agent keeps running.
open	Reattaches to the running agent, or starts the panes again if they ended.
resurrect	Reopens windows of agents still running after the local machine’s tmux restarted, without restarting them.
status, wait, send, capture	Work whether or not the window is open. Agents are labelled handle@remote.
shell	Opens a shell in the workspace on the server, in the current terminal.
list	Shows remote workspaces with their server.
remove	Stops the agent and removes the remote worktree, branch and window, with the same checks as a local remove.
merge, rebase	See bringing work home.
rename, path, run, sync-files	Not supported.

remove --all and remove --gone only remove local worktrees. A remote branch such as origin/feature can’t be the new workspace’s branch: fetch it and pass it with --base. Some other add options aren’t available either; see add.

Sending prompts

workmux send and wait work as they do locally. An agent running directly on the server can only receive send once it has reported its first status, so give the first prompt with add -p or type it into the window. In Docker mode, send works as soon as the agent’s container is running.

Panes on the server

Every pane in the window is a session on the server. Non-agent panes are shells on the server, or in the container with sandbox.target: all.

• On the server directly: workmux works in every pane, including the shell left after the agent exits. It is the server’s copy, which knows the pane’s workspace.
• In Docker: shell panes on the server have no workmux. Run workmux commands for the workspace on the local machine. The agent’s container has workmux, for merge and rm and starting agents.

Opening a shell on the server

A tmux split of the window starts a shell on the local machine, not on the server. Run workmux shell in the split to get a shell in the workspace’s working directory on the server. In Docker mode the shell runs in a new container of the workspace; --host runs it on the server instead. Exiting the shell leaves the agent running.

Remove or merge from a remote pane

In a workspace running directly on the server, type the usual commands in any of its panes. An agent can run them too, including in Docker:

workmux merge
workmux rm

The local machine does the work, exactly as if you had run workmux merge my-feature or workmux rm my-feature there: it uses the local machine’s config, hooks and base branch, and closes the window when it is done. Meanwhile the pane shows the local machine’s progress:

Merging 'my-feature' on the local machine…
Started on the local machine; follow with `workmux remote logs devbox r0123456789ab`
Bringing the work to the local machine… (1s)
Preparing a local copy for the merge (files, post_create)…
Running pre_merge hooks locally… (42s)

The log holds the full hook output.

• The local machine must be awake and connected. If it doesn’t pick the request up within about 15 seconds, the request is withdrawn and the command fails with “the local machine isn’t connected”.
• Only the workspace’s own handle works: no name, ., or the handle itself.
• Nothing can ask questions, so these are refused with a hint: removing a workspace with unmerged commits without --force, merging staged changes that need a commit message (commit them first), squash merges, rm --all, --gone and --keep-branch. close is refused too, because the window is on the local machine.
• If the merge fails, the workspace stays and the pane prints why.
• In Docker mode, these requests run no hooks: no post_create, pre_merge or pre_remove, and no Git hooks, as for a local sandbox. Hooks would run outside the container on code the agent wrote. Run workmux merge <handle> on the local machine when you want them.

An agent can finish its own task this way, for example with -p "… when the tests pass, run: workmux merge" or the bundled /merge skill.

When the local machine sleeps or disconnects

The agent, its container and its tmux session run on the server, so they don’t depend on the local machine.

• The agent keeps working, and its status is recorded on the server.
• The window shows a status line with the server’s name and the reason, reconnects by itself, and offers keys to retry now or close the pane.
• Keystrokes typed while disconnected are dropped, never delivered late.
• The dashboard, sidebar and workmux status keep showing the agent’s last known state, marked disconnected with when it was last seen.

Short interruptions pass without any visible change. After an authentication or host key failure, or when the session was attached from somewhere else, the window doesn’t retry by itself: fix the cause and press the retry key.

Agents that start agents

An agent on a server can start a sibling the same way a local agent does (see spawning agents). The sibling is created on the same server, even while the local machine is away:

# run by the agent on the server
workmux add parser-tests -b -P task.md

• The agent must name a new branch. Generated names and existing branches are refused.
• The sibling starts from the tip of the agent’s branch, with the same mode, config, files and environment. post_create hooks don’t run.
• Its window opens next to the parent’s the next time the local machine connects. If it doesn’t, run workmux list from the project’s repository, or workmux open <branch>.

When the server reboots

A reboot stops the agents and containers, but worktrees, branches and records survive. The dashboard, status and list show the agent as exited because the server rebooted. To start it again:

workmux open my-feature

The agent starts with its continue flag, so agents that keep their conversations on disk pick up where they left off. open says whether it continued. The original prompt isn’t sent again, and nothing restarts automatically at boot.