> ## Documentation Index
> Fetch the complete documentation index at: https://microsanbox-staging-toks-cloud-snapshot-contracts.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 you can use to verify the runtime before creating your 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.

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

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

  ```rust Rust theme={null}
  use microsandbox::setup;

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

  ```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                                                                          |
| ---------- | -------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
| TypeScript | `install(): Promise<void>`                   | `isInstalled(): boolean`        | Downloads the package's pinned runtime and verifies it.                           |
| Rust       | `setup::install() -> MicrosandboxResult<()>` | `setup::is_installed() -> bool` | Downloads the SDK'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       | `Microsandbox.install`                       | `Microsandbox.installed?`       | Installs and verifies the runtime used by the native extension.                   |

## Customize installation

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

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

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

  ```rust Rust theme={null}
  use microsandbox::setup::Setup;

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

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

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

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

  ```rust Rust theme={null}
  use microsandbox::set_libkrunfw_path;

  set_libkrunfw_path("/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. |

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:

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