Run your own container image

Browse all recipes

Run your own tools from a container image when a bundled kit does not fit the task. You supply the image reference and machine size; the SDK creates an isolated sandbox around it.

You need an authenticated client and an OCI image the service can pull. Use a versioned reference or digest when repeatability matters. The image must include /bin/sh.

Create from a registry image

Pass the image reference, CPU count, memory size, display name, and idempotency key. The SDK's image-reference option avoids assembling nested request fields. Do not also supply a managed image or named agent.

The example waits for the sandbox to run. A wait timeout stops your wait; it does not delete a sandbox that was already accepted. Save any sandbox handle retained by the error so you can inspect or clean it up.

The image's startup command runs inside the sandbox. Read WORKSPACE_DIR to find the workspace rather than assuming a path.

Next, run a command or copy in your project files. Delete the sandbox when the work is complete.

const sandbox = await client.create(
  { displayName: name, imageRef, resources },
  { timeoutMs: 300_000, idempotencyKey: requestId },
);
return sandbox.waitUntilRunning();

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

export async function createFromImageRef(
  client: Sandboxes,
  name: string,
  imageRef: string,
  resources: ClientCreateOptions['resources'],
  requestId: string,
) {
  const sandbox = await client.create(
    { displayName: name, imageRef, resources },
    { timeoutMs: 300_000, idempotencyKey: requestId },
  );
  return sandbox.waitUntilRunning();
}