Microsandbox SDK runtime setup

Local sandboxes need msb and libkrunfw. Call the setup helper once at application startup: it reuses an existing runtime or installs one when missing. Sandbox creation does not download it automatically. Cloud sandboxes do not need a local runtime.

Set up the runtime

import { ensureRuntime } from "microsandbox";

const runtime = await ensureRuntime();
console.log(runtime.msbPath, runtime.libkrunfwPath);

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

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

from microsandbox import ensure_runtime

runtime = await ensure_runtime()
print(runtime.msb_path, runtime.libkrunfw_path)

import (
    "fmt"
    m "github.com/superradcompany/microsandbox/sdk/go"
)

runtime, err := m.EnsureRuntime(ctx, m.RuntimeConfig{}, m.InstallOptions{})
if err != nil {
    return err
}
fmt.Println(runtime.MSBPath, runtime.LibkrunfwPath)

require "microsandbox"

Microsandbox.install unless Microsandbox.installed?

The default installation directory is ~/.microsandbox (%USERPROFILE%\.microsandbox on Windows). Keep msb and libkrunfw from the same runtime bundle.

Choose a setup operation

Use ensure for normal startup. The calls below are alternatives; choose the one your application needs.

import * as msb from "microsandbox";

await msb.ensureRuntime();  // Reuse or install if missing.
msb.resolveRuntime();       // Require an existing runtime; never install.
msb.isRuntimeInstalled();   // Check availability; returns a boolean.
await msb.installRuntime(); // Install from the selected source.

use microsandbox::{config::GlobalConfig, setup};

let config = GlobalConfig::default();

// Reuse or install if missing.
setup::ensure_runtime(&config, Default::default()).await?;
// Require an existing runtime; never install.
setup::resolve_runtime(&config)?;
// Check availability; returns a boolean.
setup::is_runtime_installed(&config);
// Install from the selected source.
setup::install_runtime(&config, Default::default()).await?;

import microsandbox as msb

await msb.ensure_runtime()  # Reuse or install if missing.
msb.resolve_runtime()       # Require an existing runtime; never install.
msb.is_runtime_installed()  # Check availability; returns a boolean.
await msb.install_runtime() # Install from the selected source.

import m "github.com/superradcompany/microsandbox/sdk/go"

config := m.RuntimeConfig{}
options := m.InstallOptions{}

// Reuse or install if missing. Returns (ResolvedRuntime, error).
m.EnsureRuntime(ctx, config, options)
// Require an existing runtime. Returns (ResolvedRuntime, error).
m.ResolveRuntime(config)
// Check availability; returns bool.
m.IsRuntimeInstalled(config)
// Install from the selected source. Returns (ResolvedRuntime, error).
m.InstallRuntime(ctx, config, options)

Ensure does not repair incomplete installations or ignore invalid explicit paths.

How runtime selection works

The SDK checks these locations in order:

Explicit paths: environment variables, process-level setters, then configured paths.
Runtime home: configured home, then MSB_HOME, then ~/.microsandbox.
SDK package: bundled binaries, when available.

A complete home installation wins over bundled Python and Node runtimes, even if its version differs from the SDK. Updating an SDK does not replace that installation. Go also reuses a complete home installation. Managed runtime paths override user choices. To use a custom installation, set both MSB_PATH and MSB_LIBKRUNFW_PATH before constructing a backend. See path overrides for SDK setters and precedence details.

Advanced setup

Bring your own runtime

Install a matching pair with the CLI installer, or provision it yourself and select its paths above.

Node: the platform package includes the runtime and native addon. --omit=optional also removes the required addon.
Rust: embedding is opt-in. To also disable the default Cargo-time runtime download:

cargo add microsandbox --no-default-features --features local,net

You can still call setup::ensure_runtime() explicitly with these features.

Use a custom kernel

If your workload needs additional Linux kernel features, build a custom libkrunfw, the library that bundles the guest kernel. This applies to local sandboxes; it does not change the managed cloud kernel.

Start from the vendor/libkrunfw revision pinned by your microsandbox release in our libkrunfw fork. It includes the kernel patches microsandbox relies on; an upstream build may not be compatible.

Enable the required kernel options or apply your patches, then follow the build instructions for your platform and architecture.
Select the compatible msb executable and your rebuilt library before starting your application.

For example, on Linux, replace these paths with your executable and custom library:

export MSB_PATH="/opt/microsandbox/bin/msb"
export MSB_LIBKRUNFW_PATH="/opt/custom-kernel/libkrunfw.so.5"

You can also use the SDK path setters. In Rust, set_sdk_libkrunfw_path() is process-wide, not a SandboxBuilder method; call it before constructing the backend. Boot a fresh guest to use the new kernel. Running guests and full snapshots retain their existing kernel.

Offline installation

Use a directory or archive source to install a pre-downloaded release bundle. To require an installation that already exists, call the resolve helper instead of ensure. See installation examples and options and offline deployment.

Embedded runtime

If your SDK build includes an embedded runtime archive, you can install from it without downloading. Select the embedded_archive source in the installation options. Ensure reuses an existing runtime before extracting the archive. Resolve only finds an existing installation; it does not extract one.

Troubleshooting

Problem	What to do
Incomplete installation	Restore a matching executable and library. Setup does not repair a partial pair or fall back to bundled binaries.
Invalid explicit path	Correct the override. Invalid paths do not fall through to another installation.
Unexpected runtime version	Check explicit paths and the runtime home; both take precedence over bundled binaries.
Feature unsupported by an older runtime	Upgrade the selected runtime. Updating the SDK alone may leave it unchanged.
Embedded archive unavailable	Use a native SDK built with embedding, or choose a directory, archive, or download source.

For existing installations, see the v0.7 migration guide before upgrading a shared database. Helper details are available below.

API reference

Customize installation

Python, TypeScript, and Go accept a RuntimeConfig and InstallOptions. Their per-call home and binary-path overrides are layered on persisted global configuration. Rust accepts GlobalConfig and InstallOptions directly. Environment binary-path overrides retain the highest priority.Use the directory source to provision a runtime from a flat release-bundle directory containing msb and libkrunfw side by side, without downloading:

import { installRuntime } from "microsandbox";

const runtime = await installRuntime(
  { home: "/opt/microsandbox" },
  { source: "directory", sourcePath: "/opt/runtime-bundle" },
);

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

let config = GlobalConfig { home: Some("/opt/microsandbox".into()), ..Default::default() };
let runtime = install_runtime(&config, InstallOptions {
    source: InstallSource::Directory("/opt/runtime-bundle".into()),
    ..Default::default()
}).await?;

from microsandbox import InstallOptions, RuntimeConfig, install_runtime

runtime = await install_runtime(
    RuntimeConfig(home="/opt/microsandbox"),
    InstallOptions(source="directory", source_path="/opt/runtime-bundle"),
)

runtime, err := m.InstallRuntime(ctx,
    m.RuntimeConfig{Home: "/opt/microsandbox"},
    m.InstallOptions{Source: m.InstallSourceDirectory, SourcePath: "/opt/runtime-bundle"},
)
if err != nil {
    return err
}

Option	Behavior
Home and binary paths	Select the runtime home or explicit pair for this call.
Source	`release_download` (default), `directory`, `archive`, or `embedded_archive`; directory and archive require a source path.
Version	Select the release to download; defaults to the SDK’s pinned release.
Force	Replace a complete installation; never repair a partial pair.
Verify	Verify the installed pair; defaults to true. Go uses `*bool` so its zero value preserves this default.
Expected archive SHA-256	Validate downloaded, local, or embedded archive bytes before publishing files.

An embedded source requires a native SDK built with an embedded runtime archive. If unavailable, explicit installation errors. Ensure still reuses an existing pair before acquisition, even when an embedded source is requested. To require a pre-provisioned runtime, call resolve directly. Each call uses its own configuration; Go no longer caches a process-wide successful setup result.

Override runtime paths

The TypeScript, Rust, Python, and Ruby SDKs can override process-wide runtime paths directly. Call setters before creating a local sandbox. Automatic package discovery is a fallback and does not occupy the explicit setter slot. A public libkrunfw setter overrides the library for the selected executable, whether that executable comes from configured paths, home, or a package.

import { setRuntimeLibkrunfwPath } from "microsandbox";

setRuntimeLibkrunfwPath("/opt/microsandbox/lib/libkrunfw.dylib");

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");

from microsandbox import set_libkrunfw_path

set_libkrunfw_path("/opt/microsandbox/lib/libkrunfw.dylib")

require "microsandbox"

Microsandbox.set_runtime_libkrunfw_path("/opt/microsandbox/lib/libkrunfw.dylib")

Set runtime paths before constructing a backend. Each backend captures these settings; create a new backend to pick up changes. Environment variables work across the SDKs and take precedence over SDK-provided or user-configured paths. Managed runtime paths take precedence over all three:

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. Prefer setting MSB_PATH and MSB_LIBKRUNFW_PATH together to select a matching pair. MSB_PATH alone may resolve a library adjacent to that executable; MSB_LIBKRUNFW_PATH alone is incomplete and fails closed. An incomplete explicit pair is not repaired by falling back to another installation. 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.

Read a runtime version

TypeScript and Rust can read the Cargo package version embedded in an msb executable without running it. This is an optional inspection of the specified file; firmware and a complete runtime installation are not required.

import { resolveRuntimeVersion } from "microsandbox";

const version = await resolveRuntimeVersion("/path/to/msb");

use microsandbox::setup::resolve_runtime_version;

let version = resolve_runtime_version("/path/to/msb")?;

Rust returns Option<setup::Version> and TypeScript returns string | null. Older executables without the version section produce None or null. Invalid executable metadata, malformed version sections and file access failures are errors. The reader supports ELF, PE and thin or universal Mach-O files, limits metadata reads to 4 MiB and version contents to 256 bytes, and never falls back to executing msb --version. Universal Mach-O slices must agree on the version, including section absence. The version identifies the build; it does not authenticate the executable or guarantee feature compatibility.Sandbox startup separately resolves a tested launch contract for the selected runtime. When embedded version metadata is absent, startup may run a bounded msb --version probe and cache the result for that native executable’s identity within the SDK process. Replacing the executable invalidates that cache. This startup behavior does not change the read-only version inspection methods above.

Inspect Go versions

Go setup helpers may load the SDK’s embedded FFI library on first use; resolve does not install host runtime binaries.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.

Compatibility: setup APIs before v0.7

These APIs were replaced in v0.7.0. Use this mapping when upgrading from v0.6; new applications should use the current helpers above.

SDK	Replace	With
TypeScript	`install`	`installRuntime`
TypeScript	`isInstalled`	`isRuntimeInstalled`
Python	`install`	`install_runtime`
Python	`is_installed`	`is_runtime_installed`
Go	`EnsureInstalled`	`EnsureRuntime`
Go	`IsInstalled`	`IsRuntimeInstalled`

TypeScript: replace the setup / Setup builder with runtime helpers accepting RuntimeConfig and InstallOptions.
Go: replace SetupOption with RuntimeConfig and InstallOptions. Replace WithSkipDownload with ResolveRuntime when installation must be avoided.

Install and ensure now return the selected runtime paths. Rust’s four helper names and Ruby’s setup API are unchanged. See setup operations.

Getting Started

SDKs

CLI

Runtime setup

Set up the runtime

Choose a setup operation

How runtime selection works

Advanced setup

Bring your own runtime

Use a custom kernel

Offline installation

Embedded runtime

Troubleshooting

API reference

​Set up the runtime

​Choose a setup operation

​How runtime selection works

​Advanced setup

​Bring your own runtime

​Use a custom kernel

​Offline installation

​Embedded runtime

​Troubleshooting

​API reference

Set up the runtime

Choose a setup operation

How runtime selection works

Advanced setup

Bring your own runtime

Use a custom kernel

Offline installation

Embedded runtime

Troubleshooting

API reference