How to start a sandbox from a private registry image

Store the registry's credential once with runtime image registry set, then build from the private image and start sandboxes from it.

On Runtime the credential is sealed to the servers the moment it arrives: no call returns it, and the API that stored it cannot read it back. A build opens it only to pull, inside its own build machine, so neither your sandboxes nor your agent ever hold the registry token. Docker Hub, GitHub, Google, Amazon ECR and any other registry that takes a user name and token work (private registries, checked 25 September 2026).

Store the credential

Every CLI form reads the secret from standard input, so it never lands in your shell history or on a command line.

Terminalecho "$GHCR_TOKEN" | runtime image registry set ghcr.io --username my-userecho "$AWS_SECRET_ACCESS_KEY" | runtime image registry set 123456789012.dkr.ecr.us-east-1.amazonaws.com --access-key-id AKIA...runtime image registry ls

From code, keep the token in your own secret store and pass it through an environment variable:

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();await runtime.images.registries.set({  registry: "ghcr.io",  username: "my-user",  password: process.env.GHCR_TOKEN ?? "",});console.log(await runtime.images.registries.list()); // never the token

Pythonimport osfrom withruntime import Runtimeruntime = Runtime()runtime.images.registries.set("ghcr.io", username="my-user", password=os.environ.get("GHCR_TOKEN", ""))print(runtime.images.registries.list())

What each registry needs

An account holds up to 20 registry credentials. Remove one with runtime.images.registries.delete(registry).

Build from the private image

A sandbox starts from a Runtime image, so the private image goes through one build. Use it as it is:

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();await runtime.images.build({ name: "app", image: "ghcr.io/acme/app:1.4.2" });await using sbx = await runtime.sandboxes.create({ image: "app" });console.log((await sbx.exec("cat /etc/os-release")).stdout);

Pythonfrom withruntime import Runtimeruntime = Runtime()runtime.images.build(name="app", image="ghcr.io/acme/app:1.4.2")with runtime.sandboxes.create(image="app") as sbx:    print(sbx.exec("cat /etc/os-release").stdout)

Terminalruntime image build --from ghcr.io/acme/app:1.4.2 --name appruntime sandbox create --image app

The same stored credential covers FROM in a Dockerfile, COPY --from=<image> and a recipe's base. So a private base image with a few packages on top is one build:

TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime();await runtime.images.build({  name: "app-tools",  recipe: { base: "ghcr.io/acme/app:1.4.2", apt: ["jq"], pip: ["pytest"] },});

A program in the sandbox is found on the image's own PATH, so python in an image built from python:3.12-slim runs as it does there.

Keep it current

Each build of a name is its next version and takes latest, or the tags you give. When the registry publishes 1.4.3, build again with the same name: sandboxes that ask for app get the new version, and ones already running keep theirs. Pin with app@2 or a tag such as app:prod (names, versions and tags).

Mistakes to avoid

• A GitHub token without package read access. The pull is refused. Make a token that can read packages.
• Putting the token in a Dockerfile or build argument. It would be in the image. Store it as a registry credential, which a build opens only to pull.
• An ECR login token instead of an access key. Give an access key id and secret that may call ecr:GetAuthorizationToken; each build asks ECR for a fresh token itself.
• Giving the sandbox registry access to pull at run time. It does not need it: the image is already built. If code in the sandbox must call a private API, use a secret it never sees scoped to that host.

Building is free and uses no trial hours. A stored image costs $0.08 per decimal GB per 30-day month on its whole file, shared base included, and the trial keeps its first three images free (pricing). For containers the sandbox runs itself, see Docker in a sandbox.

Facts on this page were checked on 25 September 2026.