ssync

Your Slurm jobs, on every cluster, in one place.
Sync your code, submit jobs, stream their output, and relaunch them when they time out,
across all your HPC clusters, from your terminal, your browser, or your iPhone.

Documentation · Quickstart · Web app · iPhone app

Why ssync

Running experiments on several clusters usually means a dozen SSH sessions: squeue in one, tail -f in another, an rsync you hope skipped the virtualenv, and a 3 a.m. resubmit because a job hit its time limit one checkpoint short.

ssync runs on your own machine, talks to your clusters over SSH, and gives you one workspace for all of it. Nothing needs to be installed on the clusters.

• Every cluster at a glance. Running, queued, and finished jobs from all hosts in one view, with array jobs grouped and live updates.
• Launch from your laptop. ssync launch syncs your project (respecting .gitignore) and submits in one command, with login-node setup for clusters without internet on compute nodes.
• Live output anywhere. Stream stdout and stderr, search them, and read them from your phone.
• Watchers that act for you. Cancel diverging runs, capture metrics, or resubmit from the last checkpoint when a job times out.
• Know where you are in the queue. Queued jobs show their priority rank and the number of jobs ahead of them.
• Reproducible. Submitted scripts and launch manifests are cached, so you can inspect or relaunch a job after Slurm has forgotten it.
• Where you work. A CLI, a web app, a native iPhone app with Live Activities and widgets, and Raycast and VS Code extensions.

   

Quickstart

Warning

The ssync package on PyPI is an unrelated project. Install ssync from this repository.

# Install (the editable install includes the web app)
git clone https://github.com/Ramlaoui/ssync.git && cd ssync
uv tool install --editable .

Describe your clusters in ~/.config/ssync/config.yaml, reusing aliases from ~/.ssh/config:

hosts:
  - hostname: my-cluster              # an alias from ~/.ssh/config
    work_dir: /home/your-username/work
    scratch_dir: /scratch/your-username

Then:

ssync status                              # every job on every cluster
ssync launch train.sh . --host my-cluster # sync this project and submit
ssync output 12345 --lines 50             # follow a job's output
ssync web                                 # open the web app at https://localhost:8042

The web app's first start builds the frontend, which needs Node.js 18 or newer. Read the quickstart for a guided tour.

Documentation

Full documentation lives at ssync.ramlaoui.org:

• Installation and configuration
• Web app and iPhone app tours
• Launching jobs, watchers, and launch recipes
• CLI and API references, and security

To preview the documentation locally:

uvx --from zensical==0.0.65 zensical serve

Development

uv sync                          # Python environment
uv run pytest                    # backend tests

cd web-frontend
npm install
npm run dev                      # web app with hot reload
npm run test:run                 # frontend tests

The iPhone app lives in ios/ and opens in Xcode 26. Documentation screenshots are generated from sample data: web-frontend/scripts/docs-screenshots.mjs for the web app and the testDocumentationScreenshots UI test for iOS.

Contributing

Issues and pull requests are welcome.

License

Apache 2.0. See LICENSE.