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
  },
  "paths": {
    "msb": "/usr/local/bin/msb",
    "libkrunfw": "/usr/local/lib/libkrunfw.so",
    "cache": "/mnt/fast/msb-cache",
    "sandboxes": null,
    "volumes": null,
    "logs": null,
    "secrets": null
  },
  "sandbox_defaults": {
    "cpus": 2,
    "memory_mib": 1024,
    "shell": "/bin/bash",
    "workdir": "/app"
  },
  "registries": {
    "auth": {
      "ghcr.io": {
        "username": "octocat",
        "store": "keyring"
      },
      "registry.example.com": {
        "username": "deploy",
        "password_env": "REGISTRY_TOKEN"
      },
      "docker.io": {
        "username": "user",
        "secret_name": "dockerhub-token"
      }
    }
  }
}

​
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

​
database

FieldDefaultDescription
urlnullDatabase URL. Uses SQLite under home when null
max_connections5Maximum connection pool size

​
paths

All path fields are optional. When null, they resolve relative to home.
FieldDefaultDescription
msb{home}/bin/msbmsb binary. Resolved via: MSB_PATH env, this field, default path, PATH
libkrunfw{home}/lib/libkrunfwPath to a custom VM kernel (.so on Linux, .dylib on macOS)
cache{home}/cacheImage layer cache
sandboxes{home}/sandboxesPer-sandbox state
volumes{home}/volumesNamed volumes
logs{home}/logsSandbox logs
secrets{home}/secretsSecrets. Registry secrets live under secrets/registries/

​
sandbox_defaults

Defaults applied to every sandbox unless overridden per-sandbox.
FieldDefaultDescription
cpus1Number of vCPUs
memory_mib512Guest memory in MiB
shell"/bin/sh"Shell for interactive sessions and scripts
workdirnullWorking directory inside the sandbox

​
registries

​
registries.auth

A map of registry hostnames to authentication entries. Each entry specifies a username and exactly one credential source. 
{
  "registries": {
    "auth": {
      "ghcr.io": {
        "username": "octocat",
        "store": "keyring"
      }
    }
  }
}

​
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, 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.auth entries in config.json
  4. Docker config ~/.docker/config.json credential helpers
  5. Anonymous (no authentication)