ksterx/srunx

**A unified CLI, web dashboard, and Python API for SLURM job management.**
Stop juggling sbatch scripts, squeue loops, and SSH sessions.
- **Submit & manage** SLURM jobs from CLI, browser, or Python
- **Orchestrate** multi-step workflows with YAML and dependency graphs
- **Monitor** GPU availability and job states with Slack notifications
- **Local or remote, one CLI** — target a local SLURM or any SSH'd cluster with --profile ; no shell-in, no separate "remote" commands — the same verbs you already know
- **Container-native** — Pyxis, Apptainer, and Singularity support built in
Installation
Requires Python 3.12+ and access to a SLURM cluster (local or via SSH).
The web dashboard and Slack notifications are included in the base install — no extras required.
For AI agent integration (MCP server), add the mcp extra:
Quick Start
Submit a job, wait for it, and view the logs — end to end:
Or describe the whole pipeline once and let srunx drive it:
Same commands, remote cluster
Every command above accepts --profile and dispatches transparently over SSH — same syntax, same output, same feel as local:
srunx rsyncs your code under a per-mount lock, runs sbatch in place on the remote, and streams logs back. Your shell never leaves the laptop.
Why srunx?
Instead of stitching together sbatch, squeue, SSH, and a pipeline runner, srunx offers one coherent surface that covers the day-to-day SLURM loop.
| Capability | srunx | submitit | simple-slurm | Snakemake |
|---|:---:|:---:|:---:|:---:|
| CLI for submit / status / cancel | ✅ | ❌ | ❌ | ⚠️ partial |
| Python API | ✅ | ✅ | ✅ | ✅ |
| Web dashboard | ✅ | ❌ | ❌ | ❌ |
| Workflow DAG with dependencies | ✅ | ❌ | ❌ | ✅ |
| Inter-job value passing (load-time) | ✅ | ❌ | ❌ | ⚠️ via files |
| Matrix parameter sweeps | ✅ | ⚠️ manual | ❌ | ⚠️ via wildcards |
| GPU availability monitoring | ✅ | ❌ | ❌ | ❌ |
| SSH remote submit + file sync | ✅ | ❌ | ❌ | ❌ |
| Container support (Pyxis / Apptainer / Singularity) | ✅ | ⚠️ limited | ❌ | ⚠️ via rules |
| Slack notifications | ✅ | ❌ | ❌ | ⚠️ plugin |
If you need full-featured scientific workflow tooling, Snakemake / Nextflow are still the right call. srunx targets the sweet spot of *"SLURM + a few dependencies + a nice UI"* without Airflow-scale infrastructure.
CLI
**Every command below runs locally _or_ against a remote cluster over SSH.** Add --profile (or set $SRUNX_SSH_PROFILE) and sbatch / squeue / sinfo / sacct / history / gpus / tail / watch / flow run transparently dispatch through the SSH adapter — no shell-in first, no separate "remote" subcommand. srunx ssh is just for managing those profiles (add / list / sync / test); it does not run jobs itself.
Type column: **SLURM** = mirrors the native SLURM CLI (muscle memory maps directly); **srunx** = srunx-original command with no direct SLURM counterpart.
Job submission & control (SLURM parity)
| Command | Type | Description |
|---------|------|-------------|
| srunx sbatch / srunx sbatch --wrap " " | SLURM | Submit a SLURM job |
| srunx scancel | SLURM | Cancel a job |
Status & accounting
| Command | Type | Description |
|---------|------|-------------|
| srunx squeue | SLURM | List active jobs (use -j for a single job's state) |
| srunx sinfo | SLURM | Partition / state / nodelist listing (native-sinfo parity) |
| srunx sacct | SLURM | Real SLURM sacct wrapper (cluster accounting DB) |
| srunx history | srunx | srunx's own submission history (SQLite-backed) |
| srunx gpus | srunx | GPU aggregate summary across partitions |
| srunx tail | srunx | View / stream job logs |
| srunx watch jobs\|resources\|cluster | srunx | Watch for state changes / resource availability |