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

# Configuration

> Read global settings and configure local backends with the Rust SDK.

See [Global configuration](https://docs.microsandbox.dev/configuration.md) for file fields and defaults, and [Runtime setup](https://docs.microsandbox.dev/sdk/setup.md) for installation.

## GlobalConfigPatch

### load()

```rust theme={null}
fn load() -> MicrosandboxResult<Self>
```

Read saved user settings while preserving omitted fields and explicit clears. A missing file returns an empty patch. Defaults and managed overrides are applied later.

### save()

```rust theme={null}
fn save(&self) -> MicrosandboxResult<()>
```

Save the patch without filling in defaults. Omitted fields stay omitted and explicit clears are preserved. Unknown user fields are ignored on load and discarded on save.

## GlobalConfig

Resolved settings after layering. Use [`LocalBackend::config()`](#config) to read the effective configuration for a backend.

## LocalBackend

### config()

```rust theme={null}
fn config(&self) -> &GlobalConfig
```

Read the settings retained by this backend. Existing handles keep their configuration when files or process defaults change.

### Runtime paths

Inspect the active config and resolve runtime paths with the same precedence used by sandbox startup:

> [accordion] Example
>
> ```rust theme={null}
> use microsandbox::{config::config, setup::resolve_runtime};
>
> let cfg = config()?;
> let runtime = resolve_runtime(&cfg)?;
> let msb = &runtime.msb_path;
> let libkrunfw = &runtime.libkrunfw_path;
> ```

When your code owns an explicit local backend, prefer the backend-owned config:

> [accordion] Example
>
> ```rust theme={null}
> use microsandbox::{setup::resolve_runtime, LocalBackend};
>
> let backend = LocalBackend::builder()
>     .home("/tmp/msb-home")
>     .build()
>     .await?;
>
> let cfg = backend.config();
> let runtime = resolve_runtime(cfg)?;
> ```

`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. All constructors read, layer, and validate global configuration before returning a backend; only database setup is lazy. Proxy settings are validated after sandbox options and managed overrides are composed, before network use.

`LocalBackendBuilder::build_lazy()` now returns `Result<LocalBackend>`. It replaces `try_build_lazy()`, and `LocalBackend` no longer implements `Default`; use `LocalBackend::lazy()?` instead.

For a long-lived process, construct a new backend to pick up configuration changes. Installing it with `set_default_backend` affects future operations; existing sandbox and volume handles retain their original backend. Construct the replacement successfully before installing it.

## LocalBackendBuilder

### config\_path()

```rust theme={null}
fn config_path(self, path: impl Into<PathBuf>) -> Self
```

Read a specific user configuration file without changing `MSB_CONFIG_PATH`. Managed settings still apply. The builder's `home()` selects data storage; it does not select the configuration file. Backend-selection helpers and synchronous constructors remain synchronous.

> [accordion] Example
>
> ```rust theme={null}
> use microsandbox::LocalBackend;
>
> let backend = LocalBackend::builder()
>     .config_path("/etc/my-app/microsandbox.json")
>     .build_lazy()?;
> ```

### deployment\_profile()

```rust theme={null}
fn deployment_profile(self, profile: DeploymentProfile) -> Self
```

Set the authoritative deployment profile for this backend. It takes precedence over the user configuration file and each sandbox's requested profile on create and restart. Managed settings retain precedence. See [deployment profiles](https://docs.microsandbox.dev/configuration.md#deployment_profile) for behavior.

### ssh\_inactivity\_timeout\_secs()

```rust theme={null}
fn ssh_inactivity_timeout_secs(self, secs: u64) -> Self
```

Override the user-configured SSH inactivity timeout. Zero disables it; managed settings retain precedence. See [SSH settings](https://docs.microsandbox.dev/configuration.md#ssh) for when the value is captured.

## Sandbox configuration patches

Use [`SandboxBuilder::overlay()`](https://docs.microsandbox.dev/sdk/rust/sandbox#sandbox-overlay) to override individual settings or explicitly clear an inherited working directory. These choices survive `SandboxBuilder::from(config)` and local database reloads. Without saved caller overrides, `workdir: None` still means omitted.

Edit settings through builder setters, `overlay()`, or sandbox modification APIs; saved overrides can overwrite direct edits to a resolved `SandboxConfig`. See [configuration layering](https://docs.microsandbox.dev/configuration.md#sandbox_defaults) for precedence and backend differences.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.