Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt

Use this file to discover all available pages before exploring further.

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?;
For persistent configuration that applies to all CLI and SDK operations, add the registry to ~/.microsandbox/config.json instead. See Registry TLS.