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.

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. 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

VM sandboxes are the default runtime, and 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

Lab

Libraries

Compute

What are Prime Images?

Push an Image

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?

​Push an Image

​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?

Push an Image

Check Build Status

Use Your Image

Push Many Images at Once

Update an Image

VM Images

Publish or Unpublish an Image

Delete an Image