CLI Reference

Installation & authentication

curl -fsSL https://supercomputer.sh/install.sh | sh   # install + sign in + agent skills

Or, with your own Python:

pip install gpu-compute-provider
super login            # sign in via the browser; saves a key + installs agent skills
super set_token <key>  # already have a key (CI, agents)
super setup            # re-run the skill install / save a key you already have
super health           # verify connectivity

How the pieces fit

Global flags

Place --json before your remote command: flags after the command — or after a -- — belong to your program. So super exec --json -- python app.py selects supercomputer's JSON output, while super exec -- python app.py --json passes --json to app.py. Unknown flags are rejected (a typo'd --limitt is an error, never silently ignored).

Find hardware

super skus     # list available GPU/CPU SKUs
super health   # check dispatcher connectivity

SKUs follow the pattern gpu_<count>x_<model> (e.g. gpu_1x_l4, gpu_8x_h100) or cpu_<...>. If a SKU has no free capacity, the session queues until a host is provisioned. Browse the catalog.

Run code

Without --on, exec and run create a throwaway session, do the work, and release it automatically — its filesystem is still saved and downloadable afterwards. With --on <session-id> (or a positional s-... argument) they attach to an existing session, run, and detach, leaving the session alive.

super exec --sku gpu_1x_l4 nvidia-smi -L        # one-off command
super run train.py --sku gpu_1x_l4              # upload + run one file
super run . --script train.py -- --epochs 50    # upload a dir, pass args
super exec --on s-abc123 python train.py        # attach to a session
super exec s-abc123 -- python train.py          # positional alias for --on

Working directory

Commands run from /workspace by default — the same place super upload puts your files. An uploaded train.py runs as python train.py; relative writes land in /workspace and persist. To run elsewhere for one command, cd inside it: sh -c 'cd /some/dir && ...'. This applies uniformly to exec, run, spawn, and shell.

Waiting, detaching, and long commands

exec waits in the foreground for a budget (default 30s; set with --wait 10m or the alias --timeout). If the command finishes in time, stdout/stderr are printed and the CLI exits with the remote return code. If not, exec does not kill it — it detaches and prints a process id:

Command is still running; use super logs s-abc123 proc-456 --follow

In --json mode a detached command returns status: "running" and returncode: null plus session_id and process_id — treat that as success-with-handle, then super wait <sid> <pid> or super logs <sid> <pid> --follow. For jobs you expect to run long, prefer spawn + wait from the start (see below).

Output is bounded by default so a noisy command can't flood the caller. If the JSON response has stdout_truncated: true, don't rerun the command — fetch the durable log instead: super logs <sid> <pid> --output all.

Shell parsing

Pass commands as normal argv when you can. A single quoted string runs as shell text (via bash -lc), and sh -c works for explicit shell syntax:

super exec --on s-abc123 python train.py --epochs 10
super exec --on s-abc123 'cd /workspace; ls'
super exec --on s-abc123 -- sh -c 'sleep 45; echo done'

Unquoted metacharacters are handled by your local shell first: super exec --on s-abc123 sleep 45; echo done runs sleep 45 remotely, then echo done locally.

Background processes

The reliable pattern for long jobs:

super spawn --on s-abc123 python train.py     # prints proc-456 immediately
super logs s-abc123 proc-456 --follow         # watch it live
super wait s-abc123 proc-456 --timeout 0      # block; exits with its exit code

wait reads durable logs, so it works after the host is gone, survives checkpoint/migration, and exits 75 if a positive --timeout elapses while the process is still running. Prefer it over hand-rolled logs | grep loops — it distinguishes "still starting" from "already died".

The default log stream is combined (stdout + stderr) — prefer it. Most ML tooling (tqdm, HuggingFace/TRL) writes progress to stderr, so --stream stdout on a training job often looks empty even though it's producing output.

--emit-pid FILE (on spawn, exec, and run) writes {"session_id": ..., "process_id": ...} JSON to a file the instant the process starts — capture the handle even when stdout is piped or backgrounded. Never pipe a live exec through | tail: it buffers everything until EOF and swallows the detach line carrying the process id.

Sessions

Session lifecycle

A session's state is reported by super sessions:

A freshly created session is cold and costs nothing until its first exec/run/upload. There is no resume command — targeting a cold session brings it back transparently, on a fresh host with its /workspace restored from cloud storage. super stop exists only to halt spend immediately; files are preserved either way.

super stop returns once the stop is accepted: billing has stopped, and the files are saved by the teardown that follows. stop --wait blocks until that teardown has settled — use it before anything that reads the saved manifest (super ls, super mount, super map --from <sid>) rather than polling super sessions yourself. It exits 1 when the wait times out, when the server records a failed final save for this stop (close_flush_incomplete, volume_commit_failed), or when the session ends failed/dead during the stop.

Preemption: restart, or live migration

Sessions run on spot capacity. Restart is on by default: on a spot notice, supercomputer flushes /workspace, gets a new host, restores the files and re-runs your command. After an unannounced host death it restores the last completed workspace sync and re-runs the command. Running processes are lost, so long jobs should save and reload their own checkpoints from /workspace or a volume.

--no-restart turns automatic recovery off: after a spot notice the session returns cold with /workspace kept and nothing re-run; after a host death it ends.

--checkpoint is an experimental opt-in: it first tries to live-migrate the running process, GPU state included, and falls back to restart if that fails. It is not available on multi-GPU SKUs and needs restart on.

Live migration suspends every process that holds GPU state, one GPU checkpoint per process, and waits for the slowest one. PyTorch DataLoader workers that are forked after your program has initialized CUDA inherit its GPU state and are suspended too. To keep them out of this step, start the workers before the first CUDA call, or use the spawn start method (DataLoader(..., multiprocessing_context="spawn"), or torch.multiprocessing.set_start_method("spawn") at program start). In our measurements on 8x L4 test machines (multi-GPU live migration is not yet available), the GPU checkpoint step took 4.54-4.64 s for DeepSpeed ZeRO-2, DeepSpeed ZeRO-3 and Megatron jobs that ran 16 GPU-holding processes (8 ranks plus 8 worker processes; 3 runs), and 2.54-2.64 s for FSDP and TRL jobs with only their 8 ranks (4 runs).

super run train.py --sku gpu_1x_h100                  # restart on (default)
super run train.py --sku gpu_1x_h100 --checkpoint     # try live migration first
super create --sku gpu_1x_l4 --no-restart             # no automatic recovery
super config set restart off                          # my default

Precedence, strongest first: the flag → SUPERCOMPUTER_RESTART / SUPERCOMPUTER_CHECKPOINT → supercomputer.json "restart" / "checkpoint" → super config set restart|checkpoint → server default (restart on, checkpoint off). The policy is fixed at create; --on <sid> keeps the session's own.

Credits

supercomputer is prepaid: you buy credit, and sessions draw it down as they run. At $0 new work is refused, running sessions are closed and queued jobs are canceled — so the balance is worth knowing before a long run.

Balance vs available. balance is what has posted to your ledger; available subtracts usage that has been metered but not yet billed. Spend decisions use available.

Auto-refill charges a saved card when the balance falls below your threshold. It only fires when it is armed — enabled, consented to and backed by a saved card — so super credits reports armed rather than just on/off, and says which of those is missing. Turning it off warns that work stops at $0 and needs a confirmation.

Consent comes from a purchase made with --autorefill, and from nothing else: buying without the flag never enrols you. What triggers a top-up is the balance a purchase leaves behind, not its size, and the top-up is large enough to clear the threshold — so buying $10 against a $200 threshold charges the card again for the difference. super credits buy --autorefill works that out and names the amount before anything is charged.

super credits buy opens a Stripe checkout page in your browser and waits for the payment to post; the card never passes through the CLI. On a machine with no browser the URL is printed to paste elsewhere.

Running out

A command refused for want of credit exits 4 and names the fix. It is not retryable — the same refusal repeats until credit lands (about a minute after it posts). Do not confuse it with exit 3 (a failed payment suspending the account) or exit 75 (a transient blip, which is worth retrying).

super exec --sku gpu_1x_l4 python3 train.py
# Out of credits: insufficient credit: your prepaid credit is exhausted...
# Add credit with `super credits buy 25`, or let a saved card top you up
# with `super credits autorefill on`.
echo $?   # 4

Before provisioning, the CLI warns once when the balance is low and nothing will top it up. The warning goes to stderr and never blocks the run.

Files

download uses the live host when the session is active (freshest bytes) and falls back to the saved manifest otherwise. ls and mount read the manifest the host writes when the session stops — use them after super stop, the common "grab my outputs later" case.

A stopped session's durable logs appear under a virtual _logs/ directory:

super ls s-abc123 _logs                  # build.log, session.log, exec-<pid>.log, ...
super download s-abc123 _logs/build.log  # readable long after the session is gone

mount uses rclone's NFS mount (brew install rclone) — no macFUSE or kernel extension — and streams bytes directly from cloud storage. The mountpoint must not exist yet; Ctrl-C unmounts.

Volumes

Named, manifest-backed folders that move data between sessions — mount with --volume NAME[:MOUNT] on exec, run, shell, spawn, job run, and map. Full guide: Volumes.

super volume create checkpoints
super exec --sku gpu_1x_l4 --volume checkpoints:/workspace/ckpt python train.py
super volume files checkpoints           # committed when the session detached
super volume download checkpoints model.pt

Subcommands: create · list · files · download [-r] · cat · delete · import.

Batch

Run-to-completion jobs and durable fan-outs. Full guide: Batch: jobs & sweeps.

super job run --sku gpu_1x_l4 --volume results -- python train.py
super map --sku gpu_1x_l4 -- python train.py --lr {lr} ::: lr=1e-4,3e-4
super sweeps                  # list sweeps
super sweep status <name>     # counts + failures clustered by error

SSH & tunnels

super shell is the supercomputer-native PTY path — no SSH server required. super ssh <sid> uses your local OpenSSH client over super tunnel; if the image lacks sshd, the CLI bootstraps it on first connect (tens of seconds — bake openssh-server into the image to skip that). super tunnel <sid> pipes its own stdin/stdout to a TCP port inside the session — the SSH port (2222) by default — for use as a ProxyCommand. It does not open a local port. To reach a service in the session from your machine, forward it over SSH; extra arguments to super ssh are passed through to ssh:

ssh -o ProxyCommand="super tunnel %h" root@s-abc123
super ssh s-abc123 -N -L 8000:localhost:8000   # e.g. a vLLM server on localhost:8000

Project config (supercomputer.json)

Drop an supercomputer.json in your project root (auto-discovered by walking up from cwd) to set defaults so you can skip the flags:

{
  "sku": "gpu_1x_l4",
  "volumes": [{ "name": "checkpoints", "mount": "/workspace/checkpoints" }],
  "image": {
    "base": "nvidia/cuda:12.8.1-devel-ubuntu24.04",
    "apt": ["git", "build-essential"],
    "pip": ["torch", "transformers"],
    "env": { "PYTHONUNBUFFERED": "1" }
  }
}

Explicit --sku overrides the file; --volume flags merge with (and re-map by name) the volumes defaults. Images are content-addressed — same config, same cache, no rebuild.

Help

super help            # grouped command list, concepts, recipes
super help <command>  # full flags and semantics for one command