Runtime setup

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 a matching installation.

use microsandbox::setup;

if !setup::is_installed() {
    setup::install().await?;
}

import { install, isInstalled } from "microsandbox";

if (!isInstalled()) {
  await install();
}

from microsandbox import install, is_installed

if not is_installed():
    await install()

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

if !m.IsInstalled() {
    if err := m.EnsureInstalled(ctx); err != nil {
        return err
    }
}

SDK	Install	Check	Behavior
Rust	`setup::install() -> MicrosandboxResult<()>`	`setup::is_installed() -> bool`	Downloads the SDK’s pinned runtime and verifies it.
TypeScript	`install(): Promise<void>`	`isInstalled(): boolean`	Downloads the package’s pinned runtime and verifies it.
Python	`install() -> None` (async)	`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.

Customize installation

Rust and TypeScript expose builders for custom install roots, versions, verification, and forced downloads. Go exposes WithSkipDownload() for pre-provisioned or air-gapped environments. Python’s setup helper uses the default installation behavior.

use microsandbox::setup::Setup;

Setup::builder()
    .base_dir("/opt/microsandbox")
    .version("0.6.8")
    .skip_verify(false)
    .force(true)
    .build()
    .install()
    .await?;

import { setup } from "microsandbox";

await setup()
  .baseDir("/opt/microsandbox")
  .version("0.6.8")
  .skipVerify(false)
  .force(true)
  .install();

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

// Do not download. Return an error if the runtime was not pre-provisioned.
if err := m.EnsureInstalled(ctx, m.WithSkipDownload()); err != nil {
    return err
}

Option	SDKs	Description
Install root	Rust: `base_dir(path)` TypeScript: `baseDir(path)`	Override `~/.microsandbox/`.
Runtime version	Rust: `version(version)` TypeScript: `version(version)`	Install a specific runtime version instead of the SDK’s pinned version.
Skip verification	Rust: `skip_verify(enabled)` TypeScript: `skipVerify(enabled)`	Skip post-install verification.
Force download	Rust: `force(enabled)` TypeScript: `force(enabled)`	Download again even when matching files are present.
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, and Python SDKs can override the process-wide libkrunfw path directly. Call the setter before creating a local sandbox.

use microsandbox::set_libkrunfw_path;

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

import { setRuntimeLibkrunfwPath } from "microsandbox";

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

from microsandbox import set_libkrunfw_path

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

Set these process-wide overrides before creating any local sandbox. They 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.

Getting Started

SDKs

CLI

Install and verify

Customize installation

Override runtime paths

Inspect Go versions

​Install and verify

​Customize installation

​Override runtime paths

​Inspect Go versions

Install and verify

Customize installation

Override runtime paths

Inspect Go versions