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

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

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

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.

Docker

Guest

Metrics backends

Using local Docker images

Local registry alternative

Step 1: Start a local registry

Step 2: Build, tag, and push your image

Step 3: Pull with microsandbox

Step 4: Use it in microsandbox

​Local registry alternative

​Step 1: Start a local registry

​Step 2: Build, tag, and push your image

​Step 3: Pull with microsandbox

​Step 4: Use it in microsandbox

Local registry alternative

Step 1: Start a local registry

Step 2: Build, tag, and push your image

Step 3: Pull with microsandbox

Step 4: Use it in microsandbox