Skip to main content
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

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.