Rust SDK configuration reference

See Global configuration for file fields and defaults, and Runtime setup for installation.

GlobalConfigPatch

load()

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

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() to read the effective configuration for a backend.

LocalBackend

config()

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:

Example

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:

Example

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

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.

Example

use microsandbox::LocalBackend;

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

deployment_profile()

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 for behavior.

ssh_inactivity_timeout_secs()

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 for when the value is captured.

Sandbox configuration patches

Use SandboxBuilder::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 for precedence and backend differences.

Getting Started

SDKs

CLI

Configuration

GlobalConfigPatch

load()

save()

GlobalConfig

LocalBackend

config()

Runtime paths

LocalBackendBuilder

config_path()

deployment_profile()

ssh_inactivity_timeout_secs()

Sandbox configuration patches

​GlobalConfigPatch

​load()

​save()

​GlobalConfig

​LocalBackend

​config()

​Runtime paths

​LocalBackendBuilder

​config_path()

​deployment_profile()

​ssh_inactivity_timeout_secs()

​Sandbox configuration patches

GlobalConfigPatch

load()

save()

GlobalConfig

LocalBackend

config()

Runtime paths

LocalBackendBuilder

config_path()

deployment_profile()

ssh_inactivity_timeout_secs()

Sandbox configuration patches