microsandbox-rb 0.5.8 → 0.5.10

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
 
@@ -14,6 +38,10 @@ This is an **unofficial, community-maintained** Ruby implementation — not part
 - **Command execution** — run commands or shell scripts and collect output
 - **Guest filesystem access** — read, write, list, copy, stat files inside a running sandbox
 - **Metrics & logs** — CPU, memory, disk and network I/O; captured stdout/stderr/system logs
+- **Rootfs patches** — inject files, dirs, and symlinks into the image before boot (`Microsandbox::Patch`)
+- **Fine-grained networking** — policy presets *and* custom CIDR/domain/group allow-deny rules (`Microsandbox::NetworkPolicy`)
+- **SSH & SFTP** — native in-process SSH client/server and file transfer (`Sandbox#ssh`)
+- **Raw agent client** — byte-level access to the guest `agentd` protocol (`Microsandbox::AgentClient`)
 - **Idiomatic Ruby** — keyword arguments, block-scoped lifecycle, a typed error hierarchy
 - **Thread-friendly** — the GVL is released during sandbox calls, so other Ruby threads keep running
 
@@ -93,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
@@ -193,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
 ```
@@ -303,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
@@ -331,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:**
 
@@ -372,19 +429,34 @@ one bound to the gem.
 > Until promoted, users install the source gem (which compiles via `rb_sys`).
 
 See [DESIGN.md](DESIGN.md) for the architecture and the implemented-surface
-section for what's covered today vs. on the roadmap. Covered: full 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), the full guest
-filesystem, metrics (per-sandbox, `Microsandbox.all_sandbox_metrics`, and
-streaming `metrics_stream`/`log_stream`), logs, OCI image-cache management,
-named volumes, and snapshots (create/list/verify/export/import +
-boot-from-snapshot). Create options span resources, network policy presets,
-`log_level`/`security`/`rlimits`/`pull_policy`/`secrets` and more; `exec`/`shell`
-take per-call `rlimits`, and `create` accepts `registry_auth`/`registry_insecure`/
-`registry_ca_certs` for private and authenticated registries. Still on the
-roadmap: custom per-rule network policies, file patches, interactive `attach`,
-SSH, and the raw agent client.
+section. The binding now covers the full official-SDK surface: sandbox
+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/
+export/import + boot-from-snapshot), **rootfs patches** (`Microsandbox::Patch`),
+**custom per-rule network policies** (`Microsandbox::NetworkPolicy`/`Rule`/
+`Destination`, alongside the presets), **SSH** (`Sandbox#ssh` →
+`SshClient`/`SftpClient`/`SshServer`), and the **raw agent client**
+(`Microsandbox::AgentClient`). Create options span resources, network policy,
+`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches` and more;
+`exec`/`shell` take per-call `rlimits`, and `create` accepts
+`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
 

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.8"
+# 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"] }

data/ext/microsandbox/extconf.rb

@@ -13,12 +13,16 @@ MSRV = Gem::Version.new("1.91")
 rustc_version = begin
   out = `rustc --version 2>/dev/null`
   out[/\d+\.\d+(\.\d+)?/] && Gem::Version.new(out[/\d+\.\d+(\.\d+)?/])
-rescue StandardError
+rescue
   nil
 end
 
 if rustc_version && rustc_version < MSRV
-  which_rustc = (`which rustc 2>/dev/null`.strip rescue "")
+  which_rustc = begin
+    `which rustc 2>/dev/null`.strip
+  rescue
+    ""
+  end
   abort(<<~MSG)
 
     [microsandbox-rb] Rust #{rustc_version} is too old — the embedded core requires rustc >= #{MSRV}.

data/ext/microsandbox/src/agent.rs

@@ -0,0 +1,166 @@
+//! Raw agent client: `Microsandbox::Native::AgentClient`.
+//!
+//! Mirrors `sdk/python/src/agent.rs`. Wraps the core `AgentBridge` — the
+//! FFI-shaped, bytes-in/bytes-out façade over a sandbox's agentd relay socket.
+//! Frames are moved as raw CBOR bodies; (de)serialization stays in Ruby. Streams
+//! are referenced by opaque `u64` handles so the Ruby layer never owns a tokio
+//! receiver. Every call runs on the shared tokio runtime with the GVL released.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use magnus::{function, method, prelude::*, Error, RHash, RModule, RString, Ruby};
+use microsandbox::agent::AgentClient as CoreAgentClient;
+use microsandbox::{AgentBridge, BridgeFrame, MicrosandboxError};
+
+use crate::error;
+use crate::runtime::{block_on, ruby};
+
+/// Map an agent-client error onto the Ruby exception hierarchy (via the core
+/// `MicrosandboxError::AgentClient` wrapper, exactly like the Python binding).
+fn to_ruby_agent(err: microsandbox::AgentClientError) -> Error {
+    error::to_ruby(MicrosandboxError::AgentClient(err))
+}
+
+#[magnus::wrap(class = "Microsandbox::Native::AgentClient", free_immediately, size)]
+pub struct AgentClient {
+    inner: Arc<AgentBridge>,
+}
+
+impl AgentClient {
+    fn from_bridge(bridge: AgentBridge) -> Self {
+        Self {
+            inner: Arc::new(bridge),
+        }
+    }
+
+    //----------------------------------------------------------------------
+    // Connection (singleton methods)
+    //----------------------------------------------------------------------
+
+    /// Connect to a running sandbox by name. `timeout` is optional seconds.
+    fn connect_sandbox(name: String, timeout: Option<f64>) -> Result<AgentClient, Error> {
+        let bridge = match dur(timeout) {
+            Some(t) => block_on(AgentBridge::connect_sandbox_with_timeout(&name, t)),
+            None => block_on(AgentBridge::connect_sandbox(&name)),
+        }
+        .map_err(to_ruby_agent)?;
+        Ok(AgentClient::from_bridge(bridge))
+    }
+
+    /// Connect to an agentd relay socket by path. `timeout` is optional seconds.
+    fn connect_path(path: String, timeout: Option<f64>) -> Result<AgentClient, Error> {
+        let bridge = match dur(timeout) {
+            Some(t) => block_on(AgentBridge::connect_path_with_timeout(&path, t)),
+            None => block_on(AgentBridge::connect_path(&path)),
+        }
+        .map_err(to_ruby_agent)?;
+        Ok(AgentClient::from_bridge(bridge))
+    }
+
+    /// Resolve a sandbox's agent relay socket path without connecting.
+    fn socket_path(name: String) -> Result<String, Error> {
+        let path = CoreAgentClient::socket_path(&name).map_err(error::to_ruby)?;
+        Ok(path.to_string_lossy().into_owned())
+    }
+
+    //----------------------------------------------------------------------
+    // Instance methods
+    //----------------------------------------------------------------------
+
+    /// Send one frame and await a single response frame ({id, flags, body}).
+    fn request(&self, flags: u8, body: RString) -> Result<RHash, Error> {
+        let body = unsafe { body.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        let frame =
+            block_on(async move { inner.request(flags, body).await }).map_err(to_ruby_agent)?;
+        Ok(frame_to_hash(frame))
+    }
+
+    /// Open a streaming session; returns {id, handle}.
+    fn stream_open(&self, flags: u8, body: RString) -> Result<RHash, Error> {
+        let body = unsafe { body.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        let (id, handle) =
+            block_on(async move { inner.stream_open(flags, body).await }).map_err(to_ruby_agent)?;
+        let hash = ruby().hash_new();
+        hash.aset("id", id)?;
+        hash.aset("handle", handle)?;
+        Ok(hash)
+    }
+
+    /// Pull the next frame from a stream; nil at end-of-stream.
+    fn stream_next(&self, handle: u64) -> Result<Option<RHash>, Error> {
+        let inner = Arc::clone(&self.inner);
+        let frame =
+            block_on(async move { inner.stream_next(handle).await }).map_err(to_ruby_agent)?;
+        Ok(frame.map(frame_to_hash))
+    }
+
+    /// Close a stream handle. Idempotent.
+    fn stream_close(&self, handle: u64) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        block_on(async move { inner.stream_close(handle).await });
+        Ok(())
+    }
+
+    /// Send a follow-up frame on an existing correlation id.
+    fn send(&self, id: u32, flags: u8, body: RString) -> Result<(), Error> {
+        let body = unsafe { body.as_slice() }.to_vec();
+        let inner = Arc::clone(&self.inner);
+        block_on(async move { inner.send(id, flags, body).await }).map_err(to_ruby_agent)
+    }
+
+    /// Cached handshake `core.ready` frame body bytes (CBOR).
+    fn ready_bytes(&self) -> Result<RString, Error> {
+        let bytes = self.inner.ready_bytes().map_err(to_ruby_agent)?;
+        Ok(ruby().str_from_slice(&bytes))
+    }
+
+    /// Close the connection. Idempotent.
+    fn close(&self) -> Result<(), Error> {
+        let inner = Arc::clone(&self.inner);
+        block_on(async move { inner.close().await });
+        Ok(())
+    }
+}
+
+/// Convert seconds into a `Duration`, treating a non-positive/absent value as
+/// "use the default handshake timeout".
+fn dur(timeout: Option<f64>) -> Option<Duration> {
+    match timeout {
+        Some(t) if t.is_finite() && t > 0.0 => Some(Duration::from_secs_f64(t)),
+        _ => None,
+    }
+}
+
+/// Shape a `BridgeFrame` into a Ruby Hash. `body` is binary (ASCII-8BIT).
+fn frame_to_hash(frame: BridgeFrame) -> RHash {
+    let r = ruby();
+    let hash = r.hash_new();
+    let _ = hash.aset("id", frame.id);
+    let _ = hash.aset("flags", frame.flags);
+    let _ = hash.aset("body", r.str_from_slice(&frame.body));
+    hash
+}
+
+pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
+    let class = native.define_class("AgentClient", ruby.class_object())?;
+
+    class.define_singleton_method(
+        "connect_sandbox",
+        function!(AgentClient::connect_sandbox, 2),
+    )?;
+    class.define_singleton_method("connect_path", function!(AgentClient::connect_path, 2))?;
+    class.define_singleton_method("socket_path", function!(AgentClient::socket_path, 1))?;
+
+    class.define_method("request", method!(AgentClient::request, 2))?;
+    class.define_method("stream_open", method!(AgentClient::stream_open, 2))?;
+    class.define_method("stream_next", method!(AgentClient::stream_next, 1))?;
+    class.define_method("stream_close", method!(AgentClient::stream_close, 1))?;
+    class.define_method("send", method!(AgentClient::send, 3))?;
+    class.define_method("ready_bytes", method!(AgentClient::ready_bytes, 0))?;
+    class.define_method("close", method!(AgentClient::close, 0))?;
+
+    Ok(())
+}

data/ext/microsandbox/src/backend.rs

@@ -0,0 +1,170 @@
+//! Backend routing: the ambient process-wide backend and its selection surface.
+//!
+//! Mirrors the official Python (`sdk/python/src/lib.rs`) and Node
+//! (`sdk/node-ts/native/runtime_config.rs`) bindings. As of upstream v0.5.8
+//! (PR #754) every operation routes through a [`microsandbox::Backend`]: the
+//! ambient default is a lazily-initialised [`microsandbox::LocalBackend`], and
+//! callers may install a different default process-wide or for a scoped block.
+//!
+//! Local-only operations (image cache, aggregate metrics, `msb` path) need a
+//! concrete `&LocalBackend`; [`local_backend`] resolves the ambient default and
+//! downcasts it, surfacing a clean [`MicrosandboxError::Unsupported`] under a
+//! cloud backend (exactly as the pyo3 `resolve_local` helper does). The backend
+//! selection setters (`set_default_backend` / `with_backend` push-pop /
+//! `default_backend_kind`) deliberately expose only a `kind`/`url`/`api_key`/
+//! `profile` facade — the raw `LocalBackend`/`CloudBackend` builders stay hidden,
+//! matching Python and Node.
+
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::{Arc, Mutex, OnceLock};
+
+use magnus::{function, prelude::*, Error, RModule, Ruby};
+use microsandbox::{Backend, MicrosandboxError};
+
+use crate::error;
+use crate::runtime::block_on;
+
+/// Resolve the ambient default backend, requiring it to be local.
+///
+/// Returns the `Arc<dyn Backend>` so the caller can keep it alive while
+/// borrowing `&LocalBackend` from it (`as_local()` borrows the `Arc`). Pure
+/// Rust — safe to call inside `block_on` (no Ruby C API), and it returns a raw
+/// `MicrosandboxError` so the Ruby-exception mapping happens *after* `block_on`
+/// re-acquires the GVL. Cloud backends yield `Unsupported`, mirroring pyo3's
+/// `resolve_local`.
+pub fn local_backend() -> Result<Arc<dyn Backend>, MicrosandboxError> {
+    let backend = microsandbox::default_backend();
+    if backend.as_local().is_some() {
+        Ok(backend)
+    } else {
+        Err(MicrosandboxError::Unsupported {
+            feature: "this operation requires a local backend".into(),
+            available_when: "with the local backend (the default)".into(),
+        })
+    }
+}
+
+/// Resolve the ambient backend (requiring it to be local), then run `op` with a
+/// borrowed `&LocalBackend` inside the blocking runtime, mapping any core error
+/// to a Ruby exception. Local-only operations (image cache, aggregate metrics)
+/// share this instead of repeating the resolve/downcast dance; the single
+/// `as_local()` unwrap is provably infallible — [`local_backend`] just checked
+/// it and returns the same `Arc` kept alive for the borrow — so it lives here
+/// once rather than at every call site.
+pub fn with_local_backend<T>(
+    op: impl AsyncFnOnce(&microsandbox::LocalBackend) -> Result<T, MicrosandboxError>,
+) -> Result<T, Error> {
+    block_on(async move {
+        let backend = local_backend()?;
+        let local = backend
+            .as_local()
+            .expect("local_backend() guarantees a local backend");
+        op(local).await
+    })
+    .map_err(error::to_ruby)
+}
+
+/// Build an `Arc<dyn Backend>` from the SDK facade. Ported from pyo3
+/// `build_backend` (`sdk/python/src/lib.rs`) / node `build_backend`. Synchronous
+/// (no network I/O): cloud construction only builds the HTTP client. Runs on the
+/// Ruby thread with the GVL held, so it may map errors to Ruby directly.
+fn build_backend(
+    kind: String,
+    url: Option<String>,
+    api_key: Option<String>,
+    profile: Option<String>,
+) -> Result<Arc<dyn Backend>, Error> {
+    match kind.trim().to_ascii_lowercase().as_str() {
+        "local" => Ok(Arc::new(microsandbox::LocalBackend::lazy())),
+        "cloud" => {
+            let cloud = match profile {
+                Some(profile) => microsandbox::CloudBackend::from_profile(&profile),
+                None => match (url, api_key) {
+                    (Some(url), Some(api_key)) => microsandbox::CloudBackend::new(url, api_key),
+                    _ => {
+                        return Err(error::to_ruby(MicrosandboxError::InvalidConfig(
+                            "cloud backend requires url + api_key or profile".into(),
+                        )))
+                    }
+                },
+            }
+            .map_err(error::to_ruby)?;
+            Ok(Arc::new(cloud))
+        }
+        other => Err(error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+            "backend kind must be 'local' or 'cloud', got {other:?}"
+        )))),
+    }
+}
+
+/// Install a process-wide default backend. Synchronous (an `RwLock` write) — no
+/// `block_on`. Mirrors Python `set_default_backend` / Node `setDefaultBackend`.
+fn set_default_backend(
+    kind: String,
+    url: Option<String>,
+    api_key: Option<String>,
+    profile: Option<String>,
+) -> Result<(), Error> {
+    microsandbox::set_default_backend(build_backend(kind, url, api_key, profile)?);
+    Ok(())
+}
+
+// Scoped-override registry. `with_backend` in Ruby is a swap-and-restore around
+// a synchronous block, so it cannot use the core's async task-local
+// `with_backend`. We mirror Node's process-wide push/pop token registry: push
+// swaps the default and stores the previous backend under a fresh token; pop
+// restores it. The Ruby wrapper drives this through an `ensure` block.
+static NEXT_BACKEND_SCOPE: AtomicU32 = AtomicU32::new(1);
+static BACKEND_SCOPES: OnceLock<Mutex<HashMap<u32, Arc<dyn Backend>>>> = OnceLock::new();
+
+fn backend_scopes() -> &'static Mutex<HashMap<u32, Arc<dyn Backend>>> {
+    BACKEND_SCOPES.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+/// Swap in a new default backend and return a token for restoring the previous
+/// one via [`pop_default_backend`]. Process-wide while active (not task-local):
+/// concurrent Ruby threads observe the swapped default.
+fn push_default_backend(
+    kind: String,
+    url: Option<String>,
+    api_key: Option<String>,
+    profile: Option<String>,
+) -> Result<u32, Error> {
+    let previous = microsandbox::swap_default_backend(build_backend(kind, url, api_key, profile)?);
+    let token = NEXT_BACKEND_SCOPE.fetch_add(1, Ordering::Relaxed);
+    backend_scopes()
+        .lock()
+        .map_err(|_| error::base_error("backend scope registry poisoned"))?
+        .insert(token, previous);
+    Ok(token)
+}
+
+/// Restore the backend saved by [`push_default_backend`].
+fn pop_default_backend(token: u32) -> Result<(), Error> {
+    let previous = backend_scopes()
+        .lock()
+        .map_err(|_| error::base_error("backend scope registry poisoned"))?
+        .remove(&token)
+        .ok_or_else(|| error::base_error("unknown backend scope token"))?;
+    microsandbox::set_default_backend(previous);
+    Ok(())
+}
+
+/// The active default backend kind: `"local"` or `"cloud"`. First call lazily
+/// resolves the env/profile/config ladder. Synchronous (an `RwLock` read).
+fn default_backend_kind() -> String {
+    match microsandbox::default_backend().kind() {
+        microsandbox::BackendKind::Local => "local",
+        microsandbox::BackendKind::Cloud => "cloud",
+    }
+    .to_string()
+}
+
+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))?;
+    Ok(())
+}

data/ext/microsandbox/src/conv.rs

@@ -5,7 +5,7 @@
 
 use std::collections::HashMap;
 
-use magnus::{value::ReprValue, Error, RHash, TryConvert, Value};
+use magnus::{value::ReprValue, Error, RArray, RHash, TryConvert, Value};
 
 /// Fetch a non-nil value for `key`, if present.
 fn get(hash: RHash, key: &str) -> Option<Value> {
@@ -62,6 +62,24 @@ pub fn opt_string_vec(hash: RHash, key: &str) -> Result<Vec<String>, Error> {
     }
 }
 
+/// Array of `Hash`es (e.g. `patches`, custom-policy `rules`). Empty if absent.
+///
+/// `RHash` is a GC-managed handle and so cannot be collected via the blanket
+/// `Vec<T: TryConvert>` path; we walk the `Array` and convert each element.
+pub fn opt_hash_vec(hash: RHash, key: &str) -> Result<Vec<RHash>, Error> {
+    match get(hash, key) {
+        Some(v) => {
+            let arr = RArray::try_convert(v)?;
+            let mut out = Vec::with_capacity(arr.len());
+            for i in 0..arr.len() {
+                out.push(arr.entry::<RHash>(i as isize)?);
+            }
+            Ok(out)
+        }
+        None => Ok(Vec::new()),
+    }
+}
+
 /// `u16`→`u16` port map (host→guest TCP). Empty if absent.
 pub fn opt_port_map(hash: RHash, key: &str) -> Result<Vec<(u16, u16)>, Error> {
     match get(hash, key) {

data/ext/microsandbox/src/error.rs

@@ -28,6 +28,12 @@ fn class_name(err: &MicrosandboxError) -> &'static str {
         MetricsDisabled(_) => "MetricsDisabledError",
         MetricsUnavailable(_) => "MetricsUnavailableError",
         AgentClient(AgentClientError::UnsupportedOperation { .. }) => "UnsupportedOperationError",
+        // Backend routing (v0.5.8 / PR #754). `Unsupported` is reachable on the
+        // local backend too (e.g. `Volume::path` on a cloud volume, snapshot
+        // ops), so it must map even for local-only use. Distinct from the agent
+        // client's `UnsupportedOperation` above.
+        CloudHttp { .. } => "CloudHttpError",
+        Unsupported { .. } => "UnsupportedError",
         _ => "Error",
     }
 }