tmux

Why you need it

When an ssh connection drops, the foreground processes started from it are killed too. A brief Wi-Fi dropout or closing the laptop lid is enough to lose an rsync that has been running for half an hour, a compile, or the tail -f you were watching an output with.

tmux (terminal multiplexer) holds the shell on the server for you. Your ssh connection is just a view onto the tmux screen, so when it drops, the shell and programs inside tmux keep running. Reconnect, reattach, and everything is where you left it. Most clusters have tmux installed; if not, screen is probably there.

Create, detach, reattach

tmux works in sessions. After logging in to the cluster, start a named session. Pick a name that tells you what it is for.

$ ssh vanda
$ tmux new -s h2o-opt

A green status bar at the bottom means you are inside tmux. Every tmux shortcut starts with the prefix key, Ctrl-b by default. Ctrl-b d means: press Ctrl and b together, release, then press d.

# detach from the session: Ctrl-b d
[detached (from session h2o-opt)]

# list running sessions
$ tmux ls
h2o-opt: 1 windows (created Tue Sep 29 00:08:22 2026)
md-run: 1 windows (created Tue Sep 29 00:08:22 2026)

# reattach
$ tmux attach -t h2o-opt

Once detached, the session survives whether you log out or the connection dies. Log back in, check with tmux ls, reattach with tmux attach -t. With only one session, plain tmux attach is enough. With none, tmux ls answers no server running on ....

To end a session, close its last shell with exit from inside, or kill it by name from outside:

$ tmux kill-session -t md-run

Windows and panes

A session can hold several windows, and a window can be split into panes. Edit an input file in one pane and keep qstat in the other.

The left of the status bar lists windows as 0:bash 1:vim*; the * marks the current one.

Scrolling

Inside tmux, your terminal's scrollbar and mouse wheel do not show earlier output (until you enable the mouse option below). Press Ctrl-b [ to enter copy mode, then scroll with the arrow keys, PgUp and PgDn. Press q to leave.

~/.tmux.conf

tmux reads ~/.tmux.conf in your cluster home directory when it starts. Two lines make it much nicer to use:

# click to select panes, drag to resize, scroll with the wheel
set -g mouse on
# lines of output remembered per pane (default 2000)
set -g history-limit 50000

The file is read when the tmux server starts. In a session that is already running, press Ctrl-b : and type source-file ~/.tmux.conf. With the mouse on, tmux captures click-and-drag, so your terminal's normal text selection stops working; in most terminals holding Shift while dragging brings it back.

A warning about login nodes

Some clusters have several login nodes behind one address, and each login can land on a different one. A tmux session exists only on the node where you created it. If tmux ls shows nothing after reconnecting, run hostname to see where you are and ssh to the previous node by name.

screen

screen is an older program that does the same job. Use it on old systems without tmux. Same ideas, different keys: