Python

Reference for the Python SDK's core objects. For raw HTTP, see the HTTP API. For the command-line interface, see the CLI Reference.

Client

The main entry point for the supercomputer SDK.

import supercomputer

client = supercomputer.Client()
# or with an explicit API key
client = supercomputer.Client(api_key="super_sk_...")

Methods

client.project(name, image=None)

Get or create a project

client.attach_session(sid)

Attach to an existing session by id

client.map(command, args=...)

Fan a command out as a durable sweep (details)

client.list_volume_files(name)

List files in a volume

client.read_volume_file(name, path)

Read a volume file (returns bytes)

client.download_volume_file(name, path, local)

Download a volume file

client.delete_volume(name)

Delete a volume

client.health()

Check dispatcher connectivity

Project

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

Methods

project.session(sku)

Create a session (usable as a context manager)

project.job(command, sku=..., volume_mounts=..., include=..., retries=...)

Run an ephemeral job (details)

Retrying session creation

project.session(..., idempotency_key=key) and project.cold_session(..., idempotency_key=key) accept a caller-owned key; the equivalent Client create methods accept it too. Without one, the SDK generates a UUID4 for each logical create and retains it through that POST's retries. An ambiguous-create error carries idempotency_key: retry the same request with that key. After learning the SID, poll or reconnect that SID. A deliberate new session needs a new key.

HTTP POST /v1/sessions accepts an optional Idempotency-Key header. Its value must be 1–255 visible ASCII bytes, excluding spaces and commas; send it once. An empty, repeated, or invalid value returns 400 invalid_idempotency_key. Omitting the header preserves keyless create behavior.

A key belongs to the authenticated user, including across API-key rotation. It binds the accepted typed allocation request to one session for the session row's lifetime, including closed, dead, failed and retired rows. The same key and request return that SID with current readiness: 202 for queued/allocating, 200 for ready or cold/terminal identity. A ready reply mints a fresh token for the current placement. A different accepted request returns 409 idempotency_key_conflict; a binding read failure returns 500 session_create_key_lookup, never an unbound-key result. No key TTL applies. The key and hash are internal metadata and are absent from session JSON.

Replaying a terminal session does not resume or replace it. Hot SDK creates raise session_create_already_ended (the message names the session) with idempotency_key when the existing session has ended. Use a new key to request a replacement. Cold creates return the existing filesystem identity.

SDK retries are scoped to this create POST; other POST endpoints keep their existing policy. The create exchange uses the caller's timeout_s when provided, otherwise its existing 30-second HTTP budget; SID polling retains its queue/dispatcher deadline behavior.

Session

with project.session(sku="gpu_1x_l4") as s:
    ...
# or manage the lifecycle yourself and call s.close()

Methods

s.run(cmd)

Run a command and wait for completion

s.spawn(cmd)

Start a background process

s.watch(proc)

Stream real-time output from a spawned process

s.logs(pid, output_range=..., stream=...)

Fetch a process's durable log

s.upload(local, remote)

Upload local files to the session

s.download(remote)

Download a file from the session (returns bytes)

s.session_id

The session's id (s-...), usable from the CLI too

s.close()

Close the session and release the GPU host

Process

Returned by s.spawn().

proc.poll()

Refresh status

proc.wait()

Block until the process completes

proc.output

Read process output

proc.status

Current status (running, ...)

proc.exit_code

Exit code once terminated