Keep work running with tmux sessions

Create, detach and reattach named tmux sessions, split windows and panes, write a minimal ~/.tmux.conf, and keep jobs alive when SSH drops.

how-to8 steps

Updated

in short

Start work with tmux new -A -s name, detach with Ctrl-b d, and reattach later with the same command. Programs inside the session keep running after you detach or your SSH connection drops.

tmux runs a server process that owns your shells. Your terminal is only a client attached to it, so closing the terminal or losing the network detaches the client while the shells, builds and log tails inside the session keep going.

This guide covers named sessions, the window and pane keys you need day to day, a short ~/.tmux.conf that enables the mouse and moves the prefix to Ctrl-a, and the pattern for long jobs on remote machines.

Tools used

Before you start

  • A Linux, macOS or BSD machine, or WSL on Windows
  • A package manager such as apt, dnf, pacman or Homebrew
  • For the remote workflow: SSH access to a server where you can install tmux

Steps

  1. Step 1: Install tmux

    Install it on every machine where you want sessions to survive, which for SSH work means the server, not your laptop.

    sh
    # Debian or Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# Arch Linux
sudo pacman -S tmux

# macOS
brew install tmux
    sh
    tmux -V

  2. Step 2: Start a named session

    tmux new starts a session; -s names it. Without a name, sessions are numbered from 0, which gets confusing once you have a few. The green status line at the bottom shows the session name on the left and its windows after it.

    sh
    tmux new -s work

  3. Step 3: Detach, list and reattach

    Every tmux key starts with the prefix, Ctrl-b by default: press and release it, then press the command key. Ctrl-b d detaches and returns you to your normal shell, while everything in the session keeps running.

    tmux ls lists sessions and tmux attach -t reattaches by name. tmux new -A -s attaches if the session exists and creates it if not, so you can use one command for both. Inside tmux, Ctrl-b s shows a session list to switch between, and Ctrl-b $ renames the current session.

    sh
    tmux ls
    output
    work: 2 windows (created Thu Oct  1 09:12:40 2026)
    sh
    tmux attach -t work
    sh
    tmux new -A -s work

  4. Step 4: Use windows and panes

    A session holds windows, like tabs, and each window can be split into panes. These are the default bindings, all after Ctrl-b:

    c new window, n and p next and previous window, 0 to 9 jump to a window, , rename the window, & close the window.

    % split left and right, " split top and bottom, arrow keys move between panes, z zooms the current pane to full size and back, x closes the pane.

    ? lists every binding, and [ enters copy mode to scroll back through output; press q to leave it.

  5. Step 5: Write a minimal ~/.tmux.conf

    tmux reads ~/.tmux.conf when the server starts. tmux 3.1 and newer also look for ~/.config/tmux/tmux.conf. This config moves the prefix to Ctrl-a, keeps Ctrl-a Ctrl-a for sending a literal Ctrl-a to the program in the pane, turns on the mouse for selecting panes, resizing and scrolling, keeps more scrollback and adds Ctrl-a r to reload the file.

    The mouse option needs tmux 2.1 or newer. tmux 3.8 turns it on by default; for older versions the line is required.

    tmux
    # ~/.tmux.conf

# Use Ctrl-a as the prefix instead of Ctrl-b
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Mouse: click to select panes, drag borders to resize, wheel to scroll
set -g mouse on

# Lines of scrollback kept per pane
set -g history-limit 50000

# Reload this file with prefix r
bind r source-file ~/.tmux.conf \; display "config reloaded"

  6. Step 6: Apply config changes

    Because the file is only read at server start, changes do not reach sessions that are already running. Load it into the running server from your shell, or use the r binding once it exists.

    sh
    tmux source-file ~/.tmux.conf

  7. Step 7: Survive SSH disconnects

    Run tmux on the remote machine, not locally. When the connection drops, the server-side session keeps running; reconnect and attach to pick up where you left off. ssh -t allocates a terminal so you can start tmux directly from the ssh command.

    Start long jobs such as builds, migrations or downloads inside the session before you need them to survive. A command started in a plain SSH shell is still tied to that connection.

    sh
    ssh -t user@server tmux new -A -s main
    sh
    # inside the session
./long-running-job.sh
# Ctrl-b d, or just lose the connection

# later, from any machine
ssh -t user@server tmux attach -t main

  8. Step 8: End a session

    Exiting the last shell in a session closes it. To close one from outside, use kill-session. When no sessions are left, the tmux server exits.

    sh
    tmux kill-session -t work

Troubleshooting

  • sessions should be nested with care, unset $TMUX to force: you ran tmux inside a tmux session. Detach first, or switch sessions with Ctrl-b s.
  • no server running or can't find session: no tmux server or no session by that name exists. Sessions do not survive a reboot or tmux kill-server.
  • New prefix or mouse setting has no effect: the server was already running when you edited the file. Run tmux source-file ~/.tmux.conf.
  • Window size jumps or shows dots along the edge: another client of a different size is attached to the same session. tmux attach -d -t work detaches the other clients.
  • Sessions disappear when you log out of the server: systemd-logind with KillUserProcesses=yes kills the login session's processes, including tmux. Run loginctl enable-linger once, then start tmux with systemd-run --scope --user tmux.
  • Cannot select text with the mouse after set -g mouse on: tmux now receives the drag. In many terminals holding Shift while dragging bypasses tmux and uses the terminal's own selection.

Tips

  • Ctrl-b w shows a tree of all sessions and windows with previews.
  • set -g base-index 1 numbers windows from 1, which matches the number row on the keyboard.
  • Copy mode uses emacs keys by default; set -g mode-keys vi switches it to vi keys.

Also worth a look

  • zellijTerminal multiplexer with detachable sessions and an on-screen key hint bar.

FAQ

Does tmux keep sessions after a reboot?
No. Sessions live in the tmux server process, so a reboot or killing the server ends them. Detaching and network drops are what tmux survives.
Should I run tmux on my laptop or on the server?
On the server for SSH work. A local tmux session holding an ssh command still loses that connection when the network drops; a remote session keeps the remote programs running.
What is the difference between ~/.tmux.conf and ~/.config/tmux/tmux.conf?
Both work in tmux 3.1 and newer. Older versions only read ~/.tmux.conf, so use that path if you share the file across machines with different versions.

related

tmux detailszellij details