Register and manage an image

Browse all recipes

Reuse an image across sandboxes by registering it with Docker Cloud Sandboxes. Registration creates an image record and a temporary upload destination. You must push the image content separately with an OCI-compatible registry client.

Start with an authenticated client and a built image. If you already have an image in a registry, run it directly instead.

Register an upload destination

Choose a display name, startup command, CPU and memory preferences, and an idempotency key. The returned image includes its resource name and a push target.

Use the target's registry reference and temporary credential to push your image. Keep that credential private and finish before it expires. Save the target from the initial response: later image reads do not issue a replacement upload credential.

This example registers the destination. It does not build or push image content.

return client.images.create(
  { displayName: name, fromImage: { resources }, startCmd },
  { idempotencyKey: requestId },
);

import type {
  ClientImagesCreateOptions,
  Sandboxes,
} from '@docker/sandboxes';

export async function createImage(
  client: Sandboxes,
  name: string,
  startCmd: string[],
  resources: Extract<
    ClientImagesCreateOptions,
    { fromImage: unknown }
  >['fromImage']['resources'],
  requestId: string,
) {
  return client.images.create(
    { displayName: name, fromImage: { resources }, startCmd },
    { idempotencyKey: requestId },
  );
}

Check preparation status

After the push finishes, read the image by its resource name. A COMPLETED status means it is ready to use. WAITING_FOR_PUSH means content has not arrived, PREPARING means preparation is in progress, and FAILED includes failure details.

The example performs one read. If preparation is still in progress, repeat the read with a delay and deadline. Repeating creation would register another image rather than advance this one.

return client.images.get(name);

import type { Sandboxes } from '@docker/sandboxes';

export async function getImage(client: Sandboxes, name: string) {
  return client.images.get(name);
}

Find registered images

List images with an optional filter, such as status=completed. The example follows all pages. List entries are summaries; get the image by name when you need its complete record.

return client.images.all({ filter }).collect();

import type { Sandboxes } from '@docker/sandboxes';

export async function listImages(client: Sandboxes, filter: string) {
  return client.images.all({ filter }).collect();
}

Remove an image

Read the image and delete through its handle. The SDK supplies its name and version to protect against deleting a newer record you have not read.

Keep images that future sandbox creations still depend on. Deleting an already absent image is safe for cleanup.

await image.delete();

import type { Image } from '@docker/sandboxes';

export async function deleteImage(image: Image) {
  await image.delete();
}