Python SDK

Everything the CLI does is available programmatically. The SDK is the right tool when GPU work is embedded in a larger program — a training harness, an agent loop, a pipeline.

Installation

pip install gpu-compute-provider

The package is gpu-compute-provider; import it as supercomputer.

Authentication

Authenticate once via the CLI (super login, or super set_token with an existing key), or pass a key explicitly:

import supercomputer

client = supercomputer.Client()                      # uses the saved token / env var
client = supercomputer.Client(api_key="super_sk_...") # explicit

Key resolution order: Client(api_key=...) → SUPERCOMPUTER_API_KEY env var → saved token in ~/.supercomputer/token → SUPERCOMPUTER_API_KEY from the nearest .env.

Session-based workflow

Sessions persist state across commands. Use the context manager so the session closes (and stops spending) even on exceptions:

import supercomputer

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

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

    weights = s.download("model.pt")     # bytes
    open("model.pt", "wb").write(weights)

Commands run from /workspace — the same place upload puts files — so uploaded scripts run by relative path.

Custom images

Declare the environment once; layers are content-addressed, so the same spec is a cache hit and is not rebuilt:

from supercomputer import Image

image = (
    Image.from_registry("nvidia/cuda:12.8.1-devel-ubuntu24.04")
    .apt_install(["git", "build-essential"])
    .pip_install(["torch", "transformers"])
    .env({"PYTHONUNBUFFERED": "1"})
)
project = client.project("my-experiment", image=image)

Image.debian_slim() is the lightweight default; named images like Image.from_name("agent-gpu") ship a pinned GPU training stack (torch, transformers, flash-attn, vLLM).

Background processes

Start long-running work without blocking:

with project.session(sku="gpu_1x_l4") as s:
    proc = s.spawn(["python", "train.py", "--epochs=100"])
    proc.poll()        # refresh status
    print(proc.output) # read output so far
    proc.wait()        # block until done
    print(proc.exit_code)

Stream output live with s.watch(proc) — see Logs & streaming.

Session lifecycle

Sessions are cold ($0, no host) until first used, then hot while running. A cold session comes back online automatically the next time you target it — there is no explicit resume step. s.close() (or super stop from the CLI) returns it to cold and halts spend; /workspace is preserved either way.

with project.session(sku="gpu_1x_l4") as s:
    s.run(["python", "train.py"])
    sid = s.session_id

# Later — even days later, on a fresh host, files restored:
s2 = client.attach_session(sid)
s2.run(["ls", "/workspace/"])        # original files are here
s2.close()

When a spot host is reclaimed, the session restarts by default: /workspace is restored on a new host and the command re-runs; running processes are lost. restart=False turns automatic recovery off. checkpoint=True is an experimental opt-in that first tries to live-migrate the running process (single-GPU SKUs only). None (the default for both) defers to the SUPERCOMPUTER_RESTART / SUPERCOMPUTER_CHECKPOINT env vars, supercomputer.json, then super config.

with project.session(sku="gpu_1x_h100") as s:
    s.run(["python", "train.py", "--resume-from", "/workspace/ckpt"])

Jobs and sweeps

For run-to-completion batch work, project.job(...) runs a command on an ephemeral session (no saved filesystem; outputs go to volumes), and client.map(...) fans a command out over argument bindings as a durable sweep. See Batch: jobs & sweeps for both.

Volumes

client.list_volume_files("results")                       # [{path, size, ...}]
data = client.read_volume_file("results", "model.pt")     # bytes, no session
client.download_volume_file("results", "model.pt", "./model.pt")
client.delete_volume("results")

Mount into a session at creation with volume_mounts=[{"name": ..., "mount_path": ...}] — semantics match the CLI's --volume (Volumes).

Mixing CLI and SDK

Both talk to the same sessions. A common pattern: provision and iterate from the CLI, then follow the work programmatically (or vice versa) — any session id printed by super create works with client.attach_session(sid), and any SDK session shows up in super sessions.