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.

Full example

{
  "home": "/custom/path/.microsandbox",
  "log_level": "info",
  "database": {
    "url": "sqlite:///tmp/msb.db",
    "max_connections": 10,
    "connect_timeout_secs": 30,
    "busy_timeout_secs": 30
  },
  "paths": {
    "msb": "/usr/local/bin/msb",
    "libkrunfw": "/usr/local/lib/libkrunfw.so",
    "cache": "/mnt/fast/msb-cache",
    "sandboxes": null,
    "volumes": null,
    "snapshots": null,
    "logs": null,
    "secrets": null
  },
  "sandbox_defaults": {
    "cpus": 2,
    "memory_mib": 1024,
    "oci": {
      "upper_size_mib": 8192
    },
    "shell": "/bin/bash",
    "workdir": "/app"
  },
  "registries": {
    "ca_certs": "/path/to/corporate-ca.pem",
    "hosts": {
      "ghcr.io": {
        "auth": {
          "username": "octocat",
          "store": "keyring"
        }
      },
      "registry.example.com": {
        "insecure": true,
        "auth": {
          "username": "deploy",
          "password_env": "REGISTRY_TOKEN"
        }
      },
      "docker.io": {
        "auth": {
          "username": "user",
          "secret_name": "dockerhub-token"
        }
      }
    }
  },
  "metrics": {
    "capacity": 4096
  },
  "active_profile": "prod",
  "profiles": {
    "prod": {
      "backend": "cloud",
      "api_key_ref": "env:MSB_API_KEY"
    },
    "local": {
      "backend": "local"
    }
  }
}

Top-level fields

Field	Default	Description
`home`	`~/.microsandbox`	Root directory for all microsandbox data
`log_level`	`null` (silent)	Log level for sandbox processes: `error`, `warn`, `info`, `debug`, `trace`
`database`	reference	Database connection settings
`paths`	reference	Path overrides for binaries and directories
`sandbox_defaults`	reference	Defaults applied to every sandbox
`registries`	reference	Container registry authentication
`metrics`	reference	Live metrics shared-memory registry settings
`active_profile`	`null`	Default backend profile name
`profiles`	reference	Named backend profiles

`database`

Field	Default	Description
`url`	`null`	Database URL. Uses SQLite under `home` when null
`max_connections`	`5`	Maximum connection pool size
`connect_timeout_secs`	`30`	Timeout when acquiring a database connection from the pool
`busy_timeout_secs`	`30`	SQLite busy timeout before a contended write surfaces as an error

`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".

Field	Default	Description
`msb`	`{home}/bin/msb`	`msb` binary. Resolved via: `MSB_PATH` env, SDK-provided runtime path, this field, debug workspace build paths, default install path, then `PATH`
`libkrunfw`	`{home}/lib/libkrunfw`	Path to a custom VM kernel (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows). Resolved via: `MSB_LIBKRUNFW_PATH` env, SDK-provided runtime path, this field, paths next to the resolved `msb` binary, then default install path
`cache`	`{home}/cache`	Image layer cache
`sandboxes`	`{home}/sandboxes`	Per-sandbox state
`volumes`	`{home}/volumes`	Named volumes
`snapshots`	`{home}/snapshots`	Snapshot artifacts
`logs`	`{home}/logs`	Sandbox logs
`secrets`	`{home}/secrets`	Secrets. Registry secrets live under `secrets/registries/`

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 every sandbox unless overridden per-sandbox.

Field	Default	Description
`cpus`	`1`	Number of vCPUs
`memory_mib`	`512`	Guest memory in MiB
`oci`	reference	Defaults for OCI-rooted sandboxes
`shell`	`"/bin/sh"`	Shell for interactive sessions and scripts
`workdir`	`null`	Working directory inside the sandbox
`metrics_sample_interval_ms`	`1000`	Runtime metrics sampling interval in milliseconds. Set to `0` to disable sampling.
`disable_metrics_sample`	`false`	Force-disable metrics sampling regardless of `metrics_sample_interval_ms`.

`sandbox_defaults.oci`

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

Field	Default	Description
`upper_size_mib`	`4096`	Writable overlay upper size in MiB

`registries`

Field	Default	Description
`ca_certs`	`null`	Path to a PEM file with additional CA root certificates trusted for registry pulls
`hosts`	`{}`	Per-registry settings keyed by registry hostname

`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

Field	Required	Description
`insecure`	No	Use plain HTTP instead of HTTPS for this registry
`auth`	No	Authentication entry for this registry

Auth entry fields

Field	Required	Description
`username`	Yes	Registry username
`store`	No	Credential store. Only `"keyring"` is supported (macOS Keychain, Windows Credential Manager, Linux Secret Service)
`password_env`	No	Environment variable containing the password or token
`secret_name`	No	Filename under `{home}/secrets/registries/` containing the password or token

Exactly one of store, password_env, or secret_name must be set per entry. Setting none or more than one is an error.

Auth resolution order

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

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

`metrics`

Field	Default	Description
`capacity`	`0`	Number of slots reserved in the live metrics shared-memory registry. `0` uses the built-in default. Stop all sandboxes for the same home before changing this value.

`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.

Field	Default	Description
`backend`	required	`local` or `cloud`
`api_key_ref`	none	Credential reference; required for `cloud` profiles
`url`	`https://api.microsandbox.dev`	Cloud endpoint override for development, self-hosted, or on-prem control planes

Supported credential references for api_key_ref:

Prefix	Description
`env:<VAR_NAME>`	Read the API key from an environment variable
`inline:<API_KEY>`	Store the API key directly in `config.json`; use only for development or CI

Getting Started

SDKs

CLI

Top-level fields

`database`

`paths`

Rust SDK path helpers

`sandbox_defaults`

`sandbox_defaults.oci`

`registries`

`registries.hosts`

Host entry fields

Auth entry fields

Auth resolution order

`metrics`

`profiles`

​Top-level fields

​database

​paths

​Rust SDK path helpers

​sandbox_defaults

​sandbox_defaults.oci

​registries

​registries.hosts

​Host entry fields

​Auth entry fields

​Auth resolution order

​metrics

​profiles

Top-level fields

`database`

`paths`

Rust SDK path helpers

`sandbox_defaults`

`sandbox_defaults.oci`

`registries`

`registries.hosts`

Host entry fields

Auth entry fields

Auth resolution order

`metrics`

`profiles`