Global config

microsandbox reads its global configuration from ~/.microsandbox/config.json. All fields are optional. A missing file or empty JSON object is equivalent to using the defaults.

Top-level fields

deployment_profile

Set deployment_profile when the local host must enforce one deployment policy for every sandbox:

{
  "deployment_profile": "multi-tenant"
}

single-tenant preserves the network configuration requested by each sandbox. multi-tenant applies the host-runtime isolation floor for shared infrastructure. The configured value is authoritative on create and restart, so a per-sandbox CLI or SDK option cannot weaken or replace it. A programmatic LocalBackendBuilder::deployment_profile() override takes precedence over the file. When the field is absent or null, each sandbox selects its own profile and defaults to single-tenant.

The parser also accepts the internal wire spellings single_tenant and multi_tenant for compatibility, but the kebab-case values above are canonical in this human-edited file. Managed cloud backends ignore this local setting because the hosting platform chooses their effective deployment profile.

database

paths

All path fields are optional. When null, they resolve relative to home.

On Windows, the default home is %USERPROFILE%\.microsandbox. JSON strings can use escaped backslashes such as "C:\\Users\\you\\.microsandbox\\lib\\libkrunfw.dll" or forward slashes such as "C:/Users/you/.microsandbox/lib/libkrunfw.dll".

Rust SDK path helpers

Rust callers can inspect the active local config and resolve runtime paths with the same precedence used by sandbox startup. microsandbox::config::config() uses the active default backend and returns Unsupported when that backend is cloud.

let cfg = microsandbox::config::config()?;
let msb = cfg.resolve_msb_path()?;
let libkrunfw = cfg.resolve_libkrunfw_path()?;

When your code owns an explicit local backend, prefer the backend-owned config:

use microsandbox::LocalBackend;

let backend = LocalBackend::builder()
    .home("/tmp/msb-home")
    .build()
    .await?;

let cfg = backend.config();
let msb = cfg.resolve_msb_path()?;

LocalBackend has two plain constructors alongside the builder. LocalBackend::lazy() is synchronous and defers opening (and migrating) the local sandbox database until the first operation; it is what backend resolution uses when no backend is set explicitly. LocalBackend::new().await? opens the database up front, so startup fails fast if the database is unusable.

sandbox_defaults

Defaults applied to local sandboxes unless overridden per-sandbox. Cloud backends retain their service-side default policy.

Explicit CLI or SDK options win over config.json, and config.json wins over built-in defaults. Microsandbox resolves the effective values once when it creates a local sandbox and persists that resolved sandbox configuration; changing the global file affects future creations, not existing sandboxes.

For workload effects, host requirements, filesystem expectations, and verification steps for these settings, see Optimization.

sandbox_defaults.oci

Defaults applied only when the sandbox rootfs is an OCI image.

root_disk and upper_size_mib are mutually exclusive. For a portable flat default, use clone: "auto"; it attempts a native reflink and safely falls back to a sparse copy. Use clone: "reflink" only when failure is preferable to copying on a host filesystem without reflink support.

When the root-disk default is flat, plain msb pull IMAGE also prepares the reusable flat artifact. An explicit msb pull IMAGE --materialize layered|flat|all always wins.

runtime

runtime.placement_profiles

Placement profiles let an operator define safe host topology policy once while callers select it by name. numa.mode is prefer_single, strict_single, or inherit; memory.mode is follow_cpu or inherit. Multi-node guest placement is not enabled in this release: prefer_single falls back to inherited host NUMA behavior when one node cannot fit, while strict_single fails clearly because it is an explicit guarantee.

follow_cpu requires managed CPU placement (auto, spread, or compact). Linux prefers the selected node for ordinary profiles and allows memory to spill elsewhere under pressure; strict_single uses a required binding instead. If CPUs span nodes, capacity is already insufficient, or the kernel rejects a best-effort affinity or memory-policy syscall, an ordinary profile starts with inherited memory placement. Windows keeps ordinary memory inherited because its preferred-node allocation cannot be undone if a later vCPU affinity attempt falls back; strict_single can still request required preferred-node allocation. Windows checks current boot-time availability, but does not expose equivalent per-node total capacity for a hard future-growth promise. macOS inherits ordinary CPU and memory scheduling for non-strict profiles because it has no equivalent hard-affinity API.

runtime.block_writeback

Use a fixed policy only when representative measurements justify a different per-disk window:

{
  "runtime": {
    "block_writeback": {
      "mode": "fixed",
      "per_disk_mib": 2048,
      "pool_mib": 12288
    }
  }
}

pool_mib is a live pressure budget, not eagerly allocated RAM. Every eligible writable disk in the same MSB_HOME receives a weighted max-min fair share: disks with a smaller configured maximum keep that smaller value, and the remaining pool is divided equally across the rest. Creating another sandbox never fails merely because this pool is full. Existing VMMs observe membership changes within 250 ms; if a disk already owns more dirty data than its new share, libkrun retires accounted ranges and pauses later writes until it converges below the target. A guest write already reserved before the target changed is allowed to complete safely. fixed and an explicitly pooled auto policy are unsupported on other hosts.

Hardware CRC32C, the guest kernel preemption model, x2APIC, APICv/AVIC capability, vCPU affinity mechanics, and the pure-Rust ext4 writer are implementation or capability details rather than user policy, so they intentionally have no global config keys. The optimization guide explains how those automatic layers interact with the configurable policy.

registries

registries.hosts

A map of registry hostnames to settings. Each host entry can mark the registry as insecure (plain HTTP) and can include an auth entry. Each auth entry specifies a username and exactly one credential source.

{
  "registries": {
    "hosts": {
      "ghcr.io": {
        "auth": {
          "username": "octocat",
          "store": "keyring"
        }
      },
      "localhost:5050": {
        "insecure": true,
        "auth": {
          "username": "dev",
          "password_env": "LOCAL_REGISTRY_TOKEN"
        }
      }
    }
  }
}

Host entry fields

Auth entry fields

Auth resolution order

When pulling from a registry, microsandbox resolves credentials in this order:

1. Explicit SDK auth via .registry(|r| r.auth(...)) on the sandbox builder
2. OS keyring entries created by msb registry login
3. Config file registries.hosts.<host>.auth entries in config.json
4. Docker config ~/.docker/config.json credential helpers
5. Anonymous (no authentication)

metrics

profiles

Named backend profiles keyed by profile name; active_profile selects the default. How profiles participate in backend selection, including the full resolution order, is documented in Backends.

Supported credential references for api_key_ref: