Using TMUX for persistent sessions

TMUX is a terminal multiplexer that creates persistent terminal sessions on your Pod.

Why use TMUX

While you can run long-running tasks in JupyterLab notebooks, the kernel can crash unexpectedly, losing hours or days of computation. TMUX runs your commands in persistent terminal sessions that continue even if JupyterLab crashes or you disconnect.

Requirements

To use TMUX, you need terminal access to your Runpod Pod (SSH, web terminal, or JupyterLab terminal).

Video tutorial

For a comprehensive video guide on using TMUX, check out this excellent tutorial: TMUX Tutorial on YouTube

Installing TMUX

TMUX is not installed by default on Runpod Pods. To install it, run:

Install TMUX

apt-get update && apt-get install -y tmux

Most Runpod templates are based on Ubuntu/Debian images that support apt-get. If you’re using Alpine Linux, use apk add tmux instead. Some minimal images may lack required dependencies.

Practical example: running model training

Here’s a typical workflow for running long-duration model training:

Training workflow

# Start a new TMUX session
tmux new -s model_training

# Navigate to your project directory
cd /workspace/my_project

# Start your training script
python train.py --epochs 100 --batch-size 32

# Detach from the session with Ctrl+B, then D
# You can now safely disconnect from the Pod

# Later, reconnect to the Pod and reattach
tmux attach -t model_training

Command reference

Starting a new session

Create a new TMUX session with a descriptive name:

Create named session

tmux new -s training

Detaching from a session

To detach from a session and leave it running in the background, press:

Ctrl+B, then D

Your processes will continue running even if you disconnect from the Pod.

Listing active sessions

View all active TMUX sessions:

List sessions

tmux ls

Reattaching to a session

Reconnect to a previously created session:

Reattach to session

tmux attach -t training

Killing a session

End a session when you no longer need it:

Kill session

tmux kill-session -t training

Killing all sessions

If you need to restart fresh and kill all TMUX sessions:

Kill all sessions

tmux kill-server

Alternatively, you can kill all sessions except the current one:

Kill other sessions

tmux kill-session -a

Advanced TMUX features

Window management

TMUX supports multiple windows within a session:

• Ctrl+B, C - Create new window
• Ctrl+B, N - Next window
• Ctrl+B, P - Previous window
• Ctrl+B, 0-9 - Switch to window by number

Pane splitting

Split your terminal into multiple panes:

• Ctrl+B, % - Split vertically
• Ctrl+B, " - Split horizontally
• Ctrl+B, Arrow keys - Navigate between panes
• Ctrl+B, X - Close current pane

Scrolling and copy mode

To scroll through terminal output:

1. Enter copy mode: Ctrl+B, [
2. Use arrow keys or Page Up/Down to scroll
3. Press q to exit copy mode

Best practices

When using TMUX on Runpod Pods, keep these tips in mind:

• Always name your sessions descriptively to easily identify them later.
• Regularly check on long-running processes by reattaching to sessions.
• Clean up finished sessions to avoid confusion.
• Use TMUX for any process that takes longer than a few minutes to complete.
• Consider creating a TMUX session immediately when connecting to a Pod for important work.

Troubleshooting

If you can’t reattach to a session after reconnecting to a Pod, the Pod may have been restarted. TMUX sessions don’t persist across Pod restarts, so ensure you save your work regularly and use network volumes for persistent storage.