Quickstart

Installation

curl -fsSL https://supercomputer.sh/install.sh | sh

One chain: installs the super CLI and Python SDK (from PyPI, into an isolated tool environment via uv or pipx), adds it to your shell's PATH, opens your browser to sign in with Google or email and add a card, hands the CLI its own API key, and installs the supercomputer skill for any coding agents on your machine (Claude Code, Cursor, Codex).

Re-running it is safe: an existing install is upgraded in place (or left alone if something other than uv/pipx installed it), and the sign-in is skipped when this machine already has a key. Knobs:

The installer runs in its own process, so it cannot change the PATH of the terminal you ran it in. It writes the line to your shell profile for every new terminal and prints the one command that makes the current one catch up (export PATH="$HOME/.local/bin:$PATH", or source ~/.zshrc).

Manual install

Prefer to manage Python yourself? The CLI is the gpu-compute-provider package on PyPI (Python 3.9+); it installs the super command and the supercomputer Python module. Any of these work:

uv tool install gpu-compute-provider        # isolated tool env, on PATH at ~/.local/bin
pipx install gpu-compute-provider           # same idea, via pipx
pip install gpu-compute-provider            # into the current Python environment

Then sign in — it opens your browser, and the CLI receives its own key:

super login

If super is not found afterwards, the tool's bin directory is not on your PATH yet. For uv and pipx that is ~/.local/bin:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

To teach your coding agent about supercomputer (Claude Code, Cursor, Codex):

super setup --agents all

Authentication

super login signs in through your browser: it shows a short code, opens the approval page, and saves a key minted for this machine (named cli:<hostname> in the dashboard, so one laptop can be revoked without the others). On a headless box it prints the URL and code to open from any device. Already have a key — CI, agents, a second machine?

super set_token super_sk_...
super setup --agents all     # optional: install agent skills for every agent

Verify connectivity:

super health

Add credit

supercomputer is prepaid: GPUs draw down a credit balance as they run, and at $0 new work is refused. Buy your first credit before the first run — this is also what turns auto-refill on, so you are not interrupted later.

super credits buy 25      # opens a checkout page in your browser
super credits             # balance, available, auto-refill, card

available is the number to watch: it is your balance minus usage that has been metered but not yet billed. See Credits for auto-refill and statements.

Pick a GPU SKU

GPUs are selected by SKU name (for example gpu_1x_l4 or gpu_8x_b200). List everything available with:

super skus

Or find your SKU in the browser — filter by GPU count and compare memory.

Run your first command

super exec --sku gpu_1x_l4 nvidia-smi

Target a specific SKU:

Run a script

super run uploads a file (or a directory) and runs it — no session bookkeeping required:

super run train.py --sku gpu_1x_l4

# Upload a whole directory, pick the entrypoint, pass arguments
super run . --script train.py --sku gpu_1x_l4 -- --epochs 50 --lr 1e-4

Iterate on one machine

For multi-step work, create a persistent session once and attach every command to it with --on. The session is cold — $0 — until first used, and its /workspace filesystem persists across commands:

super create --sku gpu_1x_l4              # prints s-abc123; $0 so far
super upload s-abc123 ./data
super exec --on s-abc123 pip install torch
super exec --on s-abc123 python train.py  # brings the host online
super stop s-abc123                       # spend stops, files stay
super download s-abc123 model.pt          # works after it's stopped

There is no resume command — using a stopped session again brings it back online automatically with its files restored, even days later.

Kick off something long

Don't babysit a training run in the foreground. spawn starts it in the background and prints a process id you can follow — the logs are durable, so this works even if your laptop sleeps or the job outlives your terminal:

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

Keep data that outlives any session

Sessions keep their own files, but a volume is how you share data across sessions — checkpoints written on a training box, read on an eval box, or pulled straight to your laptop with no session running at all:

super volume create checkpoints

# Train on one session, writing into the mounted volume
super exec --sku gpu_1x_l4 --volume checkpoints:/workspace/ckpt \
  -- sh -lc 'python train.py && cp model.pt /workspace/ckpt/'

# Writes commit when the session closes — then any session can mount them
super volume files checkpoints                # -> model.pt
super exec --sku gpu_1x_h100 --volume checkpoints:/workspace/ckpt \
  python eval.py --model /workspace/ckpt/model.pt

# Or pull results locally, no GPU involved
super volume download checkpoints model.pt

Inside the session a volume is just a directory — use normal file I/O. See Volumes for commit semantics and volume import.

Fan out

When one run becomes a grid, super map runs the same command across many argument bindings as a durable server-side sweep — submit, disconnect, and the service queues, retries, and records every task:

super map --name lr-sweep --sku gpu_1x_l4 \
  -- python train.py --lr {lr} ::: lr=1e-4,3e-4,1e-3

super sweep status lr-sweep                  # progress + failures by error
super sweep harvest lr-sweep '*.json' ./out  # every task's outputs

See Batch: jobs & sweeps for binding syntax, canaries, and run-to-completion jobs.

Scripting and agents: --json

Every command accepts --json for machine-readable output:

super exec --sku gpu_1x_l4 --json nvidia-smi -L
# {"stdout": "GPU 0: NVIDIA L4 ...\n", "returncode": 0, "status": "exited", ...}

Use the Python SDK

The same primitives are available programmatically:

import supercomputer

client = supercomputer.Client()
project = client.project("my-experiment")

with project.session(sku="gpu_1x_l4") as s:
    s.run(["pip", "install", "transformers"])
    result = s.run(["python", "train.py"])
    print(result.stdout)

Next steps

• CLI Reference — every command, grouped by task
• Credits — balance, auto-refill, what happens at $0
• Sessions — lifecycle, what survives a resume
• Volumes — commit semantics, imports, config defaults
• Batch: jobs & sweeps — jobs, ::: bindings, harvest
• Python SDK Guide — deep dive into the SDK