spur-toolkit

Tools to deploy and debug Spur, an AI-native job scheduler.

Spur's source code, build instructions, and releases live in ROCm/spur. This repo is downstream of it — it doesn't build Spur, it operates on binaries/installers produced by that repo.

This repo is also packaged as a Claude Code / Cursor plugin, so its skills can be installed directly without cloning the whole repo.

Contents

• ansible/ — self-contained Ansible playbooks for bare-metal deployment. playbooks/deploy.yml covers single-node, multi-node, HA (multi-controller Raft), and HA-with-separate-compute topologies, with optional PostgreSQL/spurdbd accounting and WireGuard mesh; playbooks/teardown.yml tears a cluster back down. All playbooks share the same roles/ and inventory/.
• skills/deploy-spur/ — standalone Claude Code skill that drives the same deployment with only SSH + bash, no Ansible required. Useful for ad-hoc or one-off deploys.
• skills/diagnose-job/ — Claude Code skill that diagnoses why a Spur job won't start, failed, timed out, got OOM-killed, or is otherwise misbehaving. Covers all job states and 60+ pending reasons.
• techsupport/ — spur-techsupport.sh, a standalone SSH + bash script that collects a diagnostic bundle (logs, Raft state, sanitized config, cluster state, DB version) from a running native-host cluster into a single .tar.gz.

The Ansible and skill paths reach the same end state (systemd-managed daemons, Slurm-compatible CLI symlinks) and are independent of each other — using one doesn't require the other to be present.

Relationship to ROCm/spur

Building the spur/spurctld/spurd/spurstepd binaries still happens in ROCm/spur (cargo build --release -p spur-cli -p spurctld -p spurd -p spur-stepd). spurstepd is the per-job supervisor spurd spawns; it must be installed in the same directory as spurd, which the playbooks handle. Release tarballs also include spur_mpi_pmix.so; the Ansible playbooks install it on agents at /usr/lib/spur/. See ansible/README.md for the full clone-build-stage-deploy walkthrough. This repo only consumes those binaries (via spur_binary_src/SPUR_BINARY_SRC) or the upstream install.sh.