# supercomputer

> The compute market for agents. Coding agents and the people who run them rent GPUs by the
> second from a prepaid balance: start a session, run the work, stop it.
> https://supercomputer.sh

## Quick start

```bash
curl -fsSL https://supercomputer.sh/install.sh | sh   # installs the CLI + SDK, signs you in, adds agent skills
super exec --sku gpu_1x_l4 nvidia-smi
```

Or with your own Python: `pip install gpu-compute-provider && super login` (the PyPI package
named `supercomputer` is a placeholder; import the SDK as `supercomputer`). Agents and CI with an
existing key: `super set_token super_sk_...` or set `SUPERCOMPUTER_API_KEY`.
Install the agent skill for the coding agents on this machine with `super setup --agents all`.

## How it works

- **Session**: a persistent `/workspace` plus environment, not a held machine. It is `cold`
  ($0, no host) until its first command, `hot` while running, `warm` when idle but still holding
  a host (billed), and stops on `super stop` or by itself after 5 idle minutes. The next command
  brings it back, on a new host if needed, with `/workspace` restored.
- **Job**: one command run to completion (`super job run`); keeps its exit code, logs and any
  volume writes, not its working files.
- **Sweep**: one command fanned out over argument bindings (`super map`), queued and retried
  server-side; `super sweep status` and `super sweep harvest` to follow and collect.
- **Volume**: named storage you mount into sessions and jobs (`super volume`).
- **SKU**: the hardware, `gpu_{count}x_{model}`, e.g. `gpu_1x_h100`, `gpu_8x_b200`. List with
  `super skus`.

## Billing

- GPU time is billed by the second while a host is attached to your session; a cold session
  costs nothing for compute. Files kept by sessions and volumes are billed as storage.
- Credit is prepaid. At $0, new work is refused and running sessions are closed (files kept).
  A refused command exits with code 4 and names the fix.
- Auto-refill is off unless you turn it on (`super credits autorefill`), and has a daily cap.
- `super credits` shows the balance; `super credits statement` lists every charge.

## GPUs

| Family | Memory per GPU | Sizes (GPUs per machine) |
|---|---|---|
| H100 | 80 GB | 1, 8 |
| H200 | 141 GB | 1, 8 |
| B200 | 180 GB | 1, 8 |
| A100 80GB | 80 GB | 8 |
| RTX PRO 6000 Blackwell | 96 GB | 1, 2, 4, 8 |
| L40S | 48 GB | 1, 4 |
| L4 | 24 GB | 1, 4, 8 |
| A10G | 24 GB | 1, 4 |
| T4 | 16 GB | 1, 4, 8 |

SKU names follow the table: `gpu_1x_l4`, `gpu_4x_l40s`, `gpu_8x_h200`, `gpu_2x_rtx_pro_6000`.
CPU only: `cpu_generic`. Current rates are on the dashboard and via `super skus`.

## ChatGPT and other MCP clients

supercomputer is also an MCP server at `https://supercomputer.sh/mcp` (Streamable HTTP, OAuth).
Add it as a custom connector in your assistant (ChatGPT developer mode, any MCP client); sign in, add
credits, allow. Tools: `list_gpus`, `get_balance`, `run`, `get_job`, `job_logs`, `list_jobs`,
`cancel_job`, `buy_credits`. Guide: https://supercomputer.sh/docs/guides/mcp

## CLI

```bash
super create --sku gpu_1x_h100           # create a session (cold: $0 until used)
super exec --on s-abc123 python train.py # run a command in it
super run train.py --sku gpu_1x_l4       # upload and run a file on a fresh session
super spawn --on s-abc123 python serve.py # background process; prints a process id
super logs s-abc123 proc-1 --follow      # durable logs; super wait / super kill
super upload s-abc123 ./data             # files in; super download / ls / mount out
super shell s-abc123                     # interactive shell; super ssh / tunnel
super stop s-abc123                      # stop: GPU billing ends, files are kept
super sessions --all                     # list sessions; super history <sid>
super job run --sku gpu_1x_l4 -- python eval.py
super map --sku gpu_1x_l4 -- python train.py --lr {lr} ::: lr=1e-4,3e-4
```

Add `--json` for machine-readable output. Exit codes: 0 ok, 3 payment failed, 4 out of credit,
75 transient (safe to retry).

## Python SDK

```python
import supercomputer

client = supercomputer.Client()          # reads SUPERCOMPUTER_API_KEY or ~/.supercomputer
project = client.project("my-experiment")

with project.session(sku="gpu_1x_h100") as s:
    s.upload("./data", "data/")
    s.run(["pip", "install", "transformers"])   # state persists across commands
    result = s.run(["python", "train.py"])
    print(result.stdout)
```

Porting from Modal: most scripts run with `import supercomputer as modal`.

## Links

- Quickstart: https://supercomputer.sh/docs/quickstart
- CLI reference: https://supercomputer.sh/docs/guides/cli
- Python SDK: https://supercomputer.sh/docs/guides/python-sdk
- Batch jobs and sweeps: https://supercomputer.sh/docs/guides/batch
- Sessions: https://supercomputer.sh/docs/concepts/sessions
- GPUs and SKUs: https://supercomputer.sh/docs/concepts/skus
- Dashboard: https://supercomputer.sh/dashboard