> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-appcypher-sdk-runtime-bootstrap.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CodeGroup>
  ```rust Rust theme={null}
  use microsandbox::{config::LocalConfig, setup::{InstallOptions, ensure_runtime}};

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

  ```typescript TypeScript theme={null}
  import { install, isInstalled } from "microsandbox";

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

  ```python Python theme={null}
  from microsandbox import install, is_installed

  if not is_installed():
      await install()
  ```

  ```go Go theme={null}
  import m "github.com/superradcompany/microsandbox/sdk/go"

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

  ```ruby Ruby theme={null}
  require "microsandbox"

  Microsandbox.install unless Microsandbox.installed?
  ```
</CodeGroup>

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

<CodeGroup>
  ```rust Rust theme={null}
  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?;
  ```

  ```typescript TypeScript theme={null}
  import { setup } from "microsandbox";

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

  ```go Go theme={null}
  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
  }
  ```
</CodeGroup>

| Option            | SDKs                                                                 | Description                                                                         |
| ----------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Install root      | Rust: `LocalConfig.home`<br />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`<br />TypeScript: `version(version)`   | Install a specific runtime version instead of the SDK's pinned version.             |
| Skip verification | Rust: `InstallOptions.verify`<br />TypeScript: `skipVerify(enabled)` | Skip post-install verification.                                                     |
| Force replacement | Rust: `InstallOptions.force`<br />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.                              |

<span id="go-with-skip-download" />

<span id="go-setupoption" />

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.

<CodeGroup>
  ```rust Rust theme={null}
  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");
  ```

  ```typescript TypeScript theme={null}
  import { setRuntimeLibkrunfwPath } from "microsandbox";

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

  ```python Python theme={null}
  from microsandbox import set_libkrunfw_path

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

  ```ruby Ruby theme={null}
  require "microsandbox"

  Microsandbox.set_runtime_libkrunfw_path("/opt/microsandbox/lib/libkrunfw.dylib")
  ```
</CodeGroup>

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:

```go theme={null}
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.