feat(sdk)!: redesign runtime bootstrap

[appcypher]

TL;DR

Redesign runtime distribution around explicit download-binaries and embed-binaries features. Resolve and install msb plus libkrunfw as one matched pair, while Agentd can be embedded at build time or supplied through MSB_AGENTD_PATH or global paths.agentd configuration at runtime.

Description

• Replace the prebuilt feature with separate acquisition and embedding controls across the Rust SDK, filesystem crate, runtime crate, CLI, workflows, and development recipes.
• Replace the legacy Rust setup::install and single-path resolvers with paired resolve_runtime, install_runtime, and ensure_runtime APIs that are read-only during resolution and fail closed on partial installations.
• Install downloaded or embedded runtime archives into the normal MSB_HOME/{bin,lib} layout, with locking, staged publication, optional digest verification, and no implicit runtime download during ordinary SDK sandbox creation.
• Add build-time runtime bundle inputs through MSB_EMBED_ARTIFACTS_DIR and MSB_EMBED_RUNTIME_BUNDLE_PATH.
• Add eager, validated Agentd selection through MSB_AGENTD_PATH and global paths.agentd, with the embedded payload as the default fallback when embed-binaries is enabled.
• Update the CLI wrapper, self-update flow, TypeScript, Python, and Ruby native bindings, documentation, and API compatibility tests for the new setup contract.

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

let runtime = ensure_runtime(&LocalConfig::default(), InstallOptions::default()).await?;
println!("msb: {}", runtime.msb_path.display());
println!("libkrunfw: {}", runtime.libkrunfw_path.display());

Test Plan

• cargo fmt --all -- --check
• MSB_AGENTD_PATH="$PWD/build/agentd" cargo test -p microsandbox-filesystem --no-default-features (621 passed)
• MSB_AGENTD_PATH="$PWD/build/agentd" cargo test -p microsandbox --lib --no-default-features --features keyring,net (617 passed, 3 ignored)
• MSB_EMBED_ARTIFACTS_DIR="$PWD/build" cargo test -p microsandbox --lib --no-default-features --features embed-binaries,keyring,net setup::runtime
• MSB_HOME=/tmp/msb-api-surface-home MSB_EMBED_ARTIFACTS_DIR="$PWD/build" cargo test -p microsandbox --test api_compat
• MSB_HOME=/tmp/msb-api-surface-home MSB_EMBED_ARTIFACTS_DIR="$PWD/build" cargo test -p microsandbox --lib setup::runtime::tests --features embed-binaries
• cargo check -p microsandbox --no-default-features --bin microsandbox
• Run focused clippy and compile checks for the CLI, filesystem, runtime, Rust SDK, Node native binding, and Python native binding; run npm run typecheck in sdk/node-ts
• Run the Linux, Windows ARM64/x64, and Ruby release lanes (runs in CI; the previous revision passed)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
microsandbox-staging	🟢 Ready	View Preview	Aug 24, 2026, 2:32 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[SDK or CLI requests local runtime] --> B[Resolve explicit environment or SDK package pair]
    B -->|Complete pair| C[Use matched msb and libkrunfw]
    B -->|No explicit pair| D[Check configured MSB_HOME]
    D -->|Complete pair| C
    D -->|Partial pair| E[Fail closed]
    D -->|Absent and explicit ensure/install| F[Select release, directory, archive, or embedded source]
    F --> G[Verify optional archive digest]
    G --> H[Acquire installation lock]
    H --> I[Stage both runtime files]
    I --> J[Publish libkrunfw then msb completion marker]
    J --> C
    K[MSB_AGENTD_PATH] --> L[Read and validate Agentd ELF]
    M[Embedded Agentd] --> L
    L --> N[Cache payload for guest bootstrap]

Loading

_{Reviews (1): Last reviewed commit: "feat(sdk)!: redesign runtime bootstrap" | Re-trigger Greptile}

[greptile-apps]

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[SDK or CLI] --> B{Resolve runtime pair}
    B -->|Complete configured install| C[Use msb and libkrunfw]
    B -->|Missing and installation requested| D{Runtime source}
    D -->|Release download| E[Download archive]
    D -->|Embedded archive| F[Read embedded bundle]
    D -->|Local archive or directory| G[Read local artifacts]
    E --> H[Validate optional digest]
    F --> I[Stage matched pair]
    G --> I
    H --> I
    I --> J[Publish under MSB_HOME bin and lib]
    J --> C
    C --> K{Select Agentd}
    K -->|MSB_AGENTD_PATH| L[External payload]
    K -->|paths.agentd| L
    K -->|Embedded fallback| M[Embedded payload]
    L --> N[Validate Linux ELF]
    M --> N
    N --> O[Spawn local sandbox runtime]

Loading

_{Reviews (2): Last reviewed commit: "feat(sdk): support configured agentd pat..." | Re-trigger Greptile}

[greptile-apps]

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[SDK or CLI startup] --> B{Agentd override configured?}
    B -->|Yes| C[Read and validate MSB_AGENTD_PATH]
    B -->|No| D{Embedded Agentd available?}
    D -->|Yes| E[Use embedded Agentd payload]
    D -->|No| F[Fail before VM construction]
    C --> G[Cache selected Agentd payload]
    E --> G
    A --> H[Resolve matched msb and libkrunfw pair]
    H --> I{Complete valid installation?}
    I -->|Yes| J[Start local runtime]
    I -->|No and ensure requested| K[Download or unpack staged runtime bundle]
    K --> L[Validate and publish bin/lib files]
    L --> J
    I -->|No and resolution only| M[Return setup error]
    G --> J

Loading

_{Reviews (3): Last reviewed commit: "fix(filesystem): validate embedded agent..." | Re-trigger Greptile}

[greptile-apps]

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[SDK or CLI] --> B{Runtime operation}
  B -->|Resolve| C[Check configured and installed paths]
  B -->|Ensure or install| D{Artifact source}
  D --> E[Embedded runtime bundle]
  D --> F[Downloaded runtime bundle]
  E --> G[Install matched msb and libkrunfw]
  F --> G
  G --> H[MSB_HOME bin and lib]
  A --> I{Agentd selection}
  I --> J[MSB_AGENTD_PATH]
  I --> K[Embedded Agentd fallback]
  H --> L[Local sandbox runtime]
  J --> L
  K --> L

Loading

_{Reviews (4): Last reviewed commit: "refactor(sdk): simplify runtime ensure o..." | Re-trigger Greptile}

[greptile-apps]

Too many files changed for review (190 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.