stmux for Interactive Work

Some interactive work on the cluster needs to run for hours or even days. A common example is AI coding agents, such as Claude Code or Codex, which work through a task over a long session. When these long-running tasks run on the login nodes, they put a strain on a shared system that everyone relies on to log in, edit files, and submit jobs. Tasks are also fragile; if you lose connection to the login node because your laptop goes to sleep or your Wi-Fi drops, the session ends and whatever was running in it stops.

To avoid both problems, we created stmux. It provides a tmux session running on a compute node. You can disconnect, close your laptop, and reconnect later from anywhere, and your session will be exactly where you left it.

stmux is available on all login nodes. You can read the script itself at /apps/utilities/stmux.

1 stmux functionality

When you run stmux, it automatically:

1. submits a Slurm job and waits for a compute node,
2. starts a tmux session inside that job and connects you to it,
3. keeps the job running as long as the tmux session is open, and ends the job automatically when you close it.

2 Starting a session

From a login node, run:

stmux

You will see something like this:

Submitting Slurm allocation:
  sbatch --job-name=stmux --comment=stmux --partition=oneweek --nodes=1 --ntasks=2 --mem=6G --time=7-00:00:00 --account=myproject --wrap=<tmux keep-alive>
Job 11870148 submitted; waiting for a node...
Connecting to job 11870148 on a01-02...

The sbatch line shows exactly what stmux asked Slurm for, so you can check the partition, account, memory, and time limit at a glance. Once a node is ready, you are dropped straight into your tmux session on that node.

If the job is taking too long to start, press Ctrl-C while it is waiting to have stmux cancel the job for you.

3 Choosing resources

With no options, stmux defaults to:

• the oneweek partition,
• 2 tasks,
• 6 GB of memory,
• the maximum time limit of the partition,
• your default Slurm account.

Any of these settings can be changed to fit your needs. The option names are the same as sbatch. See the Running Jobs guide for sbatch reference.

Run stmux -h to see this list in your terminal.

Some examples:

# 12 GB of memory for 2 days
stmux -m 12G -t 2-00:00:00

# One GPU on the gpu partition
stmux -p gpu --gres=gpu:1

# Run on the main partition and give the job a recognizable name
stmux --partition=main -J analysis

Only ask for the time you need. The default is the partition’s maximum, which is convenient, but Slurm can often start shorter jobs sooner. On a busy partition, a smaller -t may get you a node faster.

4 Working inside the session

Everything you run inside the tmux session runs on the compute node, within the resources of your job. You can open several windows in the same session, for example one for an editor and one for a running program.

A few useful tmux keys:

5 Detaching and reconnecting

To leave your session running in the background, press Ctrl-b then d. Your programs keep running, and you can safely close your terminal or log out. stmux prints the command to reconnect:

Disconnected. If still running, reconnect with: stmux attach 11870148

If you lose track of the job ID, list your jobs with:

squeue --me

Then reconnect from any login node:

stmux attach 11870148

6 Finishing

When you are done, type exit in each tmux window. When the last window closes, the job ends and the node is released.

You can also end a session from a login node without reconnecting:

stmux cancel 11870148

This stops the job immediately, along with anything still running inside it. As a safety feature, stmux cancel only cancels jobs that stmux created, so a typo in the job ID will not cancel one of your other jobs.