Projects & Config
Organize workloads and set per-project defaults.
Project config (supercomputer.json)
For CLI workflows, a project is a directory with an supercomputer.json in its root.
The CLI auto-discovers it by walking up from your current directory (like
.env), and every super exec/run in that tree picks up its defaults:
{
"sku": "gpu_1x_l4",
"volumes": [{ "name": "checkpoints", "mount": "/workspace/checkpoints" }],
"image": {
"base": "nvidia/cuda:12.8.1-devel-ubuntu24.04",
"apt": ["git", "build-essential", "ninja-build"],
"pip": ["torch", "triton", "transformers"],
"env": { "PYTHONUNBUFFERED": "1" },
"run": ["echo setup-complete"]
}
}All fields are optional. Explicit --sku flags override the file; --volume
flags merge with (and re-map by name) the volumes defaults.
| Field | Description |
|---|---|
sku | Default hardware SKU for exec and run |
volumes | Volumes auto-attached to every session. Each entry is "name", "name:/mount", or {"name": ..., "mount": ...} |
image.base | Base image. An image section without base starts from python:3.11-slim, not from the SKU default, so a GPU SKU gets no torch unless image.pip adds it |
image.apt | Packages to apt-get install |
image.pip | Packages to pip install |
image.env | Environment variables baked into the image |
image.run | Shell commands to run during build |
When supercomputer.json is present, super exec and super run automatically
build the specified image. Images are cached by content hash — same config,
no rebuild; a changed config triggers one rebuild (30–120s) on first run.
Projects in the SDK
In the Python SDK, a project is a logical grouping of sessions with a shared image definition — one per experiment, team, or environment. Projects are created implicitly when first referenced:
import supercomputer
from supercomputer import Image
client = supercomputer.Client()
image = Image.debian_slim().pip_install(["torch", "transformers"])
project = client.project("fine-tuning-llama", image=image)
s = project.session(sku="gpu_1x_l4")
s.run(["python", "train.py"])
s.close()For quick scratch work, use a throwaway name like _scratch.