shell

Opens an interactive shell in a workspace on a remote server and runs it in the current terminal. It starts in the workspace’s working directory, and you don’t need the server’s SSH address or the worktree path.

workmux shell [name] [--host]

Arguments

• [name]: Remote workspace handle or branch, or project:handle, as for send. When omitted, it uses the remote workspace whose window the command runs in.

Options

Flag	Description
--host	In a workspace whose agent runs in Docker, run the shell on the server, not in Docker

Where the shell runs

• Agent on the server directly (isolation: none): the shell runs on the server, with the server’s workmux and the workspace’s environment, like the window’s other panes.
• Agent in Docker: the shell runs in a new container of the workspace, with the same image, mounts and environment as the agent’s. This does not depend on sandbox.target. --host runs the shell on the server instead. It is the only way to get a server shell, and that shell has no workmux.

The first line in the shell says which of these you got.

Opening it next to the agent

A tmux split of a remote workspace’s window starts a shell on the local machine. Run workmux shell in that split to replace it with a shell on the server:

# in a new split of the remote window
workmux shell

You can also bind a key to open a split running the remote shell. Add a binding like this to your tmux config:

bind S split-window -h "workmux shell"

The split closes when the shell exits.

Ending the shell

• Exiting the shell ends it on the server, and workmux shell returns. The agent and its workspace keep running.
• When the connection drops, the pane shows a status line and reconnects to the same shell, as the window’s other panes do.
• Closing the pane, or pressing q while it is disconnected, also ends the shell on the server. If the server can’t be reached at that moment, the shell keeps running there until the workspace’s agent is restarted or the workspace is removed.
• Commands that stop the agent, such as remove and merge, end its shells too. So does workmux open when it restarts the agent after a server reboot.

Errors

• A local worktree name is refused. Use cd "$(workmux path <name>)" for local worktrees.
• If the server can’t be reached, shell fails at once and names the server.
• A workspace that never started on the server is refused with a hint to run workmux open <name>.