> ## 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](/configuration) for file fields and defaults, and [Runtime setup](/sdk/setup) 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 title="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;
  ```
</Accordion>

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

<Accordion title="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)?;
  ```
</Accordion>

`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 title="Example">
  ```rust theme={null}
  use microsandbox::LocalBackend;

  let backend = LocalBackend::builder()
      .config_path("/etc/my-app/microsandbox.json")
      .build_lazy()?;
  ```
</Accordion>

### 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](/configuration#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](/configuration#ssh) for when the value is captured.

## Sandbox configuration patches

Use [`SandboxBuilder::overlay()`](/sdk/rust/sandbox#sandbox-overlay) to add sparse per-sandbox values. A concrete `SandboxConfig` with `workdir: None` is treated as omitted. To explicitly clear an inherited working directory, use a patch. See [configuration layering](/configuration#sandbox_defaults) for precedence and backend differences.


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