Images

Use OCI container images or boot from disk image files

OCI images

microsandbox uses standard OCI container images as root filesystems. Docker Hub, GHCR, ECR, GCR, any OCI-compatible registry works. Existing images run as-is.

When you specify an image like python, microsandbox pulls the manifest, downloads the layers in parallel, and stacks them as a copy-on-write filesystem. Changes inside the sandbox don’t modify the base image. Two sandboxes using the same image share the same cached layers on disk.

Pull policies

By default, microsandbox pulls an image only if it isn’t already cached. You can change this behavior.

Policy	Behavior
"if-missing"	Pull only if not cached (default)
"always"	Always check the registry for updates
"never"	Use local cache only, fail if missing

TypeScript

import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("worker")
    .image("python")
    .pullPolicy("always")
    .create();

Once microsandbox resolves an image reference, it pins the exact layers. At first pull, python resolves to a specific set of immutable layers. Subsequent start() calls use the pinned layers without re-resolving the mutable tag, so your sandbox is reproducible even if the upstream tag moves.

Private registries

Authenticate to private registries by passing credentials.

TypeScript

await using sb = await Sandbox.builder("worker")
    .image("registry.corp.io/team/app:latest")
    .registry((r) => r.auth({
        kind: "basic",
        username: "deploy",
        password: process.env.REGISTRY_TOKEN!,
    }))
    .pullPolicy("always")
    .create();

Registry TLS

Local-only

By default, microsandbox connects to registries over HTTPS using system CA roots. You can customize this per-registry in ~/.microsandbox/config.json.

Plain HTTP registries

Local registries often run without TLS. Mark them as insecure to connect over plain HTTP:

{
  "registries": {
    "hosts": {
      "localhost:5050": {
        "insecure": true
      }
    }
  }
}

Custom CA certificates

For registries using self-signed or internal CA certificates, point ca_certs to a PEM file. This applies globally to all registry connections:

{
  "registries": {
    "ca_certs": "/path/to/ca-bundle.pem"
  }
}

microsandbox adds these certificates to the default system roots, so public registries continue to work normally. You can also supply the same roots per-sandbox through the SDK: caCerts in TypeScript, ca_certs in Rust, registry_ca_certs in Python, and WithRegistryCACerts / WithRegistryCACertsPath in Go.

Combined configuration

{
  "registries": {
    "ca_certs": "/path/to/corporate-ca.pem",
    "hosts": {
      "localhost:5050": {
        "insecure": true,
        "auth": { "username": "deploy", "password_env": "REGISTRY_TOKEN" }
      },
      "ghcr.io": {
        "auth": { "username": "user", "store": "keyring" }
      }
    }
  }
}

You can also set these per-sandbox via the SDK, overriding global config:

TypeScript

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

Image storage

Local-only

Images are cached in the global microsandbox home directory:

Path	Description
~/.microsandbox/cache/layers/	Materialized EROFS image layers
~/.microsandbox/cache/fsmeta/	Merged metadata images for cached manifests
~/.microsandbox/cache/vmdk/	VMDK descriptors used to boot cached images
~/.microsandbox/db/	Database tracking image metadata and digests

Layers are content-addressable and deduplicated. If python:3.12 and python:3.11 share a base layer, it’s stored once.

Use msb pull from the CLI to pre-pull images before creating sandboxes. This avoids blocking on a download during Sandbox.create.

Use msb image prune to remove cached images that are not used by any sandbox or indexed snapshot and reclaim dangling image artifacts. Prune keeps images referenced by existing sandboxes or snapshots. It cleans up image metadata, unreachable manifests, orphaned layers, layer EROFS artifacts, fsmeta EROFS artifacts, and VMDK descriptor artifacts.

msb load accepts Docker image archives and OCI Image Layout archives. By default, msb save exports from the materialized EROFS cache as a Docker archive. Use --format oci to export as an OCI Image Layout archive instead. The expanded forms are msb image load and msb image save. The exported image should run the same way after msb load, but it is a regenerated archive: manifest digest and layer digests can differ from the original registry image.

Disk images

Local-only

In addition to OCI container images, microsandbox can boot a sandbox directly from a disk image file. The guest gets raw block device access, and its kernel mounts the filesystem from the device directly.

This is a fundamentally different path from OCI images. With OCI, microsandbox stacks image layers as a copy-on-write filesystem. With disk images, the guest owns the block device. No overlay, no copy-on-write between sandboxes.

Use disk images when you need a pre-built VM template, a custom kernel configuration, or an OS that isn’t available as a container image.

Supported formats

Format	Description
QCOW2	QEMU Copy-On-Write v2. Supports thin provisioning and backing files. The most common format.
Raw	Uncompressed raw disk image. No overhead, but no thin provisioning.
VMDK	VMware virtual disk format.

Usage

When you pass a file path ending in .qcow2, .raw, or .vmdk, microsandbox auto-detects the format. For disk-image roots, rename ambiguous files with one of those extensions and set the filesystem type when auto-detection needs a hint.

TypeScript

import { Sandbox } from "microsandbox";

// Auto-detect format from the file extension
await using sb = await Sandbox.builder("custom-vm")
    .image("./ubuntu-22.04.qcow2")
    .cpus(2)
    .memory(2048)
    .create();

// Explicit filesystem type via the ImageBuilder
await using sb2 = await Sandbox.builder("custom-vm")
    .imageWith((i) => i.disk("./alpine.raw").fstype("ext4"))
    .cpus(1)
    .memory(512)
    .create();

The filesystem type (ext4, xfs, etc.) must match what’s actually on the disk image. The guest kernel mounts it using the specified filesystem driver.

Reference

For exact image APIs, see TypeScript, Rust, Python, or Go. For local image management, see Image commands.