config.json

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

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()?;

sandbox_defaults

Defaults applied to every sandbox unless overridden per-sandbox.

sandbox_defaults.oci

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

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, credentials are resolved in this order:

1. Explicit SDK auth via .registry_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

Backend profiles

Backend profiles let CLI and SDK calls choose between the local runtime and a cloud backend from the same config.json file.

{
  "active_profile": "prod",
  "profiles": {
    "prod": {
      "backend": "cloud",
      "url": "https://cloud.example.com",
      "api_key_ref": "env:MSB_API_KEY"
    },
    "local": {
      "backend": "local"
    }
  }
}

Use active_profile for the default profile. Use MSB_PROFILE=<name> to override it for a single command:

MSB_PROFILE=prod msb run python -- python -V

Cloud profiles require url and api_key_ref. Supported credential references are:

Backend resolution uses this order:

1. Programmatic backend set by the SDK
2. MSB_BACKEND=local, or MSB_API_URL plus MSB_API_KEY
3. MSB_PROFILE=<name>
4. active_profile
5. Local runtime