SlurmDeck

A local command-line tool and terminal UI for running code on a remote Slurm cluster.

PYTHON · CLI + TUI · V0.1.0 · MIT

By

github ↗pypi ↗

Overview

Running code on an HPC cluster usually means assembling the same loop by hand: rsync the project over, sbatch a script, poll squeue and sacct, tail logs over SSH, then copy results back. SlurmDeck folds that loop into one tool that works with the cluster’s existing accounts, partitions, and policies — nothing is installed on the cluster, and the login node only needs Python 3.8+ with the Slurm client commands.

Every run is immutable: planned and validated in memory, then committed atomically to the local run directory and SQLite database. Snapshots are content-hashed and upload once. Environments are managed conda builds with immutable generations or a user-owned prefix, and every command can emit a machine-readable JSON envelope for automation.

Workflow

  1. register

    Add a cluster once by SSH destination or alias; SlurmDeck verifies Python and the Slurm client commands on the login node.

  2. snapshot

    Sync rules capture the exact files a run needs as a content-hashed, immutable snapshot — previewed before anything uploads.

  3. submit

    Plan a command or parameter sweep, review the materialized run, then submit it atomically; a retry is a new run, never a mutation.

  4. monitor

    One status view merges live scheduler observations, per-task artifacts, and local lifecycle state; logs follow as they stream.

  5. fetch

    Pull results back into the local project with one command; the snapshot and receipts keep the run reproducible after the fact.

Console

SlurmDeck terminal UI showing the wide Runs screen in the dark theme
slurmdeck ui — runs / environments / remotes · keys 1 / 2 / 3

Under the hood

Atomic submissions

Runs are validated in memory and committed atomically — an interrupted submit leaves nothing half-landed on the cluster.

Immutable environments

Managed conda environments build in numbered, immutable generations with explicit garbage collection and recovery.

Sweeps & automation

Parameter matrices with exclude rules and {config}, {output}, {task_id} placeholders; every command speaks JSON for scripting.

Spec

version
0.1.0
language
Python
interface
CLI + TUI
substrate
Slurm over SSH
requires
Local: POSIX, Python 3.11+, git, OpenSSH, rsync · Cluster: Python 3.8+ and Slurm client commands
license
MIT
pipx install slurmdecksource on github ↗