Skip to main content
An image is the bootable disk template your instance runs from. Boot from an SF Compute base image with common configurations, or upload your own custom image. Every image has an id like image_2KvMb9NpQs5 and a human-readable name like ubuntu-22.04-cuda-12.4 or training-base. Each image also has is_public, which is true for SF Compute base images and false for images you upload. A name identifies a sequence of immutable versions, starting at 1. The id always refers to one exact build, and the bits behind an id never change. Uploading an existing name creates the next version.

​
Listing images

List all images available to you, including SF Compute’s public images.
The CLI lists images outside the active workspace, including SF Compute’s public images, by their full resource path. By default the list shows one entry per name: the latest active version. Pass --all-versions to see every version with its lifecycle state, including a VERSION column.

​
Using an image

Pass an image name, ID, or resource path when creating an instance.
If you omit --image, the CLI presents an interactive picker showing all completed images available to you. Referencing an image by name resolves to the latest active version at creation time, so new instances automatically pick up updated builds. To pin one exact build, reference it by id, or append @<version> to the name.
Both pin forms mean the same thing: exactly this build, even after newer versions appear. Both may launch a version that has since been deprecated, while revoked versions never launch. Ids don’t take the suffix, since an id already names one exact build. sf images get ubuntu-jammy-custom@2 inspects a pinned version. The instance stores the concrete image id it booted from either way, so sf instances get always tells you exactly which build an instance is running.

​
Uploading an image

Upload a raw disk image with sf images upload. The CLI uploads the image in parts, reports progress as it goes, and verifies integrity with a SHA256 checksum. The maximum image size is 75 GiB. Custom images stay in your workspace.
If you omit --file or --name, the CLI prompts you interactively. Uploading a file under an existing name never overwrites anything. It creates the next version, and the name starts resolving to it once the upload completes. For large images, tune the number of parallel part uploads with --concurrency. The default is your machine’s CPU count.

​
Image requirements

SF Compute supports UEFI amd64 (x86_64) raw images. We do not support qcow2. Custom images should resize themselves at boot to fill the disk available to the instance. For an example of building a compatible image with Packer, see our example GitHub repository. Custom images must have drivers for both and for networking. They must also have cloud-init installed with its network configuration step enabled so networking comes up at boot.

​
Image lifecycle

An upload moves through started → uploading → completed (or failed). Only completed images can back instances. Completed images additionally carry a catalog state. An active image is the default state: listed, resolvable by name, and launchable. A deprecated image is no longer the active version and will eventually be removed. It stops resolving by bare name and leaves the default listing, but an explicit pin (image id or name@<version>) can still launch it, and instances already running on it are unaffected. sf images list --all-versions shows deprecated versions with status deprecated. A revoked image can no longer back new instances, by name or by id, though instances already running on it are unaffected.

​
Revoking an image

Revoke an image to stop new instances from using it. Existing instances keep running.
The command prompts for confirmation. Pass --yes to skip it. Reinstate a revoked image to make it usable again.

​
Deleting an image

Delete an image to remove it permanently. Unlike a revoked image, a deleted image cannot be reinstated. You cannot delete an image while an active instance uses it.
The command prompts for confirmation. Pass --yes to skip it.

​
SFC base images

SF Compute publishes base images named ubuntu-<lts>-cuda-<major.minor>, for example ubuntu-24.04-cuda-13.2, with no OS point releases or driver builds in the name. The matrix covers Ubuntu 22.04 and 24.04 crossed with the two newest CUDA minor versions, plus a back-catalog of older CUDA versions. sf images list shows every current name. Each base image ships the NVIDIA server driver pinned to that CUDA version’s compatibility floor, the CUDA development libraries, and cloud-init. Each name tracks its latest build. When NVIDIA ships a new CUDA patch release, or a driver or OS point release lands, SF Compute republishes the same names, and each republish appears as a new version. Instances created by name pick up the latest version automatically, while running instances keep the exact image they booted from. If your workload needs one exact build, pin it by image id or by version, like ubuntu-22.04-cuda-12.7@3. Older versions of a base image are deprecated once superseded. A deprecated version leaves name resolution and the default listing but still launches by pinned id or name@<version>. Versions deprecated for a long time are eventually revoked, which blocks new launches without touching running instances. Base image versions are never deleted.

​
API reference

See the Images API for programmatic access.