Use your own image

sb = nv.sandboxes.create(image="ghcr.io/org/app:tag", cpus=4, memory_mb=4096)
nv.registries.put(host="ghcr.io", username="me", password="<token>")   # private pulls, stored once
t = nv.templates.build("python:3.12-slim", cpus=2, memory_mb=1024)     # pre-build to skip first-use wait
sb = nv.sandboxes.create(image="docker:28-dind", runtime="vm")         # the image IS the machine (experimental)

The first create of an image at a shape builds a template once (seconds for small images, minutes for huge ones); the SDK waits by default (wait_for_template=False raises TemplateBuildingError to poll yourself). After that it is fast for everyone (public images) or your org (private ones).

Sharp edges

Templates are per (image, cpus, memory_mb, runtime). In the vm runtime don’t start a second dockerd on dind images — the image’s own daemon already holds the socket. Omitting the image gives the default sandbox (Python 3.12, Node 22, common data-science stack, 2 vCPU/1 GiB, ~50–100 ms from a warm pool); it sets PIP_NO_CACHE_DIR=1, so repeated installs in one sandbox want PIP_NO_CACHE_DIR=0 pip install ….

Getting Started

Guides

Concepts

Reference

Use your own image

Sharp edges

​Sharp edges

Sharp edges