If you have ever started a long STAR alignment or GATK variant calling job over SSH, disconnected from the cluster, and come back to find the job dead, you understand the problem. SSH sessions terminate when the connection drops. The process running inside that session terminates with it.
Tmux solves this. It is a terminal multiplexer: it creates persistent sessions that continue running on the remote machine regardless of whether your local connection is alive. When you reconnect, you reattach to your existing session exactly as you left it.
This guide covers the tmux setup and workflow that actually matters for bioinformatics. By the end, you will have a working tmux configuration, understand the session and pane model, know the commands you will use every day, and be able to run overnight jobs without worrying about your SSH connection.
Prerequisites
- A Linux or macOS machine (local or remote)
- Basic comfort in a terminal
- SSH access to a remote server or cluster (optional but the main use case)
If you haven’t already set up SSH key-based authentication for your remote servers, do that first. It makes tmux workflow dramatically smoother because you aren’t re-entering passwords on reconnect. There is also a security argument: SSH keys with a strong passphrase stored in a hardware device like the YubiKey 5 NFC provide phishing-resistant authentication that password-based SSH does not. If you store sensitive genomic or patient data on cluster systems, hardware-backed SSH keys are worth the setup.
Installing Tmux
On most HPC clusters, tmux is already installed. Check with:
tmux -V
If it returns a version number (3.x is current as of 2026), you’re done. If not:
# Ubuntu/Debian
sudo apt install tmux
# macOS (via Homebrew)
brew install tmux
# CentOS/RHEL
sudo yum install tmux
If you are on a cluster where you don’t have sudo access and tmux is not installed, ask your sysadmin or check whether it’s available as a module: module avail tmux.
The Core Mental Model: Sessions, Windows, and Panes
Tmux has three layers of organization:
Sessions are independent workspaces. Each session persists on the server independently. You can create a session per project, per analysis, or per long-running job. Sessions survive disconnection.
Windows are like browser tabs inside a session. Each window is a full-screen terminal. You can have multiple windows in a session and switch between them.
Panes are splits within a window. You can divide a window into multiple panes showing different terminals simultaneously (useful for watching a running job in one pane while editing a config in another).
The hierarchy is: Session > Windows > Panes.
Starting, Attaching, and Detaching
Create a new named session:
tmux new -s rnaseq
This opens a new tmux session called rnaseq. The green status bar at the bottom confirms you’re inside tmux. The session name appears at the left of the bar.
To detach from the session (leave it running in the background), press:
Ctrl+b, then d
Ctrl+b is the tmux prefix key. Every tmux command starts by pressing Ctrl+b first. After detaching, you’re back in your normal terminal, but rnaseq is still running on the server.
To list active sessions:
tmux ls
To reattach:
tmux attach -t rnaseq
This is the core workflow: create session, start job, detach, disconnect. When you return (tomorrow, next week), reattach and everything is exactly as you left it.
Windows and Panes: The Commands You’ll Use Daily
Window management
| Action | Shortcut |
|---|---|
| New window | Ctrl+b c |
| Next window | Ctrl+b n |
| Previous window | Ctrl+b p |
| Go to window by number | Ctrl+b 0-9 |
| Rename window | Ctrl+b , |
| Close window | exit (or Ctrl+b &) |
Pane management
| Action | Shortcut |
|---|---|
| Split horizontal (top/bottom) | Ctrl+b " |
| Split vertical (left/right) | Ctrl+b % |
| Move between panes | Ctrl+b arrow keys |
| Resize pane | Ctrl+b Ctrl+arrow keys |
| Zoom pane to full screen | Ctrl+b z (press again to zoom out) |
| Close pane | exit (or Ctrl+b x) |
The pane zoom shortcut (Ctrl+b z) is one of the most useful in day-to-day bioinformatics. You can work in a split view for monitoring, then zoom in on your main pane when you need to focus on output.
A Practical Bioinformatics Workflow
Here’s how this looks in practice when running a full RNA-seq pipeline.
# Connect to cluster
ssh username@cluster.university.edu
# Start a tmux session for this project
tmux new -s rna_project_march
# Window 1: your main terminal for running jobs
# (this is where you are by default)
# Start a STAR alignment that will run for hours
STAR --runThreadN 16 \
--genomeDir /path/to/genome \
--readFilesIn sample_R1.fastq.gz sample_R2.fastq.gz \
--readFilesCommand zcat \
--outFileNamePrefix results/sample_ \
--outSAMtype BAM SortedByCoordinate &
# Create a second window for monitoring
# Press Ctrl+b, then c
# Now you're in window 2
# Watch job resource usage
htop
# Split this window to also watch disk usage
# Press Ctrl+b, then %
watch -n 5 df -h /scratch
# Detach when you want to leave
# Press Ctrl+b, then d
# The alignment continues running. Disconnect from SSH.
When you return later:
ssh username@cluster.university.edu
tmux attach -t rna_project_march
# You're back. Both windows are intact. The alignment log is right where you left it.
Setting Up a .tmux.conf
The default tmux configuration is functional but rough. A small config file makes it significantly more pleasant to use. Create or edit ~/.tmux.conf:
# Set prefix to Ctrl+a (easier to reach than Ctrl+b on most keyboards)
unbind C-b
set -g prefix C-a
bind C-a send-prefix
# Enable mouse support (click to select panes, resize panes by dragging)
set -g mouse on
# Start windows and panes at index 1 instead of 0
set -g base-index 1
setw -g pane-base-index 1
# Increase scrollback buffer (useful for long command output)
set -g history-limit 50000
# Faster escape key response (important for vim users)
set -sg escape-time 10
# More intuitive split keys (| and - mirror the visual result)
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
# Reload config without killing server
bind r source-file ~/.tmux.conf \; display "Config reloaded."
# Status bar customization
set -g status-bg colour235
set -g status-fg colour250
set -g status-left "#[fg=colour112][#S] "
set -g status-right "%H:%M %d-%b-%y"
set -g status-interval 60
Apply the config without restarting:
tmux source-file ~/.tmux.conf
The change to Ctrl+a as the prefix is optional but popular among people who use tmux heavily. It is one key closer on most keyboards than Ctrl+b.
Tmux + SSH: The Full Remote Workflow
A few tips specific to SSH sessions with tmux:
Name your sessions after projects, not tasks. One session per active project keeps things organized. tmux ls becomes readable.
Use the -CC flag with iTerm2 on Mac. If you use iTerm2, ssh -t user@host tmux new -s work -CC opens a native integration where iTerm2 renders the tmux windows as actual tabs. It’s significantly nicer than working inside a single terminal window.
Always attach before you start a new session. Run tmux ls before tmux new. It’s easy to create duplicate sessions when you forget one is running.
Transfer large files outside of tmux. Tmux session scrollback is not infinite, and watching a rsync progress bar inside tmux adds no value. Run large file transfers in a separate, non-tmux terminal tab.
Common Issues and Fixes
“sessions should be nested with care”: This error means you’re already inside tmux and trying to start another tmux. Use tmux new -s name to create a new session without nesting, or press Ctrl+b $ to rename the current session.
Colors look wrong: Add set -g default-terminal "screen-256color" to your .tmux.conf and ensure your local terminal supports 256 colors. iTerm2 and most modern terminals do.
Mouse mode doesn’t work on older servers: If set -g mouse on isn’t working, the server may be running tmux 2.x. Use set -g mouse-select-pane on and set -g mouse-resize-pane on instead.
Clipboard doesn’t sync on macOS: Install reattach-to-user-namespace via Homebrew and add set-option -g default-command "reattach-to-user-namespace -l $SHELL" to .tmux.conf.
SSH Security: A Brief Note
Since tmux is fundamentally a tool for remote server access, it’s worth addressing SSH key management. If you’re using username/password authentication for SSH, you’re relying on a credential that can be phished, reused across systems, or intercepted on insecure networks. This matters more as you access systems with genomic data or research data under data use agreements.
SSH key pairs are more secure and more convenient (no password re-entry). For an extra layer of protection, a hardware security key like the YubiKey 5 NFC can store your SSH private key on the hardware device itself, meaning it can’t be extracted from your laptop. Even if your laptop is compromised, the key can’t be stolen without the physical YubiKey. Setup instructions are on the Yubico documentation site.
This is not necessary for everyone. If you’re on a standard academic cluster where the main threat model is accidental exposure rather than targeted attack, standard SSH key pairs in ~/.ssh with a passphrase are sufficient.
Next Steps
You now have a working tmux setup and a configuration you can build on. The natural next step is combining tmux with a proper cluster job scheduler. If your institution uses SLURM, the nf-core tutorial covers submitting Nextflow pipelines through SLURM; tmux keeps the Nextflow driver process running while SLURM handles the actual compute jobs.
If you’re not yet set up with a reproducible analysis environment, read the conda and mamba setup guide next; having isolated environments for each project is the other half of reproducible remote bioinformatics.
If you’re new to remote computing and want to understand the full picture, the Git and GitHub guide for bioinformatics is worth reading alongside this one. Version control and session persistence solve different but related problems: one protects your code, the other protects your running jobs.