#SSH

cmux ssh creates a workspace for a remote machine. Browser panes route through the remote network, files drag-and-drop via scp, coding agents send notifications to your local sidebar, and sessions reconnect on drops.

#Usage

cmux ssh user@remote
cmux ssh user@remote --name "dev server"
cmux ssh user@remote -p 2222
cmux ssh user@remote -i ~/.ssh/id_ed25519

cmux ssh reads your ~/.ssh/config for host aliases, identity files, and proxy settings. All flags mirror their ssh equivalents.

#Flags

#SSH deep links

Use cmux SSH deep links when a website or tool wants to offer an Open in cmux button. The link opens cmux, shows a confirmation prompt, then runs the equivalent cmux ssh command after the user confirms.

cmux://ssh?host=dev.example.com
cmux://ssh?host=dev.example.com&user=alice&port=2222&title=GPU%20box
cmux://ssh?host=workspace123.vm-ssh.freestyle.sh&user=workspace123%2Csession-token
cmux://ssh?host=dev.example.com&host-key-policy=accept-new&no-focus=true

Use the cmux.com fallback URL for website buttons. It opens the native link and shows the download if cmux is not installed.

https://cmux.com/deeplink/ssh?host=workspace123.vm-ssh.freestyle.sh&user=workspace123%2Csession-token&title=Freestyle

Prompt and rules buttons use the same fallback shape. Commas, colons, and literal plus signs are preserved when they are URL encoded:

https://cmux.com/deeplink/prompt?text=Review%20this%20branch
https://cmux.com/deeplink/rules?name=freestyle&text=Prefer%20commas,%20colons:%20and%20small%20PRs

Use the SVG icon for dashboard buttons, or the PNG logo when a raster image is required:

https://cmux.com/cmux-icon.svg
https://cmux.com/logo.png

Build the fallback URL with URLSearchParams so titles, host aliases, and user names are encoded safely:

const params = new URLSearchParams({
  host: "workspace123.vm-ssh.freestyle.sh",
  user: "workspace123,session-token",
  title: "Freestyle",
});

const href = "https://cmux.com/deeplink/ssh?" + params.toString();

Use cmux:// for the stable app, cmux-nightly:// for Nightly, and cmux-dev:// for Debug or tagged dev builds.

External links cannot pass identity files, raw ssh options, commands, ProxyCommand, or forwarding rules. Put keys, ProxyJump, HostName, and advanced options in ~/.ssh/config instead. cmux displays the command preview and requires the user to trust the SSH target before connecting.

#Browser panes

Browser panes in a remote workspace route all HTTP and WebSocket traffic through the remote machine's network. Type localhost:3000 and you're looking at the dev server running on the remote box. No -L flags, no manual port forwarding. Each remote workspace gets an isolated cookie store so sessions are scoped per-connection.

#Drag and drop

Drag an image or file into a remote terminal and cmux uploads it via scp through the existing SSH connection. cmux detects the foreground SSH process by TTY and routes the upload through ControlMaster multiplexing.

#Notifications

Processes on the remote machine can run cmux commands that execute on your local instance. When a coding agent calls cmux notify on the remote box, the notification appears in your local sidebar. The blue ring lights up on the workspace tab. Cmd+Shift+U jumps to it. Notification spam from flaky connections is suppressed with a per-host cooldown.

#Coding agents over SSH

cmux claude-teams and cmux omo both work inside SSH sessions. The Go relay daemon on the remote host handles the same tmux-compat translation that the local Swift CLI does. Teammate agents spawn as native cmux splits on your local machine while computation runs on the remote box.

# Inside an SSH session:
cmux claude-teams
cmux omo

#Reconnect

When the connection drops, cmux reconnects with exponential backoff (3s, 6s, 12s, up to 60s). The remote session persists and cmux reattaches on reconnect, resizing with smallest-screen-wins semantics. Default keepalive options (ServerAliveInterval=20, ServerAliveCountMax=2) are injected unless your config already sets them.

#Relay daemon

On first connect, cmux probes the remote host (uname -s, uname -m) and uploads a versioned cmuxd-remote binary. The binary speaks JSON-RPC over stdio and handles three things:

The daemon binary is stored at ~/.cmux/bin/cmuxd-remote/<version>/<os>-<arch>/cmuxd-remote on the remote host and verified against a SHA-256 manifest embedded in the app.