Runtime setup

Install, verify, and configure microsandbox runtime dependencies from every SDK

Local sandboxes use the msb executable and libkrunfw library. Depending on the SDK and installation method, those runtime files may already be bundled or may need to be downloaded. Each SDK exposes helpers that let an application verify the runtime before creating its first sandbox.

The default install root is ~/.microsandbox/ (%USERPROFILE%\.microsandbox on Windows). Explicit setup is useful when you want installation failures to surface at process startup or when you are preparing an offline environment.

Install and verify

Check for the runtime and install it only when needed. These installation helpers are idempotent and reuse an existing complete installation.

Rust

use microsandbox::{config::LocalConfig, setup::{InstallOptions, ensure_runtime}};

let runtime = ensure_runtime(&LocalConfig::default(), InstallOptions::default()).await?;

SDK	Install	Check	Behavior
Rust	setup::install_runtime(&LocalConfig, InstallOptions)	setup::resolve_runtime(&LocalConfig)	Resolves and installs msb plus libkrunfw as one matched pair.
TypeScript	install(): Promise<void>	isInstalled(): boolean	Downloads the package’s pinned runtime and verifies it.
Python	install() -> Awaitable[None]	is_installed() -> bool	Installs and verifies the runtime; release wheels normally bundle matching files.
Go	EnsureInstalled(ctx, ...SetupOption) error	IsInstalled() bool	Installs msb and libkrunfw; the Go FFI library is embedded separately.
Ruby	install -> nil	installed? -> bool	Installs and verifies the runtime used by the native extension.

Customize installation

Rust exposes explicit install sources and options for custom install roots, versions, verification, and replacement. TypeScript exposes its existing setup builder. Go exposes WithSkipDownload() for pre-provisioned or air-gapped environments. Python’s setup helper uses the default installation behavior.

InstallSource::EmbeddedArchive requires the Rust SDK’s embed-binaries feature. Without that feature, selecting the embedded source returns an error instead of downloading or falling back to another source.

The Rust crate enables both local and cloud by default. Applications that only use the hosted backend can build with default-features = false, features = ["cloud", "net"]; this omits the local database, image cache, migration, metrics, and host-runtime client dependencies. Local snapshots and image-archive import/export remain part of local rather than separate feature flags. Both download-binaries and embed-binaries imply local, and they manage the msb + libkrunfw host-runtime pair; Agentd packaging belongs to the msb build.

Rust

use microsandbox::{
    config::LocalConfig,
    setup::{InstallOptions, InstallSource, install_runtime},
};

let config = LocalConfig {
    home: Some("/opt/microsandbox".into()),
    ..Default::default()
};
let runtime = install_runtime(&config, InstallOptions {
    source: InstallSource::ReleaseDownload,
    version: "0.6.8".into(),
    force: true,
    ..Default::default()
}).await?;

Option	SDKs	Description
Install root	Rust: LocalConfig.home TypeScript: baseDir(path)	Override ~/.microsandbox/.
Runtime source	Rust: InstallSource	Choose an official download, archive path, unpacked directory, or embedded archive.
Runtime version	Rust: InstallOptions.version TypeScript: version(version)	Install a specific runtime version instead of the SDK’s pinned version.
Skip verification	Rust: InstallOptions.verify TypeScript: skipVerify(enabled)	Skip post-install verification.
Force replacement	Rust: InstallOptions.force TypeScript: force(enabled)	Replace an already complete installation. Partial installations fail closed.
Skip download	Go: WithSkipDownload()	Require the runtime to be present without fetching it.

In Go, WithSkipDownload() returns a SetupOption, whose exported type is func(*setupConfig). Options apply only to the first EnsureInstalled() call.

Override runtime paths

The Rust, TypeScript, Python, and Ruby SDKs can override process-wide runtime paths directly. Call setters before creating a local sandbox. Native language packages already provide their bundled msb path, so their public libkrunfw setter completes that package-owned pair.

Rust

use microsandbox::config::{set_sdk_libkrunfw_path, set_sdk_msb_path};

set_sdk_msb_path("/opt/microsandbox/bin/msb");
set_sdk_libkrunfw_path("/opt/microsandbox/lib/libkrunfw.dylib");

Environment variables work across the SDKs and take precedence over SDK-provided or configured paths:

Variable	Purpose
MSB_PATH	Override the msb executable used by local SDK operations.
MSB_LIBKRUNFW_PATH	Override the libkrunfw shared library loaded by the process.
MSB_AGENTD_PATH	Override the Agentd guest executable read by msb before VM startup.

Set these process-wide overrides before creating any local sandbox. When using environment overrides, set MSB_PATH and MSB_LIBKRUNFW_PATH together so resolution cannot mix runtime versions. MSB_AGENTD_PATH takes precedence over global paths.agentd; the selected file is read eagerly and must name a compatible Linux ELF executable. These variables do not belong to an individual sandbox configuration.

Inspect Go versions

Go also exposes the SDK’s pinned release version and the version reported by the loaded FFI library:

sdkVersion := m.SDKVersion()

runtimeVersion, err := m.RuntimeVersion()
if err != nil {
    return err
}

SDKVersion() string does not load the FFI library. RuntimeVersion() (string, error) loads it automatically on first use and returns an error if loading fails.