Using local Docker images

microsandbox cannot read Docker's private local image store directly. If you build an image locally with docker build, export it with docker save and load it into microsandbox:

docker build -t my-image:latest .
docker save my-image:latest | msb load
msb run my-image:latest

You can also save to a file first:

docker save -o my-image.tar my-image:latest
msb load --input my-image.tar

If the archive has no useful tag, or you want a different local alias, pass one:

docker save my-image:latest | msb load --tag app:local
msb run app:local

msb load is the short top-level form of msb image load.

msb load can also import OCI Image Layout archives produced by tools such as BuildKit, Skopeo, or ORAS. If the OCI layout does not include an org.opencontainers.image.ref.name annotation, pass --tag to name the imported image locally.

Local registry alternative

Use a local registry when you want registry-like push/pull behavior, or when multiple machines should pull the same locally built image.

Step 1: Start a local registry

Run a local OCI registry on port 5050:

docker run -d -p 5050:5000 --name registry registry:2

Step 2: Build, tag, and push your image

Build your Docker image and tag it for the local registry:

docker build -t localhost:5050/my-image:latest .

If you already have an existing image, re-tag it:

docker tag my-image:latest localhost:5050/my-image:latest

Push to the local registry:

docker push localhost:5050/my-image:latest

Step 3: Pull with microsandbox

Since the local registry runs over plain HTTP, use the --insecure flag:

msb pull localhost:5050/my-image:latest --insecure

Step 4: Use it in microsandbox

import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("worker")
    .image("localhost:5050/my-image:latest")
    .registry((r) => r.insecure())
    .create();