Skip to main content
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. 
{
  "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",
      "url": "https://cloud.example.com",
      "api_key_ref": "env:MSB_API_KEY"
    },
    "local": {
      "backend": "local"
    }
  }
}

​
Top-level fields

FieldDefaultDescription
home~/.microsandboxRoot directory for all microsandbox data
log_levelnull (silent)Log level for sandbox processes: error, warn, info, debug, trace
databasereferenceDatabase connection settings
pathsreferencePath overrides for binaries and directories
sandbox_defaultsreferenceDefaults applied to every sandbox
registriesreferenceContainer registry authentication
metricsreferenceLive metrics shared-memory registry settings
active_profilenullDefault backend profile name
profiles{}Named backend profiles

​
database

FieldDefaultDescription
urlnullDatabase URL. Uses SQLite under home when null
max_connections5Maximum connection pool size
connect_timeout_secs30Timeout when acquiring a database connection from the pool
busy_timeout_secs30SQLite 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".
FieldDefaultDescription
msb{home}/bin/msbmsb binary. Resolved via: MSB_PATH env, SDK-provided runtime path, this field, debug workspace build paths, default install path, then PATH
libkrunfw{home}/lib/libkrunfwPath 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}/cacheImage layer cache
sandboxes{home}/sandboxesPer-sandbox state
volumes{home}/volumesNamed volumes
snapshots{home}/snapshotsSnapshot artifacts
logs{home}/logsSandbox logs
secrets{home}/secretsSecrets. 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()?;

​
sandbox_defaults

Defaults applied to every sandbox unless overridden per-sandbox.
FieldDefaultDescription
cpus1Number of vCPUs
memory_mib512Guest memory in MiB
ocireferenceDefaults for OCI-rooted sandboxes
shell"/bin/sh"Shell for interactive sessions and scripts
workdirnullWorking directory inside the sandbox
metrics_sample_interval_ms1000Runtime metrics sampling interval in milliseconds. Set to 0 to disable sampling.
disable_metrics_samplefalseForce-disable metrics sampling regardless of metrics_sample_interval_ms.

​
sandbox_defaults.oci

Defaults applied only when the sandbox rootfs is an OCI image.
FieldDefaultDescription
upper_size_mib4096Writable overlay upper size in MiB

​
registries

FieldDefaultDescription
ca_certsnullPath 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

FieldRequiredDescription
insecureNoUse plain HTTP instead of HTTPS for this registry
authNoAuthentication entry for this registry

​
Auth entry fields

FieldRequiredDescription
usernameYesRegistry username
storeNoCredential store. Only "keyring" is supported (macOS Keychain, Windows Credential Manager, Linux Secret Service)
password_envNoEnvironment variable containing the password or token
secret_nameNoFilename 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:
  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

FieldDefaultDescription
capacity0Number 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.

​
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:
PrefixDescription
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
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