Prime Images

What are Prime Images?

Prime Images lets you push custom Docker images to Prime’s registry and use them in sandboxes. Builds happen in the cloud, so you don’t need Docker running locally.

Image references

When you create a sandbox, the image reference resolves in this order:

Prime Images — references that start with prime/, like prime/<username>/<image>:<tag>, prime/<team-slug>/<image>:<tag>, or the id forms (prime/<userId>/<image>:<tag>, prime/team-<teamId>/<image>:<tag>), resolve to a Prime Image you can access: your own, your team’s, or one that’s been published.
Docker Hub — any other reference with no registry host and no prime/ prefix resolves as a Docker Hub image, so official images like ubuntu:22.04 or pytorch/pytorch:latest work as usual.
Other public registries — references hosted on registries like ghcr.io or quay.io are not accepted directly. Transfer the image into Prime first with prime images push --source-image, then reference the resulting prime/ image.

Push an Image

# Basic push (uses ./Dockerfile in current directory)
prime images push myapp:v1.0.0

# Make the image public when the build completes
prime images push myapp:v1.0.0 --public

# Specify a different Dockerfile
prime images push myapp:v1.0.0 --dockerfile custom.Dockerfile

# Use a different build context
prime images push myapp:v1.0.0 --context ./app

# Copy existing public images into Prime's registry
prime images push --source-image ubuntu:22.04,ghcr.io/org/app:v1

# Copy and rename the destination tag
prime images push myubuntu:22.04 --source-image quay.io/org/ubuntu:22.04

The CLI packages your build context, uploads it, and kicks off a remote build. You’ll get a build ID to track progress. Use --source-image to transfer public images from Docker Hub, GHCR, Quay, public ECR, registry.k8s.io, or MCR without building from a Dockerfile. Pass several at once as a comma-separated list. Google-hosted registries are rejected.

Private registries

Pass registry credentials to pull a private --source-image or private FROM base images in your Dockerfile. Prime forwards the credentials to that build only and does not store them.

# Private source image (password or token from the environment)
export PRIME_REGISTRY_PASSWORD=<token>
prime images push myapp:v1 --source-image ghcr.io/acme/app:v1 \
  --registry-server ghcr.io --registry-username <user>

# Dockerfile whose FROM image is private (prompts for the password)
prime images push myapp:v1 --registry-server docker.io --registry-username <user>

Use a short-lived, read-only token (for example a fine-grained GitHub token with read:packages, or a Docker Hub read-only access token) rather than your account password. Pass it through PRIME_REGISTRY_PASSWORD or the prompt instead of --registry-password, which is visible in shell history and process listings. Source images still need to be hosted on one of the registries listed above. Dockerfile base images can come from any registry. Private Docker Hub sources become your own image (or your team’s) instead of a public platform image. Each build accepts one set of credentials. When the push completes, the CLI prints the full image reference to use when creating a sandbox. Prime Image references always start with prime/. By default this uses your unique slug — your username for personal images, or the team slug when you’re in a team context:

prime/<your-username>/myapp:v1.0.0      # personal
prime/<team-slug>/myapp:v1.0.0          # team

If you haven’t set a username (or your team has no slug yet), the reference falls back to the id form — prime/<userId>/myapp:v1.0.0 or prime/team-<teamId>/myapp:v1.0.0. Run prime images list to see the exact reference for each image.

Check Build Status

# See all your images and their build status
prime images list

Status meanings:

PENDING – Queued for build
UPLOADING – Build context is being uploaded
BUILDING – Build in progress
COMPLETED – Build succeeded, image is usable
FAILED – Build failed (check your Dockerfile)
CANCELLED – Build was cancelled

Use Your Image

Once the status shows COMPLETED, create a sandbox with it:

# Personal image
prime sandbox create prime/<your-username>/myapp:v1.0.0 --cpu-cores 2 --memory-gb 4

# Team image
prime sandbox create prime/<team-slug>/myapp:v1.0.0 --cpu-cores 2 --memory-gb 4

Push Many Images at Once

prime images push-bulk builds many images in one command. Builds come from a JSONL manifest (--manifest), a Harbor tasks directory (--harbor), or a Hugging Face dataset (--hf):

# JSONL manifest: Dockerfile builds and public-registry source builds, one per line
prime images push-bulk --manifest builds.jsonl

# Harbor task directory (each task's environment/ folder is the build context)
prime images push-bulk --harbor ./tasks --tag latest

# Hugging Face dataset: one Dockerfile per row, names from a column
prime images push-bulk --hf org/dataset --dockerfile-column dockerfile --name-column instance_id

# Hugging Face dataset: one registry image reference per row
prime images push-bulk --hf org/dataset --column docker_image

Manifest lines are either Dockerfile builds:

{"image": "myapp:v1.0.0", "context": "./app", "dockerfile": "Dockerfile.prod"}

or public-registry source builds:

{"source": "ghcr.io/org/app:v1", "image": "myapp:v1.0.0"}

Useful flags:

--public / --private – set visibility for the built images
--concurrency – how many builds run in flight at once
--build-timeout – seconds to wait for a single build
--dry-run – resolve and print the build list without pushing
--failures-out – where to write a re-runnable manifest of failed builds (default push-bulk-failures.jsonl)

Failed builds are written to the --failures-out manifest so you can re-run just the failures.

Update an Image

prime images update renames an image, changes its tag or visibility, or moves it between scopes. The image contents do not move — the old reference stops resolving and the new reference points at the same stored artifacts.

# Rename
prime images update myapp:v1 --name myapp-final

# Change the tag
prime images update myapp:v1 --tag v2

# Change visibility
prime images update myapp:v1 --public

# Move a personal image into a team
prime images update myapp:v1 --to-team team_a

Add --dry-run to preview the change without applying it, and --yes to skip the confirmation prompt.

VM Images

Sandboxes are microVMs, so they boot a VM image rather than a container image. You still define images the normal way — build from a Dockerfile with prime images push, and the VM image builds automatically. The first time a given image is launched, Prime converts it into a VM image. The sandbox sits in PENDING while that runs, which can take a few minutes; later sandboxes from the same image start normally. A --source-image push also builds the VM image during the push, so the first sandbox launch from it starts right away.

Publish or Unpublish an Image

Images are private by default. Publishing an image lets other authenticated Prime users use it in sandboxes with the prime/ reference shown by prime images list.

prime images publish myapp:v1.0.0
prime images unpublish myapp:v1.0.0

Delete an Image

prime images delete myapp:v1.0.0

# Skip confirmation
prime images delete myapp:v1.0.0 --yes

Getting Started

Inference

Model Factory

Community

Compute

Traces

Libraries

What are Prime Images?

Image references

Push an Image

Private registries

Check Build Status

Use Your Image

Push Many Images at Once

Update an Image

VM Images

Publish or Unpublish an Image

Delete an Image

​What are Prime Images?

​Image references

​Push an Image

​Private registries

​Check Build Status

​Use Your Image

​Push Many Images at Once

​Update an Image

​VM Images

​Publish or Unpublish an Image

​Delete an Image

What are Prime Images?

Image references

Push an Image

Private registries

Check Build Status

Use Your Image

Push Many Images at Once

Update an Image

VM Images

Publish or Unpublish an Image

Delete an Image