tmux ssh: fixing broken pipe and dropped sessions

tmux over SSH is the standard fix for a connection that drops mid-job: start or attach to a tmux session on the remote machine, and whatever you're running keeps going on the server even after the SSH connection itself dies. The one-liner is ssh host -t 'tmux attach || tmux new' — attach if a session exists, create one if it doesn't — and the -t matters, covered below.

Why a dropped connection doesn't kill your job#

A program started at a plain SSH shell prompt is a child of that shell. When the connection drops — laptop sleeps, network blips, you close the terminal — the shell and its pseudo-terminal go away, and SIGHUP propagates down to whatever it was running. That's why a long npm run build started over a bare SSH session dies the moment the connection does.

Inside tmux, the program you started is a child of the tmux server, a background process on the remote machine that has nothing to do with your SSH connection. Losing the connection just detaches you — the same as pressing prefix d on purpose. The job keeps running; you just aren't watching it.

The attach-or-create pattern#

ssh host -t 'tmux attach || tmux new'

tmux attach succeeds if any session exists and fails otherwise, so || tmux new only runs when there was nothing to attach to. Run this and you either land back in whatever you had running, or get a fresh session — never an error about a missing session name.

The -t is not optional here. SSH only allocates a pseudo-terminal automatically when you don't pass a remote command; the moment you hand it 'tmux attach || tmux new', you have to force it with -t or tmux fails with open terminal failed: not a terminal. If you're just running ssh host with no command and attaching manually afterward, you don't need it — the terminal is already there.

The nested-tmux problem#

If you already run tmux locally — inside iTerm2, or as your default shell wrapper — and then SSH into a box that also runs tmux, both are listening for the same prefix key. Press Ctrl-b and your local tmux catches it first; the remote session never sees it, which makes it look like none of your remote key bindings work.

Different prefixes per machine is the one worth actually adopting if you SSH into tmux sessions regularly — it's zero extra keystrokes forever, versus remembering to double-tap every time. Nothing about the rest of tmux changes once you're attached — tmux commands covers the full session, window and pane reference for whatever you do next.

"Client too small" and the resize fight#

Attaching from a narrow terminal — a phone SSH client, a small split — into a session that's already attached elsewhere can shrink everyone's view to fit yours, because by default a tmux window sizes itself to the smallest attached client. tmux attach session covers the full mechanics of window-size and aggressive-resize; the SSH-specific fix is simpler: attach with -d to detach every other client first instead of sharing the view.

ssh host -t 'tmux attach -d || tmux new'

That's the safer default for a quick SSH check-in from a small screen — you get your own view at your own size, and nobody else's layout moves because of it.

SSH keepalives: the real fix for broken pipe#

Write failed: Broken pipe almost never means tmux crashed — it means the underlying TCP connection died silently, usually because a NAT gateway or firewall dropped an idle connection without telling either end. tmux itself is unaffected; the session is still running on the server, waiting for you to reconnect.

The fix is a client-side keepalive, in ~/.ssh/config:

Host *
    ServerAliveInterval 60
    ServerAliveCountMax 3

ServerAliveInterval 60 sends a null packet every 60 seconds if nothing else is happening, which keeps the connection looking "active" to anything in between that would otherwise time out an idle one. ServerAliveCountMax 3 is how many of those can go unanswered before SSH gives up and disconnects on its own — better than hanging indefinitely on a connection that's actually dead.

tmux + SSH vs mosh#

These solve different layers and are often used together rather than as alternatives: mosh replaces the fragile TCP transport with something that survives roaming and packet loss, but it doesn't give you sessions, panes, or anything that outlives the mosh client itself — that's still tmux's job. If your problem is a laptop that changes networks constantly, mosh plus tmux beats either alone. If your problem is just an occasional dropped connection on a stable network, keepalives and tmux are enough.

Checking whether a long SSH-and-tmux job actually finished is the same "not at my desk" problem either way. If reattaching over SSH every time you want a status check gets old, mtmux (npm i -g mtmux) serves the same tmux session to a browser tab and can push a notification when a pane goes quiet — no SSH client required for the check itself, even though the session it's watching still runs exactly as described above.