CH·GGuides

Certified Image & Environments

The GPU.ai Certified Image: digest-pinned frameworks, driver floors, and the launch environment picker.

GPU.ai aggregates GPU capacity from many providers. Those providers ship different base images, drivers, and CUDA toolkits — so the *same* GPU can behave differently depending on where it happens to launch. The GPU.ai Certified Image is our answer to that: one normalized, digest-pinned environment that runs identically across every provider that can host it.

When you launch the GPU.ai Certified Image you get the same image digest, the same CUDA generation, and a guaranteed-minimum NVIDIA driver — regardless of which underlying provider fulfilled the capacity. Your code sees one environment, not a dozen.

The three launch environments

Every offering in the catalog belongs to one of three launch environments. You choose per launch:

Environment	What you get	When it's available
GPU.ai Certified Image	The one normalized, digest-pinned environment. Same image, CUDA, and driver floor everywhere. Comes as a bare base or as a framework environment (PyTorch, CUDA devel, JupyterLab).	Certified-capable machines only.
VM · root access	A plain VM we bootstrap for you with full root access. Bring your own stack.	VM-class capacity.
provider template	The provider's own runtime template. Launches without the GPU.ai Certified Image.	Container-native or otherwise non-normalizable capacity.

Choosing an environment

In the dashboard. The cloud catalog has an Environment filter (Certified / VM · root access / provider template) and a per-row badge showing the deployment class (VM or Container). The launch dialog only offers the environments a given machine can honor; picking a non-normalizable machine surfaces a warning that it will launch without the GPU.ai Certified Image.

In the CLI.

# Find machines that can run the GPU.ai Certified Image
gpu pricing --certified

# Narrow to a deployment class
gpu pricing --type container
gpu pricing --type vm

# Launch the Certified Image
gpu instances create -t rtx_pro_6000_blackwell --environment certified

# Launch a raw VM with root access instead
gpu instances create -t h100_sxm --environment raw-vm

See gpu pricing and gpu instances create for the full flag reference.

In the API. Pass environment (certified, certified:, certified:@, raw_vm, raw_vm:, or provider_template) on POST /v1/instances — GET /v1/environments (unauthenticated) lists every framework, version, and OS you can pass. The value is re-validated server-side against the live catalog; if no offering of the requested GPU type can honor it, the launch is rejected with a 422 environment_unavailable problem+json — for example *"this machine is container-native — root VM access isn't available"* or *"this provider launches from its own template; the GPU.ai Certified Image isn't available"*. GPU.ai never silently substitutes a different environment than the one you asked for.

Framework environments

The certified base image is deliberately lean: Python 3, pip, git, and SSH on the NVIDIA CUDA runtime base — no ML frameworks, and no CUDA compiler. Framework environments are digest-pinned certified images that ship the most-used stacks ready to go, with every certified guarantee (driver floors, digest pins, capability gating) unchanged:

Framework	Wire value	What's inside
PyTorch (latest)	`certified:pytorch`	Latest PyTorch + torchvision with CUDA-generation-matched wheels, plus JupyterLab.
CUDA devel (nvcc)	`certified:cuda-devel`	The CUDA compiler toolchain — `nvcc`, headers, dev libraries. Use this to JIT-compile extensions (DeepGEMM, FlashInfer, custom torch ops) that can't build on the runtime-only base.
JupyterLab (minimal)	`certified:jupyter`	JupyterLab on the lean base — bring your own frameworks.
Bare base	`certified`	The lean certified image itself.

In the dashboard, the launch dialog's Environment section is a row of logo cards — PyTorch, CUDA, Jupyter, bare base, plus VM (root access) and the provider's own template where the machine supports them. Options the selected region can't serve stay visible but disabled (clicking one tells you whether another region has it); the selected card expands a "What's included" panel with the published contract, and framework picks offer an inline Set as default (Settings → Marketplace preferences has the same control). In the CLI, pass the wire value to --environment (e.g. gpu instances create -t h100_sxm --environment certified:pytorch).

Each framework is published per CUDA base family, so the exact package versions track the machine's CUDA generation (e.g. Blackwell machines get cu128 PyTorch wheels). A framework that isn't published for the selected machine is rejected synchronously with 422 environment_unavailable — never silently swapped for the bare base.

Picking a framework version

Where a framework publishes more than one build for a machine's CUDA generation, you can pin the exact one with certified:@ — e.g. certified:pytorch@2.13, certified:jupyter@cuda12.4, or certified:cuda-devel@12.8. Versions are CUDA-generation-specific (the GPU fixes the CUDA variant, which fixes the compatible wheel set), so a version only launches on GPUs it was built for; a bare certified: uses the default build for the placed machine. The dashboard shows a Version dropdown when a machine offers more than one; otherwise the single build is shown as info. List the versions per framework with gpu environments or GET /v1/environments.

Picking a raw-VM operating system

A raw_vm launch boots the provider's default OS unless you name one with raw_vm: — e.g. raw_vm:ubuntu-24.04 (CLI spelling raw-vm:ubuntu-24.04). The OS catalog is server-controlled (customer-safe labels only; never a provider's internal image name), and the -cuda variants ship the NVIDIA driver preinstalled. The dashboard shows an Operating system dropdown when the machine publishes a catalog; an OS a given machine can't boot is rejected with 422 environment_unavailable. List the OS options with gpu environments or GET /v1/environments.

The published environment contract

For every certified-capable machine, GPU.ai publishes the exact environment contract you'll get. These fields appear as the environment object on each gpu pricing --output json row (and as a footnote under Certified environment (pinned per machine): in table view):

Field	Meaning
`image`	The human-readable Certified Image reference (tag form for display).
`image_digest`	The exact `sha256:` digest the launch path actually pins.
`driver_min`	The minimum NVIDIA driver the machine is guaranteed to have, e.g. `570.26`.
`cuda`	The CUDA toolkit generation, e.g. `12.8`.

Why digest pinning matters

A tag like base-cuda128 can be re-pushed to point at new bits at any time. A digest (sha256:…) can't — it names one exact, immutable image. By pinning the launch to the digest, GPU.ai guarantees that "certified" means the same bytes every time, on every provider. A tag tells you roughly what you're getting; the digest is the actual contract. That's why the Certified Image is launched by digest, never by a floating tag.

The Certified Image is built and published on the

ghcr.io/gpuai-dev/base-cuda128 and ghcr.io/gpuai-dev/base-cuda124 tag

lines (CUDA 12.8 and 12.4 respectively). Refer to the published

image_digest on each catalog row for the exact pinned digest — not the tag.

Driver and CUDA floors per GPU generation

Newer GPU generations require newer drivers and CUDA toolkits. GPU.ai maps each GPU to a floor and only marks a machine certified-capable when the guaranteed driver clears that floor. The most notable current floor:

GPU generation	Minimum driver	CUDA
RTX PRO 6000 Blackwell	570.26	12.8

Blackwell-class silicon simply won't run on older drivers, so an RTX PRO 6000 Blackwell offering is only offered as certified when the driver is at least 570.26 and the toolkit is CUDA 12.8. Older generations map to the CUDA 12.4 line. The driver_min and cuda fields on each row tell you exactly what a given machine guarantees.

The honest caveat: provider-template machines

Not every machine can be normalized. Some capacity is container-native or launches from a provider's own runtime template that we can't replace with the Certified Image. For those provider template machines, your instance launches *without* the GPU.ai Certified Image — you get the provider's environment, not ours.

This is surfaced up front, not hidden: the dashboard shows a launch warning, the CLI's ENV column labels these rows provider-template, and an API launch that asks for certified on such a machine is rejected with the 422 above rather than quietly downgraded. If you need the guaranteed environment, filter to certified-capable machines first (gpu pricing --certified).

Exact-offering pinning

If you pin a launch to one exact offering with gpu instances create --offering-id (or offering_id in the API) and that specific offering is no longer available at launch time, the launch fails with an explicit error — *"selected machine is no longer available — pick another offering"* — and is never silently swapped for a different, possibly pricier offering. You always get the machine you asked for, or a clear error.