> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# config.json

> Global config.json reference

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.

<Accordion title="Full example">
  ```json theme={null}
  {
    "home": "/custom/path/.microsandbox",
    "log_level": "info",
    "database": {
      "url": "sqlite:///tmp/msb.db",
      "max_connections": 10,
      "connect_timeout_secs": 30
    },
    "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,
      "oci": {
        "upper_size_mib": 8192
      },
      "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"
        }
      }
    },
    "active_profile": "prod",
    "profiles": {
      "prod": {
        "backend": "cloud",
        "url": "https://cloud.example.com",
        "api_key_ref": "env:MSB_API_KEY"
      },
      "local": {
        "backend": "local"
      }
    }
  }
  ```
</Accordion>

## 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)         | Database connection settings                                               |
| `paths`            | [reference](#paths)            | Path overrides for binaries and directories                                |
| `sandbox_defaults` | [reference](#sandbox_defaults) | Defaults applied to every sandbox                                          |
| `registries`       | [reference](#registries)       | Container registry authentication                                          |
| `active_profile`   | `null`                         | Default backend profile name                                               |
| `profiles`         | `{}`                           | 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 |

## `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, this field, default path, `PATH`      |
| `libkrunfw` | `{home}/lib/libkrunfw` | Path to a custom VM kernel (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows) |
| `cache`     | `{home}/cache`         | Image layer cache                                                                 |
| `sandboxes` | `{home}/sandboxes`     | Per-sandbox state                                                                 |
| `volumes`   | `{home}/volumes`       | Named volumes                                                                     |
| `logs`      | `{home}/logs`          | Sandbox logs                                                                      |
| `secrets`   | `{home}/secrets`       | Secrets. Registry secrets live under `secrets/registries/`                        |

## `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](#sandbox_defaultsoci) | 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`

### `registries.auth`

A map of registry hostnames to authentication entries. Each entry specifies a username and exactly **one** credential source.

```json theme={null}
{
  "registries": {
    "auth": {
      "ghcr.io": {
        "username": "octocat",
        "store": "keyring"
      }
    }
  }
}
```

#### 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                                       |

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

### 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)

## Backend profiles

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

```json theme={null}
{
  "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:

```bash theme={null}
MSB_PROFILE=prod msb run python -- python -V
```

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

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

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