microsandbox-rb 0.12.0 → 0.14.0

data/DESIGN.md

@@ -85,28 +85,106 @@ and the Rust→class mapping in `sdk/python/src/error.rs`.
 
 ## Runtime binary (`msb` + `libkrunfw`)
 
-The core crate's `prebuilt` feature (on by default) downloads the `msb` microVM
-runtime and `libkrunfw` firmware into `~/.microsandbox/{bin,lib}` **at build
-time** (`build.rs`). The path resolver checks, in order: `$MSB_PATH` →
-SDK-set path (`Microsandbox.runtime_path=`) → config file → workspace build →
-`~/.microsandbox/bin/msb` → `which msb`. `Microsandbox.install` / `.installed?`
-expose the core `setup::install`/`is_installed` for explicit, idempotent
-provisioning (mirrors the Python `install()`/`is_installed()`).
-
-Build-time provisioning only helps the **source gem**, where `build.rs` runs on
-the user's own machine. A **precompiled gem** is built in CI, so its build-time
-download lands on the CI host, not the user's — the user's `~/.microsandbox` is
-empty. `Microsandbox.ensure_runtime!` closes that gap: `Sandbox.create`/`start`
-call it to fetch the runtime on first use (by the *running* host's arch, which is
-always correct), at most once per process. `MICROSANDBOX_NO_AUTO_INSTALL` opts
-out (air-gapped hosts that provision out of band). libkrunfw is `dlopen`'d by
-`msb` at runtime and is never linked into the extension.
+The gem is **SDK-only**: nothing is provisioned while it is built or installed.
+The core crate's `prebuilt` feature — whose `build.rs` downloads the `msb`
+microVM runtime and `libkrunfw` firmware into `~/.microsandbox/{bin,lib}` at
+build time — is deliberately **off** (`default-features = false`, features
+`keyring`/`net`/`ssh`, the set the official SDKs ship). Build-time provisioning
+only ever helped the source gem: for a precompiled gem the download lands on the
+CI host, and even for a source install it couples "compile a Ruby extension" to
+"fetch 50 MB of host binaries", which is not the compiler's business.
+
+The *guest* agent is a different story and is still embedded at build time: the
+`agentd` binary that runs as PID 1 inside every microVM is `include_bytes!`-d
+into the extension by `microsandbox-filesystem`'s `build.rs`, keyed by *target*
+arch. Without its `prebuilt` feature that build script demands a locally built
+`build/agentd` (workspace-only), so `ext/microsandbox/Cargo.toml` enables exactly
+that one sub-feature through a direct `microsandbox-runtime` dependency
+(`default-features = false, features = ["prebuilt"]`, whose `prebuilt` is just
+`microsandbox-filesystem/prebuilt`) while the SDK-level host download stays off.
+
+### The companion gem
+
+The host runtime ships as its own gem, **`microsandbox-rb-binaries`** (source in
+`binaries/`), one platform gem per `arm64-darwin` / `x86_64-linux-gnu` /
+`aarch64-linux-gnu` (Linux binaries are glibc-linked, hence
+`required_rubygems_version >= 3.3.11`). It carries `vendor/bin/msb`,
+`vendor/lib/libkrunfw.*` and a `vendor/manifest.json` — a layout that mirrors
+both the upstream release bundle and `~/.microsandbox`, so the core finds the
+firmware by `../lib` adjacency to `msb` and only the binary path needs handing
+over (same trick as the Python and Node SDKs). Everything is downloaded from the
+upstream GitHub release named by `Microsandbox::Binaries::RUNTIME_VERSION` and
+sha256-verified fail-closed against that release's `checksums.sha256` — the copy
+committed as `binaries/checksums/<tag>.sha256` when the runtime was adopted
+(a GitHub release is mutable, so the live file must agree with the reviewed
+one, not replace it) — at vendoring time; the gem build re-verifies the staged
+tree against the manifest (regular files only), so nothing unverified is ever
+packaged. Build pipeline:
+`rake -C binaries vendor[<platform>] build[<platform>] verify`.
+
+There is **no dependency edge in either direction**. RubyGems has no optional
+dependencies, and cloud-only users (`MSB_BACKEND=cloud`) must not be forced to
+download ~50 MB of binaries they will never execute — so the SDK discovers the
+companion gem instead of depending on it, and the companion gem stays a pure
+payload. The two are versioned in lockstep (`Binaries::VERSION` ==
+`Microsandbox::VERSION`, `Binaries::RUNTIME_VERSION` == `RUNTIME_VERSION`, both
+asserted by `spec/unit/version_spec.rb`).
+
+### Activation and the resolver ladder
+
+`lib/microsandbox.rb` runs a private `activate_bundled_runtime!` once, at
+`require "microsandbox"` time: `gem "microsandbox-rb-binaries", "= VERSION"`
+(pins the lockstep version when RubyGems, not Bundler, picks the gem; a failure
+here is tolerated) → `require "microsandbox/binaries"` (`LoadError` → the tier is
+simply absent, silently) → `Binaries::VERSION` must equal `VERSION` and
+`Binaries::RUNTIME_VERSION` must equal `RUNTIME_VERSION` (the `gem` pin above
+cannot enforce lockstep: under Bundler it raises whenever the bundle picked any
+other version, and that is swallowed) **and** both `msb_path` and
+`libkrunfw_path` must exist →
+`Native.set_runtime_msb_path(msb)`. The version gate is the load-bearing part: a
+runtime from a different upstream release passes any exists-check and then fails
+every `create` on a wire-protocol mismatch, so a mismatch is reported with a
+warning and skipped rather than handed to the core. The whole path is
+non-raising — a broken companion gem must never take `require "microsandbox"`
+down with it.
+
+Activation is **eager** rather than lazy, mirroring the Node SDK (`napi.ts`
+pushes its platform package's `msb` into the same set-once slot at module load).
+A lazy hook inside `ensure_runtime!` would only cover `Sandbox.create`/`start`
+and silently miss every other entry point that resolves or spawns `msb`.
+
+The resolver order is therefore: `$MSB_PATH` → SDK-set path (claimed by the
+companion gem at load; `Microsandbox.runtime_path=` targets this same set-once
+slot, so with the gem installed the setter is a **no-op** — override via
+`MSB_PATH`) → config file → workspace build → `~/.microsandbox/bin/msb` →
+`which msb`. `Microsandbox.runtime_path` reports the winner.
+`Microsandbox.install` / `.installed?` expose the core `setup::install`/
+`is_installed` for explicit, idempotent provisioning (mirrors the Python
+`install()`/`is_installed()`).
+
+Auto-provisioning stays as the **lowest tier**, deliberately (npx-style
+first-use download; see upstream discussion
+[superradcompany/microsandbox#1305](https://github.com/superradcompany/microsandbox/issues/1305)):
+`Sandbox.create`/`start` call `Microsandbox.ensure_runtime!`, which fetches a
+missing or version-stale runtime into `~/.microsandbox` on first use — by the
+*running* host's arch, which is always correct — at most once per process.
+`MICROSANDBOX_NO_AUTO_INSTALL` opts out (air-gapped hosts that provision out of
+band). When the companion gem won the resolver (`bundled_runtime_active?`),
+`ensure_runtime!` returns immediately: those binaries are already the matching
+version, so nothing is downloaded or touched in `~/.microsandbox`. Note the
+asymmetry in trust: the companion gem's payload is digest-verified when it is
+vendored, while the first-use download is not yet content-verified (pending
+upstream
+[superradcompany/microsandbox#1300](https://github.com/superradcompany/microsandbox/issues/1300)).
+
+libkrunfw is `dlopen`'d by `msb` at runtime and is never linked into the
+extension.
 
 ## Core-crate dependency (self-contained)
 
 `ext/microsandbox/Cargo.toml` depends on the core crate via a **pinned git tag**
 (`microsandbox` / `microsandbox-network`, pinned to the same tag as
-`Microsandbox::RUNTIME_VERSION` — currently `v0.6.2`), so the gem builds anywhere
+`Microsandbox::RUNTIME_VERSION` — currently `v0.6.9`), so the gem builds anywhere
 — CI, `rake-compiler-dock` release containers, and end-user source installs —
 without an adjacent checkout. For fast local development against a sibling
 microsandbox checkout, copy `.cargo/config.toml.example` to `.cargo/config.toml`
@@ -122,7 +200,8 @@ git. The override must never be committed — it would break container builds.
   (`rake-compiler-dock`) per `Gem::Platform`, shipping multi-ABI
   `lib/microsandbox/<ruby_abi>/` native artifacts — the same model Node uses with
   per-platform packages. End users then install with no Rust toolchain, and the
-  runtime is fetched on first use (see above). The guest `agentd` is baked into
+  host runtime comes from the `microsandbox-rb-binaries` gem — or, without it, is
+  fetched on first use (see above). The guest `agentd` is baked into
   the extension by *target* arch (`filesystem/build.rs` uses
   `CARGO_CFG_TARGET_ARCH` + `include_bytes!`), so it cross-compiles correctly;
   the real cross work is linking the *target* native libs — `libcap-ng` on Linux
@@ -133,6 +212,16 @@ git. The override must never be committed — it would break container builds.
   since CI can't boot a microVM to prove a built gem actually works, gems are
   promoted to the publish path manually after per-platform validation. Published
   to RubyGems via Trusted Publishing (OIDC). See [Releasing](README.md#releasing).
+* **Runtime binaries gems** (`microsandbox-rb-binaries`): a distinct artifact
+  from the precompiled *extension* gems above — no Ruby code beyond a small
+  locator module, just the verified upstream `msb` + `libkrunfw` for one
+  platform. CI's `binaries` job vendors and builds all three platforms on every
+  run and smoke-tests the host one; the `package` job installs the source gem
+  together with the host binaries gem and asserts `Microsandbox.runtime_path`
+  resolves into it, and the real-microVM integration job runs twice — once
+  against a `~/.microsandbox` provision (the fallback tier) and once booting from
+  the gem's vendored runtime. Publishing them is a follow-up (it needs a pending
+  trusted publisher on rubygems.org) and lands with the next release.
 
 ## Build requirements
 

data/README.md

@@ -20,7 +20,13 @@ them. Our deepest thanks to the maintainers and community. 🙏
   [Rust](https://github.com/superradcompany/microsandbox/tree/main/sdk) ·
   [Python](https://github.com/superradcompany/microsandbox/tree/main/sdk/python) ·
   [TypeScript / Node](https://github.com/superradcompany/microsandbox/tree/main/sdk/node-ts) ·
-  [Go](https://github.com/superradcompany/microsandbox/tree/main/sdk/go)
+  [Go](https://github.com/superradcompany/microsandbox/tree/main/sdk/go) ·
+  [Ruby](https://github.com/superradcompany/microsandbox/tree/main/sdk/ruby)
+  (since upstream `v0.6.9` there is an **official** `microsandbox` gem — a
+  compact veneer over the same Rust SDK. This gem predates it and covers a
+  larger surface (snapshots, SSH, streaming, volumes fs, network policy DSL,
+  RBS types); both define the `Microsandbox` module, so use one or the other,
+  not both, in a single process.)
 - **Agents** — [Agent Skills](https://github.com/superradcompany/skills) · [MCP server](https://github.com/superradcompany/microsandbox-mcp)
 - **Community** — [Discord](https://discord.gg/T95Y3XnEAK)
 
@@ -52,6 +58,10 @@ them. Our deepest thanks to the maintainers and community. 🙏
 - A **Rust** toolchain (stable >= 1.91) — needed only when installing the source
   gem (it compiles the native extension on install). Precompiled per-platform
   gems, where available, require no Rust toolchain; see [Releasing](#releasing)
+- The **`msb` runtime + `libkrunfw` firmware** — shipped by the optional
+  companion gem `microsandbox-rb-binaries`, or downloaded into `~/.microsandbox`
+  on first use; see [The runtime binaries](#the-runtime-binaries). Cloud-only
+  users (`MSB_BACKEND=cloud`) need no local runtime at all
 
 ## Installation
 
@@ -74,17 +84,49 @@ takes a few minutes and needs a Rust toolchain (`rustc >= 1.91`) on `PATH`. When
 a **precompiled platform gem** is available for your OS/architecture, RubyGems
 picks it automatically and no Rust toolchain is required.
 
-Either way the `msb` runtime and `libkrunfw` firmware are provisioned into
-`~/.microsandbox` automatically on first use (the first `Sandbox.create`/`start`
-downloads them if missing). To provision ahead of time — e.g. while baking a
-container image, or to avoid the first-call latency — call `install` explicitly:
+### The runtime binaries
+
+`microsandbox-rb` is **SDK-only** — it wraps the microVM runtime, it doesn't
+carry it. The host-side `msb` runtime and the `libkrunfw` firmware come from an
+optional companion gem, **`microsandbox-rb-binaries`**, published as one gem per
+platform (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`) and
+versioned in lockstep with this gem:
+
+```ruby
+# Gemfile — install both gems at the same version
+gem "microsandbox-rb", require: "microsandbox"
+gem "microsandbox-rb-binaries"
+```
+
+That's all the wiring there is: `require "microsandbox"` finds the companion
+gem, checks it is the same version and built for the same upstream runtime, and points the resolver
+at its vendored `msb` — so your bundle carries the runtime and nothing is
+downloaded at install time or on first call. **Recommended whenever you boot
+local microVMs.** Cloud-only users (`MSB_BACKEND=cloud`) should skip it: it is a
+separate, optional gem precisely so nobody has to fetch ~50 MB of binaries they
+won't run. Neither gem depends on the other.
+
+> **Availability.** The binaries gems are published on every release tag
+> alongside `microsandbox-rb` (first release to ship them: the one after
+> 0.13.0). On an older SDK version, or a platform without a bundle, use the
+> fallback below (or build them yourself from `binaries/` — see that
+> directory's README).
+
+**Fallback — first-use download.** Without the companion gem, the `msb` runtime
+and `libkrunfw` firmware are provisioned into `~/.microsandbox` automatically on
+first use (the first `Sandbox.create`/`start` downloads them if missing). To
+provision ahead of time — e.g. while baking a container image, or to avoid the
+first-call latency — call `install` explicitly:
 
 ```ruby
 Microsandbox.install unless Microsandbox.installed?
 ```
 
 Set `MICROSANDBOX_NO_AUTO_INSTALL` to disable the automatic first-use download
-(e.g. on air-gapped hosts that provision the runtime out of band).
+(e.g. on air-gapped hosts that provision the runtime out of band). None of this
+applies when the companion gem supplies the runtime: its binaries are already the
+matching version, so `ensure_runtime!` skips the installer entirely and nothing
+is written to `~/.microsandbox`.
 
 ## Quick start
 
@@ -193,6 +235,22 @@ end
 A non-zero exit is **not** an error — inspect `exit_code`/`success?`. Spawn-time
 failures (e.g. command not found) and timeouts raise typed errors (see below).
 
+**Default workload** (runtime `v0.6.9`): `create` is strictly boot-only — it
+never runs the image's `ENTRYPOINT`/`CMD`. Execute the image's own command
+explicitly:
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "example/worker:latest",
+  cmd: ["worker.py", "--once"]) do |sb|   # cmd: overrides the durable image CMD
+  out = sb.exec_default(timeout: 300)     # buffered; exec-style options
+  handle = sb.exec_default_stream         # or streaming (returns an ExecHandle)
+  sb.attach_default                       # or interactive (host TTY)
+end
+```
+
+An image whose entrypoint and CMD resolve to no executable command raises
+`Microsandbox::NoDefaultCommandError`.
+
 ### Guest filesystem
 
 ```ruby
@@ -256,6 +314,10 @@ Microsandbox::Sandbox.create("live", image: "public.ecr.aws/docker/library/alpin
   # Live resize — applies to the running VM under the default :no_restart policy:
   sb.modify(cpus: 2, memory: 1024)
 
+  # Grow the root disk (managed upper or flat, MiB — runtime v0.6.9). Applied
+  # while stopped; growth-only:
+  sb.modify(root_disk_size: 8192, policy: :next_start)
+
   # env/labels/workdir changes on a *running* sandbox require a restart, so the
   # default :no_restart policy rejects the whole apply (it raises rather than
   # partially applying). Persist them for the next start — or restart now —
@@ -402,8 +464,9 @@ end
 ## Runtime configuration
 
 The `msb` runtime path is resolved in this order: the `MSB_PATH` environment
-variable → an SDK-set override → the config file → `~/.microsandbox/bin/msb` →
-`msb` on `PATH`.
+variable → the `microsandbox-rb-binaries` gem (or another SDK-set override) →
+the config file → `~/.microsandbox/bin/msb` → `msb` on `PATH`.
+`Microsandbox.runtime_path` reports the winner.
 
 ```ruby
 Microsandbox.installed?            # => true/false
@@ -413,6 +476,16 @@ Microsandbox.runtime_path = "/opt/microsandbox/bin/msb"  # override (set-once)
 Microsandbox.libkrunfw_path = "/opt/microsandbox/lib/libkrunfw.dylib"  # override (set-once)
 ```
 
+When [`microsandbox-rb-binaries`](#the-runtime-binaries) is installed,
+`require "microsandbox"` claims that SDK-set slot with the gem's vendored `msb`
+(the firmware is found alongside it), and `runtime_path` points into the gem.
+The two gems are versioned in lockstep and the companion gem must be the same
+version **and** built for the same upstream runtime — a mismatch of either is reported with a warning and
+skipped, and the SDK falls back to `~/.microsandbox` rather than driving a
+runtime it doesn't match. Because the slot is **set-once**,
+`Microsandbox.runtime_path=` is then a no-op: use the `MSB_PATH` environment
+variable, which outranks it, to point at a different runtime.
+
 ### Backend routing
 
 As of v0.5.8 every operation runs through a backend. The default is the local
@@ -430,9 +503,15 @@ Microsandbox.with_backend(:local) { Microsandbox::Sandbox.create("box", image: "
 ```
 
 Resolution order when no backend is set programmatically: `MSB_BACKEND`
-(`local`/`cloud`) → `MSB_API_URL` + `MSB_API_KEY` → `MSB_PROFILE` → the
-`active_profile` in `~/.microsandbox/config.json` (path overridable via
-`MSB_CONFIG_PATH`) → local. The cloud backend currently supports a subset of
+(`local`/`cloud`) → `MSB_PROFILE` → the `active_profile` in
+`~/.microsandbox/config.json` (path overridable via `MSB_CONFIG_PATH`) →
+local. **Cloud intent must be explicit** (since runtime `v0.6.9`): a bare
+`MSB_API_KEY` is treated as credential material, not backend intent, and no
+longer selects the cloud on its own — pair it with `MSB_BACKEND=cloud` (which
+reads `MSB_API_URL`/`MSB_API_KEY`), or select a cloud profile. Invalid cloud
+configuration (e.g. `MSB_BACKEND=cloud` without a usable API key or cloud
+profile) fails closed with `Microsandbox::InvalidConfigError` instead of
+silently running locally. The cloud backend currently supports a subset of
 operations (create/start/stop/remove/get/list, one-shot exec, follow log
 streaming); unsupported operations raise `Microsandbox::UnsupportedError`.
 
@@ -445,10 +524,17 @@ change diverged the two numbers — the gem version is **not** a reliable indica
 of the embedded runtime version. To learn which runtime a build wraps, ask it:
 
 ```ruby
-Microsandbox::VERSION          # => "0.12.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.6.8"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.13.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.6.9"  (the embedded upstream runtime tag)
 ```
 
+The companion [`microsandbox-rb-binaries`](#the-runtime-binaries) gem is
+versioned in **lockstep** with this gem (same number, released together) and
+pins the same upstream runtime — install both at the same version. The gem's
+`Microsandbox::Binaries::VERSION` and `::RUNTIME_VERSION` are asserted against
+this gem's constants by the test suite, so a companion gem can't silently go
+stale.
+
 | Gem version | Upstream runtime | Notes |
 |-------------|------------------|-------|
 | `0.5.7`  | `v0.5.7` | initial release |
@@ -469,6 +555,8 @@ Microsandbox.runtime_version   # => "v0.6.8"  (the embedded upstream runtime tag
 | `0.10.0` | `v0.6.6` | `v0.6.6` API parity: live `modify`/resize, `ping`/`touch`, create `max_cpus`/`max_memory` |
 | `0.11.0` | `v0.6.7` | adopts upstream `v0.6.7` (**breaking**): network profiles replace `public_only`/`non_local`, structured `root_disk:` replaces `oci_upper_size:` (deprecated alias kept), snapshot descriptor contract (`create` re-keyed by name, `save`/`load` rename, `snapshot_to` removed, on-disk auto-migration), `Image.load`/`Image.save`, `follow_root_symlinks:`; runtime carries the GHSA-4vq3-cjpp-v7fg `msb copy` fix |
 | `0.12.0` | `v0.6.8` | adopts upstream `v0.6.8` (**breaking**): `Sandbox.list`/`.list_with` return a cursor-paginated `SandboxPage` (`limit:`/`cursor:` keywords), `UnsupportedError` re-keyed by structured operations with `#operation`/`#hint`; runtime adds a shared log registry for followed streams and cloud exec/ssh reconnects |
+| `0.13.0` | `v0.6.9` | adopts upstream `v0.6.9` (**breaking**): a bare `MSB_API_KEY` no longer selects the cloud backend (explicit `MSB_BACKEND=cloud` or a cloud profile required; invalid cloud config fails closed with `InvalidConfigError`); snapshot payload integrity becomes opt-in (`record_integrity:`, `verify` can report `:not_recorded`). Parity: default-workload execution (`exec_default`/`exec_default_stream`/`attach_default`, `cmd:`), flat root disks (`RootDisk.flat`), `modify(root_disk_size:)`, `rate_limiter:`, `vsock:`, `default_backend_info`, `Volume.get_default` |
+| `0.14.0` | `v0.6.9` | two-gem split: SDK-only gem (no build-time runtime download) + companion `microsandbox-rb-binaries` platform gems |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:
@@ -522,7 +610,11 @@ or credential setup is needed.
    the number to mirror the upstream tag. If the release also adopts a new upstream
    runtime, bump the `tag = "vX.Y.Z"` on **both** the `microsandbox` and
    `microsandbox-network` git deps, update `Microsandbox::RUNTIME_VERSION` to match,
-   and add a row to the Versioning table. Update `CHANGELOG.md`.
+   and add a row to the Versioning table. Also bump
+   `Microsandbox::Binaries::VERSION` (and, on a runtime adoption,
+   `::RUNTIME_VERSION`) in `binaries/lib/microsandbox/binaries.rb` — the
+   companion gem ships in lockstep and the specs assert both. Update
+   `CHANGELOG.md`.
 2. Push a `vX.Y.Z` tag. CI builds the **source gem** and pushes it to RubyGems
    via `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
    `RUBYGEMS_API_KEY` secret required.
@@ -535,13 +627,29 @@ or credential setup is needed.
 > prove otherwise — so promotion is manual after validating the artifact on each
 > platform. A precompiled gem ships the compiled extension (with the guest
 > `agentd` baked in by *target* arch); the host-side `msb` + `libkrunfw` runtime
-> is fetched into `~/.microsandbox` on first use by `Microsandbox.ensure_runtime!`
-> (libkrunfw is `dlopen`'d by `msb` at runtime, never linked into the gem). The
+> is **not** in it — that comes from the companion `microsandbox-rb-binaries`
+> gem, or, when that isn't installed, is fetched into `~/.microsandbox` on first
+> use by `Microsandbox.ensure_runtime!` (libkrunfw is `dlopen`'d by `msb` at
+> runtime, never linked into the gem). The
 > real cross-compile work is linking the *target* native libraries — `libcap-ng`
 > on Linux (handled via Debian multiarch in the workflow) and the Hypervisor +
 > Security frameworks on macOS (via osxcross; the one platform left to confirm).
 > Until promoted, users install the source gem (which compiles via `rb_sys`).
 
+> **Runtime binaries gems** (`microsandbox-rb-binaries`, source in `binaries/`)
+> are a *separate* artifact from the precompiled extension gems above: they carry
+> no Ruby extension, only the upstream `msb` + `libkrunfw` for one platform,
+> verified against the release's published `checksums.sha256` when vendored. CI's
+> `binaries` job vendors and builds all three (`arm64-darwin`,
+> `x86_64-linux-gnu`, `aarch64-linux-gnu`) on every run and smoke-tests the host
+> one; `release.yml`'s `binaries-gems` job does the same on a tag and a separate
+> `publish-binaries` job pushes them after the SDK gem is live (a companion
+> failure is its own red job and never blocks the SDK release).
+> They use their own RubyGems trusted-publisher entry (same repo + workflow,
+> gem name `microsandbox-rb-binaries`). To build them by hand:
+> `rake -C binaries vendor[<platform>]` then `rake -C binaries build[<platform>]`
+> (→ `binaries/pkg/*.gem`).
+
 See [DESIGN.md](DESIGN.md) for the architecture and the implemented-surface
 section. The binding covers the official-SDK surface: sandbox
 lifecycle (the live `Sandbox` `stop`/`stop_and_wait`/`kill`/`drain`/`wait`/

data/ext/microsandbox/Cargo.toml

@@ -6,8 +6,8 @@ name = "microsandbox_rb"
 description = "Ruby SDK native extension for microsandbox — secure, fast microVM-based sandboxing."
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
-# The core-crate dependency below stays pinned at its own tag (v0.6.7).
-version = "0.12.0"
+# The core-crate dependency below stays pinned at its own tag (v0.6.9).
+version = "0.14.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -32,11 +32,27 @@ rb-sys = "0.9"
 # gem is self-contained and buildable anywhere (CI, release containers, end-user
 # source installs) without an adjacent checkout. For local development against a
 # sibling checkout, use the `paths` override in `.cargo/config.toml` (see
-# `.cargo/config.toml.example`). "ssh" matches the feature set the Python/Node
-# SDKs ship with; default features add "prebuilt" (provisions msb + libkrunfw at
-# build time), "net", and "keyring".
-microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.8", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.8" }
+# `.cargo/config.toml.example`).
+#
+# Features are listed explicitly (default-features = false) so the SDK crate's
+# own "prebuilt" feature stays OFF: that feature makes its build.rs download
+# the msb + libkrunfw *host runtime* into ~/.microsandbox at compile time. This
+# gem is SDK-only — the host runtime comes from the companion
+# `microsandbox-rb-binaries` gem (see binaries/) or, as the lowest tier, the
+# first-use download into ~/.microsandbox (`setup::install`, which is not
+# gated on "prebuilt"). "net"/"ssh"/"keyring" are the features the official
+# SDKs ship with.
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9", default-features = false, features = ["keyring", "net", "ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9" }
+# The *guest* agent (`agentd`, PID 1 inside every microVM) is embedded into the
+# extension by microsandbox-filesystem's build.rs, which without its "prebuilt"
+# feature demands a locally built `build/agentd` (workspace-only, `just
+# build-deps`). Enable that one sub-feature directly — via microsandbox-runtime,
+# whose "prebuilt" is exactly `microsandbox-filesystem/prebuilt` — so the
+# prebuilt agentd for the target arch is fetched (same behaviour as before)
+# while the SDK-level msb download above stays off. Feature unification means
+# this adds no new crates; keep it on the same tag as the deps above.
+microsandbox-runtime = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9", default-features = false, features = ["prebuilt"] }
 
 # Async core bridged to Ruby's synchronous API via a blocking tokio runtime.
 tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }

data/ext/microsandbox/src/backend.rs

@@ -159,10 +159,32 @@ fn default_backend_kind() -> String {
     .to_string()
 }
 
+/// Secret-safe description of the active default backend (v0.6.9):
+/// {kind, api_url, source, profile}. `source` names what selected the backend
+/// (e.g. "MSB_BACKEND", "programmatic", "default"); the API key is never
+/// included. Like `default_backend_kind`, the first call freezes ambient
+/// env/profile resolution for the process.
+fn default_backend_info() -> magnus::RHash {
+    let info = microsandbox::default_backend_info();
+    let hash = crate::runtime::ruby().hash_new();
+    let _ = hash.aset(
+        "kind",
+        match info.kind {
+            microsandbox::BackendKind::Local => "local",
+            microsandbox::BackendKind::Cloud => "cloud",
+        },
+    );
+    let _ = hash.aset("api_url", info.api_url);
+    let _ = hash.aset("source", info.source.as_str());
+    let _ = hash.aset("profile", info.profile);
+    hash
+}
+
 pub fn define(_ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     native.define_singleton_method("set_default_backend", function!(set_default_backend, 4))?;
     native.define_singleton_method("push_default_backend", function!(push_default_backend, 4))?;
     native.define_singleton_method("pop_default_backend", function!(pop_default_backend, 1))?;
     native.define_singleton_method("default_backend_kind", function!(default_backend_kind, 0))?;
+    native.define_singleton_method("default_backend_info", function!(default_backend_info, 0))?;
     Ok(())
 }

data/ext/microsandbox/src/error.rs

@@ -60,6 +60,10 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         // unconditionally enables the core's `net` feature (default-features),
         // so this variant is always present.
         NetworkBuilder(_) => "NetworkPolicyError",
+        // v0.6.9: `exec_default`/`attach_default` on an image whose resolved
+        // ENTRYPOINT+CMD provide no executable command. Mirrors the Python
+        // SDK's `NoDefaultCommandError`.
+        NoDefaultCommand => "NoDefaultCommandError",
         _ => "Error",
     }
 }