Using Local Docker Images

Use locally built Docker images with microsandbox via a local registry

microsandbox pulls images from OCI-compatible registries. If you build an image locally with docker build, microsandbox can’t access it directly from Docker’s local store. The workaround is to run a local registry and push your image there.

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

Rust

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

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