microsandbox-rb 0.5.9 → 0.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 045a5bf021edaf5afcfcf487cf0d980c38018560cc842c44018863570236f4ed
-  data.tar.gz: 25791e8bab4051711794cb8c1e08bbabc2b4dbc79bf080b02908b620ee0bd06e
+  metadata.gz: d4d9e8db2dddac7a22c2910c82a56603e95ad702d328c6a020f514997d29859c
+  data.tar.gz: 5f19089f8d1d0f18d5d930cf49576d25862f02323495ffa02db683f57a3439cd
 SHA512:
-  metadata.gz: 1b89148498194edb82241979432ee2e47599f2b657805b05718bfd18a8e1104318833ef84eb5f5e47a66f3cec8dc369f742897bbfe60cdb07fb613b597ef6ac5
-  data.tar.gz: c25b033291b4fb5195349030dcf2296006fa8b3563c7e1f6804441ed5e554e496583b22ddbca32828dff1b36127082b4cb1e995ab654573afc46b09e012031fd
+  metadata.gz: 88e44654909dd3f39ac23c6cf682bd62519bbaf7f57ca24f611a66e05bb66c825919fc1f2be6f9044513c99508bfedd412e5c72c1f15fc8b66c3ac11ee2b78ac
+  data.tar.gz: 00b0f44a4568107891a2ce9a623950245457ea51d0700f45333b96fec7eb73e6572b8b9b67b4147490423687fa1ff7dcb96b6edd29c2aa28c3ed22807eab7bdb

data/CHANGELOG.md

@@ -6,6 +6,83 @@ upstream microsandbox runtime.
 
 ## [Unreleased]
 
+## [0.5.10] - 2026-06-22
+
+### Added
+
+- **Streaming stdin pipe for `exec_stream`/`shell_stream`** (`stdin: :pipe`).
+  Opens a writable `ExecHandle#stdin` sink (`ExecStdin`) lifted out of the core
+  handle via `take_stdin`, distinct from the existing fixed-bytes `stdin:`
+  buffer. This is the load-bearing primitive for driving an interactive
+  long-running process (e.g. a `claude` CLI) over `exec_stream` from a host
+  reactor. The published `0.5.9` shipped without it (`stdin: :pipe` was fed as
+  the literal byte string `"pipe"`), so any consumer of the streaming sink must
+  require `>= 0.5.10`.
+
+Adopts the upstream **microsandbox `v0.5.8`** runtime (was `v0.5.7`), whose
+backend-routing rewrite (upstream PR #754) both adds new surface and reshapes the
+sandbox lifecycle.
+
+### Changed
+
+- **BREAKING — sandbox lifecycle split (mirrors the official Python/Node SDKs).**
+  Upstream `v0.5.8` split the lifecycle across a live `Sandbox` and a lightweight
+  `SandboxHandle`. The gem follows suit:
+  - The live `Microsandbox::Sandbox` (from `Sandbox.create`/`Sandbox.start`) now
+    exposes `#stop`, `#stop_and_wait`, `#kill`, `#drain`, `#wait`, `#status`,
+    `#detach`, and `#owns_lifecycle?`. `#stop` and `#kill` **no longer take a
+    `timeout:`** keyword; `#stop` performs the graceful SIGTERM→SIGKILL
+    escalation (10s default) the official SDKs use.
+  - `#request_stop`, `#request_kill`, `#request_drain`, `#wait_until_stopped`,
+    and a custom stop/kill timeout have **moved off** the live `Sandbox` onto the
+    controllable `Microsandbox::SandboxHandle` (see Added).
+- **BREAKING — `Sandbox.get`/`.list`/`.list_with` now return a controllable
+  `Microsandbox::SandboxHandle`** instead of a read-only `SandboxInfo`. The
+  handle keeps the same metadata accessors (`name`, `status`, `created_at`,
+  `updated_at`, `running?`, `stopped?`). `Microsandbox::SandboxInfo` remains as a
+  deprecated constant alias for `SandboxHandle`.
+- `SandboxStatus` gained two values, `:created` and `:starting` (cloud-only
+  today), so `#status` may now return them.
+
+### Added
+
+- **Backend routing** — `Microsandbox.set_default_backend(kind, url:, api_key:,
+  profile:)`, `Microsandbox.with_backend(kind, …) { … }` (a scoped, restoring
+  override), and `Microsandbox.default_backend_kind`. Without configuration the
+  runtime resolves a backend lazily from `MSB_BACKEND`, `MSB_API_URL` +
+  `MSB_API_KEY`, `MSB_PROFILE`, and `~/.microsandbox/config.json` (honoring
+  `MSB_CONFIG_PATH`). The cloud backend supports a documented subset
+  (create/start/stop/remove/get/list, one-shot exec, follow log streaming);
+  unsupported operations raise `UnsupportedError`. Under a cloud backend,
+  `Sandbox.create`/`.start` skip local `msb`/`libkrunfw` runtime provisioning
+  (it isn't needed), so cloud-only hosts no longer trigger a spurious download.
+- **`Microsandbox::SandboxHandle`** — the controllable handle returned by
+  `Sandbox.get`/`.list`/`.list_with`: `#stop`, `#stop_with_timeout(secs)`,
+  `#kill`, `#kill_with_timeout(secs)`, `#request_stop`, `#request_kill`,
+  `#request_drain`, `#wait_until_stopped` (→ `SandboxStopResult`), plus the
+  metadata accessors. Mirrors the official SDKs' `SandboxHandle`.
+- **`Sandbox#stop_and_wait` / `Sandbox#wait`** — return a `Microsandbox::ExitStatus`
+  (`#exit_code`, `#success?`). **`Sandbox#drain`** triggers a graceful drain.
+  **`Sandbox#status`** fetches the live status from the backend.
+- **`Microsandbox.libkrunfw_path=`** — overrides the `libkrunfw` shared-library
+  path (SDK tier of the resolver; `MSB_LIBKRUNFW_PATH` still wins). Mirrors
+  `runtime_path=`.
+- **`Microsandbox::CloudHttpError`** (`cloud-http`) and
+  **`Microsandbox::UnsupportedError`** (`unsupported`) — distinct from the
+  existing `UnsupportedOperationError`.
+
+### Fixed
+
+- **Reject invalid durations with a clear `ArgumentError`** — negative, `NaN`,
+  and infinite values passed to `timeout:` (`exec`/`shell`),
+  `SandboxHandle#stop_with_timeout`/`#kill_with_timeout`, `replace_with_timeout:`,
+  and `metrics_stream(interval:)` are rejected in Ruby before reaching the native
+  layer, where they would otherwise panic across the FFI boundary
+  (`Duration::from_secs_f64` panics on exactly those inputs).
+- **Reject contradictory `image:` + `from_snapshot:`** — `Sandbox.create` now
+  raises `ArgumentError` when both are given (a sandbox boots from exactly one
+  rootfs source), failing fast instead of after a runtime round-trip.
+
 ## [0.5.9] - 2026-06-18
 
 Closes the remaining roadmap items, bringing the binding surface to parity with

data/Cargo.lock

@@ -3003,8 +3003,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "anyhow",
  "astral-tokio-tar",
@@ -3031,6 +3031,7 @@ dependencies = [
  "microsandbox-network",
  "microsandbox-protocol",
  "microsandbox-runtime",
+ "microsandbox-types",
  "microsandbox-utils",
  "nix 0.31.3",
  "notify",
@@ -3047,6 +3048,7 @@ dependencies = [
  "tempfile",
  "thiserror 2.0.18",
  "tokio",
+ "tokio-tungstenite",
  "tracing",
  "typed-builder",
  "which",
@@ -3054,8 +3056,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-agent-client"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "ciborium",
  "microsandbox-protocol",
@@ -3067,8 +3069,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-db"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "async-trait",
  "sea-orm",
@@ -3079,8 +3081,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-filesystem"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "libc",
  "microsandbox-utils",
@@ -3092,8 +3094,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-image"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "astral-tokio-tar",
  "async-compression",
@@ -3118,8 +3120,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-metrics"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "chrono",
  "libc",
@@ -3129,8 +3131,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-migration"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "sea-orm-migration",
  "serde_json",
@@ -3138,8 +3140,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-network"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "base64",
  "bytes",
@@ -3178,11 +3180,12 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-protocol"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "chrono",
  "ciborium",
+ "microsandbox-types",
  "serde",
  "serde_bytes",
  "strum 0.28.0",
@@ -3192,19 +3195,21 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-runtime"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "bytes",
  "chrono",
  "clap",
  "crossbeam-queue",
  "libc",
+ "microsandbox-agent-client",
  "microsandbox-db",
  "microsandbox-filesystem",
  "microsandbox-metrics",
  "microsandbox-network",
  "microsandbox-protocol",
+ "microsandbox-types",
  "microsandbox-utils",
  "msb_krun",
  "nix 0.31.3",
@@ -3218,10 +3223,22 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "microsandbox-types"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+dependencies = [
+ "chrono",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "microsandbox-utils"
-version = "0.5.7"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.7#4dbb712bfd636f8964939a5317f749ba111e6a6d"
+version = "0.5.8"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
 dependencies = [
  "dirs",
  "libc",
@@ -3232,7 +3249,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.5.9"
+version = "0.5.10"
 dependencies = [
  "chrono",
  "futures",
@@ -3306,9 +3323,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5df0f4dbc4771ed8df8a7ed584221e48bc3fe1726242378332a02ce27518ca53"
+checksum = "72a554acf513be16b336fbcd4a9bab29a78b06a5ddf94e917481cfeafc1078f5"
 dependencies = [
  "crossbeam-channel",
  "kvm-bindings",
@@ -3326,9 +3343,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_arch"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "923b2f7ed0d299b37ea9bbc47e9d8fe1a46c44e1ecf1d9ecf306377b20f90762"
+checksum = "9d270d914cee3125cf71734b9a5aa60fe7d9648f09511999199424e0fe1a88c6"
 dependencies = [
  "kvm-bindings",
  "kvm-ioctls",
@@ -3342,15 +3359,15 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_arch_gen"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aff114cab67c406f051985749d7cd4aedab3fd445936f6759fd95de9c0352bb7"
+checksum = "8372d1e4e8c853e20ffb5568a4cc3f930a2bf1ce25bc346812ac7b84e84639d4"
 
 [[package]]
 name = "msb_krun_cpuid"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9f4a5cf30e814f211c32c43ee88e9a711ed0b17b88396a80baf5360f49ade848"
+checksum = "179542321455c65a8e4b14c09bc8443227a89cd46ef2c9c06f0ee1ab11f510ea"
 dependencies = [
  "kvm-bindings",
  "kvm-ioctls",
@@ -3359,9 +3376,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_devices"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "80f22c8cd187fc729c7f3b0922ae9e2e078809172f305dd343a6c4c71a219d68"
+checksum = "67350e76fd466e1a089b89fa548ba85a92f237c2d3dab179ba675cfd18eb9a39"
 dependencies = [
  "bitflags 1.3.2",
  "capng",
@@ -3387,9 +3404,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_hvf"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8c816c66f7eb6ccf751cb250a1c7ab0bc261cac6cef36ee68a8b673864ce5800"
+checksum = "13eaca12857149c3552007a18c7f863ccc6b4dddcf2863c0bcc8fbc2aa2d4c6e"
 dependencies = [
  "crossbeam-channel",
  "libloading",
@@ -3399,9 +3416,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_kernel"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "294eaf9998761721183f080866ddca635f3186da8541d2a273f60cf719ee92c3"
+checksum = "514f7493860978b08819fdcc4ef3d1887fd4d2b5e26ad0a0eabcec005410df94"
 dependencies = [
  "msb_krun_utils",
  "vm-memory 0.16.2",
@@ -3409,9 +3426,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_polly"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "778c4a9713517f131ae5b0c3e6c299a7e70ced97edeedd6e469639b9d7390fe2"
+checksum = "08ebbb0336b9cd8dcffa9c47d01a729de4f83c39fc099620f4f9c4d8ef69f460"
 dependencies = [
  "libc",
  "msb_krun_utils",
@@ -3419,18 +3436,18 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_smbios"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "775c50a8ab2688083eaf8636af96bed12974d5be9e5811e4c5665cea4fd06ff8"
+checksum = "f25cb991386c6aca7c74d0bd8b327a807290830e439fbb473c5e1b62a7c66d32"
 dependencies = [
  "vm-memory 0.16.2",
 ]
 
 [[package]]
 name = "msb_krun_utils"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0f620c8707cd19f6c67c004c2e80744a0bdab7349e18564ec982f8542712a375"
+checksum = "b7104f87f235ef5cc320ffa760b7cd3635960b58cdc5e1ec89df852fc538f042"
 dependencies = [
  "bitflags 1.3.2",
  "crossbeam-channel",
@@ -3443,9 +3460,9 @@ dependencies = [
 
 [[package]]
 name = "msb_krun_vmm"
-version = "0.1.16"
+version = "0.1.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb70c044c60e011e6f43c2e336687850b0910853a0efe37010e9649eff1395fe"
+checksum = "6742a7fba174849b924a370bfba0fe7be8435253bff26303aec34ac89641ae63"
 dependencies = [
  "bzip2",
  "crossbeam-channel",
@@ -6009,6 +6026,18 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -6151,6 +6180,22 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand 0.9.4",
+ "sha1 0.10.6",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "typed-builder"
 version = "0.23.2"

data/DESIGN.md

@@ -126,9 +126,13 @@ git. The override must never be committed — it would break container builds.
 ## Implemented surface (v1) vs roadmap
 
 **Implemented:** sandbox lifecycle (`create`/`start`/`get`/`list`/`list_with`/
-`remove`/`stop`/`kill`, the async `request_stop`/`request_kill`/`request_drain`/
-`wait_until_stopped` (→ `SandboxStopResult`) / `detach` / `owns_lifecycle?`
-controls, block form), `exec`/`shell` with collected `ExecOutput`,
+`remove`; the live `Sandbox` exposes `stop`/`stop_and_wait`/`kill`/`drain`/
+`wait` (→ `ExitStatus`) / `status` / `detach` / `owns_lifecycle?`, while the
+controllable `SandboxHandle` from `get`/`list` carries the fine-grained
+`stop_with_timeout`/`request_stop`/`request_kill`/`request_drain`/
+`wait_until_stopped` (→ `SandboxStopResult`) controls — the v0.5.8 live-vs-handle
+split that mirrors the official SDKs), backend routing (`set_default_backend`/
+`with_backend`/`default_backend_kind`), block form), `exec`/`shell` with collected `ExecOutput`,
 **streaming** `exec_stream`/`shell_stream` (`ExecHandle` is `Enumerable` over
 `ExecEvent`s, with stdin sink + signal/kill/resize), the full guest filesystem
 API (`fs.read`/`write`/`list`/`mkdir`/`remove`/`stat`/…), `metrics`,

data/README.md

@@ -4,7 +4,31 @@ Lightweight microVM sandboxes for Ruby — run AI agents and untrusted code with
 
 The `microsandbox-rb` gem provides native bindings to the [microsandbox](https://github.com/superradcompany/microsandbox) runtime via a Rust extension (magnus). It spins up real microVMs (not containers) in under 100 ms, runs standard OCI (Docker) images, and gives you full control over command execution, the guest filesystem, networking, and metrics — all from an idiomatic, **synchronous** Ruby API. There is no daemon to install and no server to connect to: the runtime is embedded directly in your process.
 
-This is an **unofficial, community-maintained** Ruby implementation — not part of the official SDK family ([Rust](https://github.com/superradcompany/microsandbox/tree/main/sdk), TypeScript, Python, Go) — though it wraps the same core engine.
+This is an **unofficial, community-maintained** Ruby implementation — not part of the official SDK family — though it wraps the same core engine.
+
+## Upstream & acknowledgements
+
+`microsandbox-rb` exists only because of the excellent work by the [Super Rad
+Company](https://github.com/superradcompany) team on the upstream
+**microsandbox** runtime. All the hard parts — the microVM engine, the guest
+`agentd`, the networking stack — are theirs; this gem is a thin Ruby skin over
+them. Our deepest thanks to the maintainers and community. 🙏
+
+- **Website & docs** — <https://microsandbox.dev> · [documentation](https://docs.microsandbox.dev)
+- **Official repository** — [superradcompany/microsandbox](https://github.com/superradcompany/microsandbox)
+- **Official SDKs** —
+  [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)
+- **Agents** — [Agent Skills](https://github.com/superradcompany/skills) · [MCP server](https://github.com/superradcompany/microsandbox-mcp)
+- **Community** — [Discord](https://discord.gg/T95Y3XnEAK)
+
+> **Not affiliated.** This gem is an independent, community-maintained project.
+> It is **not** built, endorsed, or supported by Super Rad Company or the
+> microsandbox team. Please don't direct questions about this gem to the
+> upstream project — open an issue here instead. **Contributions are very
+> welcome — PRs welcome!** See [Contributing](#contributing).
 
 ## Features
 
@@ -97,17 +121,33 @@ sb = Microsandbox::Sandbox.create("box", image: "public.ecr.aws/docker/library/a
 begin
   # ...
 ensure
-  sb.stop          # graceful (sb.stop(timeout: 5) to bound the wait)
-  # sb.kill        # force (SIGKILL)
+  sb.stop          # graceful (SIGTERM→SIGKILL escalation, 10s default)
+  # sb.stop_and_wait # graceful, then wait → ExitStatus(#exit_code, #success?)
+  # sb.kill          # force (SIGKILL); sb.drain for a graceful drain
 end
 
-# Inspect / manage existing sandboxes
-Microsandbox::Sandbox.list            # => [Microsandbox::SandboxInfo, ...]
-Microsandbox::Sandbox.get("box")      # => Microsandbox::SandboxInfo
+# Inspect / manage existing sandboxes. `get`/`list` return a controllable
+# SandboxHandle (the live `stop`/`kill`/`drain`/`wait` live on the object from
+# `create`/`start`; fine-grained control lives on the handle).
+Microsandbox::Sandbox.list            # => [Microsandbox::SandboxHandle, ...]
+h = Microsandbox::Sandbox.get("box")  # => Microsandbox::SandboxHandle
+h.status                              # :running, :stopped, :created, ...
+h.stop_with_timeout(5)                # custom escalation timeout
+h.request_stop                        # fire-and-return; pair with #wait_until_stopped
+h.request_kill
+h.request_drain
+h.wait_until_stopped                  # => Microsandbox::SandboxStopResult
 Microsandbox::Sandbox.start("box")    # restart a stopped sandbox
 Microsandbox::Sandbox.remove("box")   # remove a stopped sandbox
 ```
 
+> **v0.5.8 lifecycle change.** Upstream split the lifecycle into the live
+> `Sandbox` and a controllable `SandboxHandle`, and the gem mirrors it. The live
+> `Sandbox#stop`/`#kill` no longer take a `timeout:`; `#request_stop`/
+> `#request_kill`/`#request_drain`/`#wait_until_stopped` and a custom stop timeout
+> now live on the `SandboxHandle` from `Sandbox.get`. `Sandbox.get`/`.list` return
+> a `SandboxHandle` (was a read-only `SandboxInfo`, kept as a deprecated alias).
+
 ### Configuration
 
 ```ruby
@@ -197,8 +237,9 @@ Microsandbox::Sandbox.create("stream", image: "public.ecr.aws/docker/library/pyt
     print event.text if event.stdout?
   end
   # or: out = handle.collect  → ExecOutput  (drain to the end)
-  # interactive stdin:
-  #   sink = handle.stdin; sink.write("data\n"); sink.close
+  # interactive stdin — create the stream with stdin: :pipe to get a writable sink:
+  #   h = sb.exec_stream("cat", [], stdin: :pipe)
+  #   sink = h.stdin; sink.write("data\n"); sink.close  # close sends EOF
   # control: handle.signal(15), handle.kill, handle.resize(rows, cols)
 end
 ```
@@ -307,8 +348,32 @@ Microsandbox.installed?            # => true/false
 Microsandbox.install               # download + install the runtime (idempotent)
 Microsandbox.runtime_path          # => "/Users/you/.microsandbox/bin/msb"
 Microsandbox.runtime_path = "/opt/microsandbox/bin/msb"  # override
+Microsandbox.libkrunfw_path = "/opt/microsandbox/lib/libkrunfw.dylib"  # override (set-once)
+```
+
+### Backend routing
+
+As of v0.5.8 every operation runs through a backend. The default is the local
+libkrun backend; without any configuration nothing changes. A backend can be
+selected programmatically or via the environment:
+
+```ruby
+Microsandbox.default_backend_kind          # => :local (or :cloud)
+Microsandbox.set_default_backend(:cloud, url: "https://api.example.com", api_key: ENV["MSB_API_KEY"])
+# or a named profile from ~/.microsandbox/config.json:
+Microsandbox.set_default_backend(:cloud, profile: "prod")
+
+# Scoped override (restored afterward, even on error):
+Microsandbox.with_backend(:local) { Microsandbox::Sandbox.create("box", image: "alpine") { |sb| ... } }
 ```
 
+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
+operations (create/start/stop/remove/get/list, one-shot exec, follow log
+streaming); unsupported operations raise `Microsandbox::UnsupportedError`.
+
 ## Development
 
 ```bash
@@ -335,21 +400,9 @@ bundle exec rake compile
 ## Releasing
 
 Releases are automated by `.github/workflows/release.yml` via RubyGems
-**Trusted Publishing** (OIDC) — there is no API key to store as a secret.
-
-**One-time setup** (before the first release), create a *pending* trusted
-publisher at <https://rubygems.org/profile/oidc/pending_trusted_publishers>:
-
-| Field | Value |
-|-------|-------|
-| RubyGems gem name | `microsandbox-rb` |
-| Repository owner | `ya-luotao` |
-| Repository name | `microsandbox-rb` |
-| Workflow filename | `release.yml` |
-| Environment | *(leave blank)* |
-
-On the first successful push the pending publisher auto-converts to a permanent
-one bound to the gem.
+**Trusted Publishing** (OIDC) — there is no API key to store as a secret. The
+trusted publisher is already configured for this gem, so no per-release secret
+or credential setup is needed.
 
 **Each release:**
 
@@ -377,9 +430,12 @@ one bound to the gem.
 
 See [DESIGN.md](DESIGN.md) for the architecture and the implemented-surface
 section. The binding now covers the full official-SDK surface: sandbox
-lifecycle (including the async `request_stop`/`request_kill`/`request_drain`/
-`wait_until_stopped`/`detach`/`owns_lifecycle?` controls and label-filtered
-`list_with`), `exec`/`shell` (collected and streaming), interactive `attach`/
+lifecycle (the live `Sandbox` `stop`/`stop_and_wait`/`kill`/`drain`/`wait`/
+`status`/`detach`/`owns_lifecycle?`, plus the `SandboxHandle` controls
+`stop_with_timeout`/`request_stop`/`request_kill`/`request_drain`/
+`wait_until_stopped` from `Sandbox.get`, and label-filtered `list_with`),
+backend routing (`set_default_backend`/`with_backend`/`default_backend_kind`),
+`exec`/`shell` (collected and streaming), interactive `attach`/
 `attach_shell`, the full guest filesystem, metrics (per-sandbox,
 `Microsandbox.all_sandbox_metrics`, and streaming `metrics_stream`/`log_stream`),
 logs, OCI image-cache management, named volumes, snapshots (create/list/verify/
@@ -393,6 +449,15 @@ export/import + boot-from-snapshot), **rootfs patches** (`Microsandbox::Patch`),
 `registry_auth`/`registry_insecure`/`registry_ca_certs` for private and
 authenticated registries.
 
+## Contributing
+
+This is a community-maintained gem and **contributions are very welcome** —
+bug reports, fixes, docs, and feature work alike. Open an
+[issue](https://github.com/ya-luotao/microsandbox-rb/issues) or send a
+[pull request](https://github.com/ya-luotao/microsandbox-rb/pulls); PRs target
+`main`. Before pushing, run the local gate (Rust `fmt`/`clippy`, `standardrb`,
+and unit specs) — see [Development](#development).
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

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.5.7).
-version = "0.5.9"
+# The core-crate dependency below stays pinned at its own tag (v0.5.8).
+version = "0.5.10"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"
@@ -35,8 +35,8 @@ rb-sys = "0.9"
 # `.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.5.7", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.5.7" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.5.8", default-features = true, features = ["ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.5.8" }
 
 # Async core bridged to Ruby's synchronous API via a blocking tokio runtime.
 tokio = { version = "1", features = ["rt-multi-thread", "sync", "time"] }