Interactive Sessions with sinteractive¶

The sinteractive script launches a persistent interactive session on a compute node using tmux. It's located at scripts/sinteractive in this repository.

Why use sinteractive instead of srun --pty bash?¶

Installation¶

make install

This copies the script to ~/.local/bin/. Make sure ~/.local/bin is in your $PATH (add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc if needed).

To install to a different location:

make install PREFIX=~/bin

Usage¶

sinteractive [OPTIONS] [SBATCH_ARGS...]

Options¶

All other arguments are passed directly to sbatch, so you can use any sbatch option.

Environment variables¶

Set personal defaults in your ~/.bashrc; explicit flags always win.

# Example: always use mouse mode and a bigger default allocation
export SINTERACTIVE_MOUSE=on
export SINTERACTIVE_MEM=16G
export SINTERACTIVE_CPUS=4

Configuring for CU Alpine¶

sinteractive is written for Bodhi but is cluster-agnostic — the scheduler details are all driven by SINTERACTIVE_* variables. To run it on CU Boulder's Alpine, three things differ from the Bodhi defaults:

• tmux path — Alpine ships tmux as a system package at /usr/bin/tmux, not the source-built /usr/local/bin/tmux Bodhi uses.
• CPU partition + QOS — the general-purpose CPU queue is acpu (an explicit --qos is mandatory). acpu/cpu-normal are the names that take effect after Alpine's 2026-08-05 rename of amilan/normal; both name sets are already accepted, so using the new ones now means no change at the cutover.
• name clash on PATH — Alpine already provides an older, screen-based sinteractive in /usr/local/bin, which is ahead of ~/.local/bin on PATH. An alias forces your copy to win.

After make install, add this to your ~/.bashrc:

# Use the ~/.local/bin copy instead of Alpine's older /usr/local/bin one
alias sinteractive="$HOME/.local/bin/sinteractive"

export SINTERACTIVE_TMUX=/usr/bin/tmux     # Alpine's system tmux
export SINTERACTIVE_PARTITION=acpu         # CPU queue (was 'amilan' pre-2026-08-05)
export SINTERACTIVE_QOS=cpu-normal         # 1-day max walltime; QOS is required on Alpine

Then sinteractive launches a 1-day CPU session. For a longer run (up to 7 days), override the QOS: sinteractive --time=2d --qos=cpu-long. The default account (amc-general for most users) is applied automatically; pass --account=<name> if you need a different allocation.

Examples¶

# Default: 1-day session, 2 CPUs, 8G memory
sinteractive

# Run on a specific node
sinteractive --node compute01

# 2-hour session on the rna partition
sinteractive --time=2:00:00 --partition=rna

# Override default memory and CPUs
sinteractive --mem=16G --cpus-per-task=4

# GPU session
sinteractive --partition=gpu --gpus=1 --mem=16G

# Longer session on the normal partition (up to 3 days)
sinteractive --time=1-12:00:00 --partition=normal

How it works¶

1. Submits a batch job — sbatch launches the script itself on a compute node, where it starts a tmux session.
2. Waits for the job to start — polls squeue every 5 seconds until the job is running (you'll see dots printed while waiting).
3. Connects via SSH — once running, it SSHs into the compute node with X11 forwarding (-X) and attaches to the tmux session.
4. Stays alive until you exit — the SLURM job remains running as long as the tmux session exists. Detaching (Ctrl-b d) or losing your SSH connection leaves the job running so you can reconnect. Exiting tmux (exit) ends the job.

sequenceDiagram
    participant L as Login Node
    participant S as SLURM
    participant C as Compute Node

    L->>S: sbatch (submit job)
    S->>C: start tmux session
    L-->>L: poll squeue until RUNNING
    L->>C: ssh -X (attach to tmux)
    Note over C: you work here

Reconnecting after a disconnect¶

If your SSH connection drops or you intentionally detach (Ctrl-b d), the tmux session keeps running on the compute node and your work is safe. To reconnect from the login node:

# List your running sessions
sinteractive --list
#   JOBID       NAME                  NODE            PARTITION     ELAPSED     TIMELIMIT   CWD
#   12345       rna-seq               compute01       cpu           01:23:45    1-00:00:00  ~/projects/rna-seq

# Reattach
sinteractive --attach 12345

Sessions launched with -n NAME can be reattached by name (sinteractive --attach NAME). Forgot to name one? Press Ctrl-b $ inside the session to name (or rename) it in place — the new name shows up in the status bar, squeue, --list, and works with --attach NAME.

Scripting and agent use¶

sinteractive has a headless mode designed for scripts and coding agents such as Claude Code:

# Launch without attaching; returns once the session is ready
sinteractive --detach -n mywork --time=8h

# Machine-readable session info
sinteractive --list --json
sinteractive --status mywork --json
# {"job_id":147845,"name":"mywork","state":"RUNNING","node":"compute20",
#  "partition":"rna","time_limit":"8:00:00","elapsed":"0:43",
#  "end_epoch":1783180952,"remaining_seconds":28757}

# Run a command inside the allocation (exit code propagates)
srun --overlap --jobid=JOBID -- bash -lc 'make test'

Inside a session, SINTERACTIVE_JOB_ID (and SINTERACTIVE_NAME, if named) are exported, and sinteractive --status with no argument reports on the current session. A state file at ~/.cache/sinteractive/JOBID.json is refreshed about every 30 seconds with remaining_seconds, so tools can poll the time budget without querying the scheduler; it is removed when the session ends. In-session renames (Ctrl-b $) are reflected in the state file, --status, and new panes, but shells already running keep their original SINTERACTIVE_NAME.

make skill-install   # copies to ~/.claude/skills/bodhi-compute

Tips¶

Basic tmux commands¶

Cancelling the job¶

Exiting the tmux session (type exit or Ctrl-d in all panes) automatically cancels the SLURM job. You can also cancel it directly:

scancel <JOBID>