Using local Docker images

microsandbox cannot read Docker’s private local image store directly. First, build the image with Docker:

docker build -t my-image:latest .

Stream the image into microsandbox’s local image store:

docker save my-image:latest | msb load

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

You can now run it like any other image:

msb run my-image:latest

You can also save to a file first:

docker save -o my-image.tar my-image:latest

Load the saved archive:

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

docker save -o my-image.tar my-image:latest
msb load --input my-image.tar --tag app:local
Remove-Item my-image.tar

Run it by its new local name:

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.

Start a local registry

Run a local OCI registry on port 5050:

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

Port 5000 is used by AirPlay on macOS. This guide uses port 5050 to avoid conflicts.

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

Pull with microsandbox

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

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

Use it in microsandbox

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

import { Sandbox } from "microsandbox";

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

For persistent configuration that applies to all CLI and SDK operations, add the registry to ~/.microsandbox/config.json instead. See Registry TLS.

Agents

CI/CD

Docker

Sandbox Workflows

Automation & Tooling

Data & Observability

Using local Docker images

Local registry alternative

​Local registry alternative

Local registry alternative