microsandbox-rb 0.12.0 → 0.13.0

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)
 
@@ -193,6 +199,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 +278,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 —
@@ -430,9 +456,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,8 +477,8 @@ 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)
 ```
 
 | Gem version | Upstream runtime | Notes |
@@ -469,6 +501,7 @@ 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` |
 
 **Going forward** — the gem version moves on its own semver track and no longer
 mirrors the upstream tag:

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.13.0"
 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.6.8", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.8" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9", default-features = true, features = ["ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.6.9" }
 
 # 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",
     }
 }

data/ext/microsandbox/src/sandbox.rs

@@ -18,7 +18,7 @@ use microsandbox::logs::{
     LogCursor, LogEntry, LogOptions, LogSource, LogStreamOptions, LogStreamStart,
 };
 use microsandbox::sandbox::{
-    AttachOptionsBuilder, DiskImageFormat, EnvVar, FsEntry, FsEntryKind, FsMetadata,
+    AttachOptionsBuilder, DiskImageFormat, EnvVar, FlatClone, FsEntry, FsEntryKind, FsMetadata,
     HostPermissions, Patch, PullPolicy, PullProgress, PullProgressHandle, RlimitResource,
     RootDiskBuilder, SandboxBuilder, SandboxHandle, SandboxMetrics, SandboxModificationBuilder,
     SandboxModificationPatch, SandboxStatus, SandboxStopResult, SecretBuilder,
@@ -128,13 +128,41 @@ impl Sandbox {
         for (k, v) in conv::opt_string_map(opts, "scripts")? {
             b = b.script(k, v);
         }
-        let entrypoint = conv::opt_string_vec(opts, "entrypoint")?;
-        if !entrypoint.is_empty() {
+        // entrypoint/cmd: presence-keyed, NOT non-emptiness-keyed — an
+        // explicitly *empty* array is meaningful for both (it clears the
+        // image's ENTRYPOINT / CMD, blocking the image-config merge), exactly
+        // like the Python binding. Keying on non-emptiness silently resurrects
+        // the image ENTRYPOINT and runs the wrong command under
+        // `exec_default`/`attach_default`.
+        if let Some(entrypoint) = conv::opt::<Vec<String>>(opts, "entrypoint")? {
             b = b.entrypoint(entrypoint);
         }
+        if let Some(cmd) = conv::opt::<Vec<String>>(opts, "cmd")? {
+            b = b.cmd(cmd);
+        }
         for (host, guest) in conv::opt_port_map(opts, "ports")? {
             b = b.port(host, guest);
         }
+        // vsock: host Unix sockets exposed on guest-to-host vsock ports
+        // (v0.6.9). Each route is normalized by the Ruby layer to a
+        // string-keyed Hash {host_socket:, port:, socket_type: "stream"|"dgram"}.
+        for route in conv::opt_hash_vec(opts, "vsock")? {
+            let Some(host_socket) = conv::opt_string(route, "host_socket")? else {
+                return Err(error::base_error("vsock route requires host_socket:"));
+            };
+            let Some(port) = conv::opt_u32(route, "port")? else {
+                return Err(error::base_error("vsock route requires port:"));
+            };
+            match conv::opt_string(route, "socket_type")?.as_deref() {
+                None | Some("stream") => b = b.vsock(host_socket, port),
+                Some("dgram") => b = b.vsock_dgram(host_socket, port),
+                Some(other) => {
+                    return Err(error::base_error(format!(
+                        "unknown vsock socket_type {other:?} (expected stream/dgram)"
+                    )))
+                }
+            }
+        }
         // volumes: each mount is normalized by the Ruby layer to a string-keyed
         // Hash — guest (req), kind ("bind"/"named"/"tmpfs"/"disk"), source
         // (bind/named/disk), size_mib (tmpfs/disk), format + fstype (disk),
@@ -413,6 +441,28 @@ impl Sandbox {
                 n
             });
         }
+        // rate_limiter: per-sandbox egress/ingress token-bucket limits
+        // (v0.6.9). The Ruby layer normalizes the option to a string-keyed
+        // Hash {egress:, ingress:} of {bandwidth:, ops:} buckets
+        // {size:, refill_time_ms:, one_time_burst:}; mirrors the Python SDK's
+        // `NetworkRateLimiter`. Applied via the network builder, accumulating
+        // on top of any configuration above.
+        if let Some(spec) = conv::opt::<RHash>(opts, "rate_limiter")?
+            .map(parse_rate_limiter)
+            .transpose()?
+        {
+            b = b.network(move |n| {
+                n.rate_limiter(move |mut r| {
+                    if let Some(egress) = spec.egress {
+                        r = r.egress(move |rl| egress.apply(rl));
+                    }
+                    if let Some(ingress) = spec.ingress {
+                        r = r.ingress(move |rl| ingress.apply(rl));
+                    }
+                    r
+                })
+            });
+        }
         // init: hand guest PID 1 to an init system. The Ruby layer normalizes
         // `init:` to a Hash { cmd:, args?:, env?: }. `init_with` with empty
         // args/env builds the same HandoffInit as the plain `init(cmd)`, so route
@@ -560,6 +610,29 @@ impl Sandbox {
         Ok(ExecHandle::from_core(handle))
     }
 
+    /// Run the image's resolved OCI ENTRYPOINT and CMD (the default workload,
+    /// v0.6.9) and wait for completion. `create` is strictly boot-only, so this
+    /// is how the image's own command is executed. `opts` matches `exec` minus
+    /// the command: cwd, user, env, timeout, tty, stdin, rlimits. Raises
+    /// NoDefaultCommandError when the image resolves no executable command.
+    fn exec_default(&self, opts: RHash) -> Result<RHash, Error> {
+        let parsed = ExecOpts::parse(Vec::new(), opts)?;
+        let output = block_on(self.inner.exec_default_with(move |b| parsed.apply(b)))
+            .map_err(error::to_ruby)?;
+        exec_output_to_hash(output)
+    }
+
+    /// Streaming default-workload execution. Returns an ExecHandle.
+    fn exec_default_stream(&self, opts: RHash) -> Result<ExecHandle, Error> {
+        let parsed = ExecOpts::parse(Vec::new(), opts)?;
+        let handle = block_on(
+            self.inner
+                .exec_default_stream_with(move |b| parsed.apply(b)),
+        )
+        .map_err(error::to_ruby)?;
+        Ok(ExecHandle::from_core(handle))
+    }
+
     /// Streaming shell execution.
     fn shell_stream(&self, script: String, opts: RHash) -> Result<ExecHandle, Error> {
         let parsed = ExecOpts::parse(Vec::new(), opts)?;
@@ -853,6 +926,14 @@ impl Sandbox {
     fn attach_shell(&self) -> Result<i32, Error> {
         block_on(self.inner.attach_shell()).map_err(error::to_ruby)
     }
+
+    /// Attach an interactive terminal to the image's resolved OCI ENTRYPOINT
+    /// and CMD (the default workload, v0.6.9); returns its exit code. `opts`:
+    /// cwd, user, env, detach_keys, rlimits.
+    fn attach_default(&self, opts: RHash) -> Result<i32, Error> {
+        let parsed = AttachOpts::parse(Vec::new(), opts)?;
+        block_on(self.inner.attach_default_with(move |b| parsed.apply(b))).map_err(error::to_ruby)
+    }
 }
 
 //--------------------------------------------------------------------------------------------------
@@ -1268,6 +1349,83 @@ fn parse_dns(d: RHash) -> Result<DnsSpec, Error> {
     })
 }
 
+/// One token bucket of the `rate_limiter` create option (v0.6.9):
+/// `(size, refill_time_ms, one_time_burst)`. Size is bytes for bandwidth
+/// buckets, frames for ops buckets.
+type TokenBucketSpec = (u64, u64, u64);
+
+/// One direction of the `rate_limiter` create option.
+struct RateLimiterSpec {
+    bandwidth: Option<TokenBucketSpec>,
+    ops: Option<TokenBucketSpec>,
+}
+
+/// Parsed `rate_limiter` create option (v0.6.9, mirrors the Python SDK's
+/// `NetworkRateLimiter`): per-direction bandwidth/ops token buckets. Parsed up
+/// front because the network builder closure cannot return an error.
+struct NetworkRateLimiterSpec {
+    egress: Option<RateLimiterSpec>,
+    ingress: Option<RateLimiterSpec>,
+}
+
+fn parse_token_bucket(b: RHash, dir: &str, dim: &str) -> Result<TokenBucketSpec, Error> {
+    let Some(size) = conv::opt::<u64>(b, "size")? else {
+        return Err(error::base_error(format!(
+            "rate_limiter {dir} {dim} bucket requires size:"
+        )));
+    };
+    let Some(refill) = conv::opt::<u64>(b, "refill_time_ms")? else {
+        return Err(error::base_error(format!(
+            "rate_limiter {dir} {dim} bucket requires refill_time_ms:"
+        )));
+    };
+    let burst = conv::opt::<u64>(b, "one_time_burst")?.unwrap_or(0);
+    Ok((size, refill, burst))
+}
+
+fn parse_rate_limiter_direction(h: RHash, dir: &str) -> Result<RateLimiterSpec, Error> {
+    Ok(RateLimiterSpec {
+        bandwidth: conv::opt::<RHash>(h, "bandwidth")?
+            .map(|b| parse_token_bucket(b, dir, "bandwidth"))
+            .transpose()?,
+        ops: conv::opt::<RHash>(h, "ops")?
+            .map(|b| parse_token_bucket(b, dir, "ops"))
+            .transpose()?,
+    })
+}
+
+fn parse_rate_limiter(h: RHash) -> Result<NetworkRateLimiterSpec, Error> {
+    Ok(NetworkRateLimiterSpec {
+        egress: conv::opt::<RHash>(h, "egress")?
+            .map(|d| parse_rate_limiter_direction(d, "egress"))
+            .transpose()?,
+        ingress: conv::opt::<RHash>(h, "ingress")?
+            .map(|d| parse_rate_limiter_direction(d, "ingress"))
+            .transpose()?,
+    })
+}
+
+impl RateLimiterSpec {
+    fn apply(
+        self,
+        mut rl: microsandbox_network::builder::RateLimiterBuilder,
+    ) -> microsandbox_network::builder::RateLimiterBuilder {
+        if let Some((size, refill_ms, burst)) = self.bandwidth {
+            rl = rl.bandwidth(size, Duration::from_millis(refill_ms));
+            if burst > 0 {
+                rl = rl.bandwidth_burst(burst);
+            }
+        }
+        if let Some((count, refill_ms, burst)) = self.ops {
+            rl = rl.ops(count, Duration::from_millis(refill_ms));
+            if burst > 0 {
+                rl = rl.ops_burst(burst);
+            }
+        }
+        rl
+    }
+}
+
 struct TlsSpec {
     bypass: Vec<String>,
     verify_upstream: Option<bool>,
@@ -1409,12 +1567,14 @@ struct RootDiskSpec {
     size_mib: Option<u32>,
     format: Option<DiskImageFormat>,
     fstype: Option<String>,
+    clone: Option<FlatClone>,
 }
 
 enum RootDiskKindSpec {
     Managed,
     Tmpfs,
     Disk(String),
+    Flat,
 }
 
 impl RootDiskSpec {
@@ -1423,6 +1583,7 @@ impl RootDiskSpec {
             RootDiskKindSpec::Managed => {}
             RootDiskKindSpec::Tmpfs => d = d.tmpfs(),
             RootDiskKindSpec::Disk(path) => d = d.disk_image(path),
+            RootDiskKindSpec::Flat => d = d.flat(),
         }
         if let Some(mib) = self.size_mib {
             d = d.size(mib);
@@ -1433,6 +1594,9 @@ impl RootDiskSpec {
         if let Some(ft) = self.fstype {
             d = d.fstype(ft);
         }
+        if let Some(c) = self.clone {
+            d = d.clone_strategy(c);
+        }
         d
     }
 }
@@ -1444,12 +1608,13 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             size_mib: Some(mib),
             format: None,
             fstype: None,
+            clone: None,
         });
     }
     let Ok(h) = RHash::try_convert(v) else {
         return Err(error::base_error(
             "root_disk: expects an Integer (managed size in MiB) or a Hash \
-             (use Microsandbox::RootDisk.managed/tmpfs/disk)",
+             (use Microsandbox::RootDisk.managed/tmpfs/disk/flat)",
         ));
     };
     let kind = match conv::opt_string(h, "kind")?.as_deref() {
@@ -1461,20 +1626,35 @@ fn parse_root_disk(v: Value) -> Result<RootDiskSpec, Error> {
             };
             RootDiskKindSpec::Disk(path)
         }
+        Some("flat") => RootDiskKindSpec::Flat,
         Some(other) => {
             return Err(error::base_error(format!(
-                "unknown root_disk kind {other:?} (expected managed/tmpfs/disk)"
+                "unknown root_disk kind {other:?} (expected managed/tmpfs/disk/flat)"
             )))
         }
     };
     let format = conv::opt_string(h, "format")?
         .map(|f| disk_format_from_str(&f))
         .transpose()?;
+    // clone: flat-only private-disk clone strategy (v0.6.9). Validated here
+    // (unknown values error) but kind cross-validation stays in the core
+    // builder, matching the other fields.
+    let clone = conv::opt_string(h, "clone")?
+        .map(|c| match c.as_str() {
+            "auto" => Ok(FlatClone::Auto),
+            "copy" => Ok(FlatClone::Copy),
+            "reflink" => Ok(FlatClone::Reflink),
+            other => Err(error::base_error(format!(
+                "unknown root_disk clone strategy {other:?} (expected auto/copy/reflink)"
+            ))),
+        })
+        .transpose()?;
     Ok(RootDiskSpec {
         kind,
         size_mib: conv::opt_u32(h, "size_mib")?,
         format,
         fstype: conv::opt_string(h, "fstype")?,
+        clone,
     })
 }
 
@@ -1969,9 +2149,9 @@ fn run_modify(builder: SandboxModificationBuilder, opts: RHash) -> Result<String
 
 /// Build the canonical `SandboxModificationPatch` from the modify Hash. Env and
 /// label pairs are sorted so repeated calls with the same arguments produce the
-/// same patch (and plan) ordering, mirroring the Python binding. `oci_upper_size`
-/// is deliberately not surfaced (CLI-only upstream; the Python/Node SDKs omit it
-/// too), so it stays unset via `..Default::default()`.
+/// same patch (and plan) ordering, mirroring the Python binding. As of v0.6.9
+/// every patch field is surfaced (`root_disk_size` covers what the deprecated
+/// CLI-only `oci_upper_size` used to mean).
 fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
     let mut env_pairs = conv::opt_string_map(opts, "env")?;
     env_pairs.sort();
@@ -1983,6 +2163,10 @@ fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
         max_cpus: conv::opt_u8(opts, "max_cpus")?,
         memory_mib: conv::opt_u32(opts, "memory")?,
         max_memory_mib: conv::opt_u32(opts, "max_memory")?,
+        // v0.6.9 ("root disk resizing in every SDK"): grow the sandbox-owned
+        // layered upper or flat root disk. Restart/next-start semantics and
+        // backing-specific limits are enforced by the core.
+        root_disk_size_mib: conv::opt_u32(opts, "root_disk_size")?,
         env: env_pairs
             .into_iter()
             .map(|(k, v)| EnvVar::new(k, v))
@@ -1993,7 +2177,6 @@ fn build_modify_patch(opts: RHash) -> Result<SandboxModificationPatch, Error> {
         workdir: conv::opt_string(opts, "workdir")?,
         secrets: parse_modify_secrets(opts)?,
         secrets_remove: conv::opt_string_vec(opts, "remove_secrets")?,
-        ..Default::default()
     })
 }
 
@@ -2422,6 +2605,11 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     class.define_method("shell", method!(Sandbox::shell, 2))?;
     class.define_method("exec_stream", method!(Sandbox::exec_stream, 3))?;
     class.define_method("shell_stream", method!(Sandbox::shell_stream, 2))?;
+    class.define_method("exec_default", method!(Sandbox::exec_default, 1))?;
+    class.define_method(
+        "exec_default_stream",
+        method!(Sandbox::exec_default_stream, 1),
+    )?;
     class.define_method("stop", method!(Sandbox::stop, 0))?;
     class.define_method("stop_and_wait", method!(Sandbox::stop_and_wait, 0))?;
     class.define_method("kill", method!(Sandbox::kill, 0))?;
@@ -2461,6 +2649,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     )?;
 
     class.define_method("attach", method!(Sandbox::attach, 3))?;
+    class.define_method("attach_default", method!(Sandbox::attach_default, 1))?;
     class.define_method("attach_shell", method!(Sandbox::attach_shell, 0))?;
 
     let handle = native.define_class("SandboxHandle", ruby.class_object())?;

data/ext/microsandbox/src/snapshot.rs

@@ -171,9 +171,10 @@ fn remove(name_or_path: String, force: bool) -> Result<(), Error> {
 }
 
 /// Verify a snapshot's recorded upper-layer integrity. Returns
-/// {digest, path, upper_status, upper_algorithm, upper_digest}. Schema-1
-/// descriptors always record integrity, so the status is always "verified"
-/// on success (mismatches raise SnapshotIntegrityError instead).
+/// {digest, path, upper_status, upper_algorithm, upper_digest}. As of v0.6.9
+/// payload integrity is opt-in at create time: opted-in snapshots verify to
+/// "verified" (mismatches raise SnapshotIntegrityError), snapshots without
+/// recorded integrity report "not_recorded" with no algorithm/digest keys.
 fn verify(name_or_path: String) -> Result<RHash, Error> {
     let snap = block_on(Snapshot::open(&name_or_path)).map_err(error::to_ruby)?;
     let report = block_on(snap.verify()).map_err(error::to_ruby)?;
@@ -248,6 +249,12 @@ fn verify_report_to_hash(report: &SnapshotVerifyReport) -> RHash {
             let _ = hash.aset("upper_algorithm", algorithm.clone());
             let _ = hash.aset("upper_digest", digest.clone());
         }
+        // v0.6.9 (#1346): payload integrity is opt-in at create time
+        // (`record_integrity`); a snapshot without it verifies structurally
+        // but has no content digest to check.
+        UpperVerifyStatus::NotRecorded => {
+            let _ = hash.aset("upper_status", "not_recorded");
+        }
     }
     hash
 }

data/ext/microsandbox/src/volume.rs

@@ -18,6 +18,7 @@ fn handle_to_hash(h: &VolumeHandle) -> RHash {
     let hash = ruby().hash_new();
     let _ = hash.aset("name", h.name().to_string());
     let _ = hash.aset("kind", h.kind().as_str().to_string());
+    let _ = hash.aset("default", h.is_default());
     let _ = hash.aset("quota_mib", h.quota_mib());
     let _ = hash.aset("used_bytes", h.used_bytes());
     let _ = hash.aset("capacity_bytes", h.capacity_bytes());
@@ -83,6 +84,13 @@ fn get(name: String) -> Result<RHash, Error> {
     Ok(handle_to_hash(&handle))
 }
 
+/// The backend's default volume (v0.6.9). Cloud-backend only — the local
+/// backend rejects it (Unsupported) to avoid accidental host access.
+fn get_default() -> Result<RHash, Error> {
+    let handle = block_on(microsandbox::Volume::get_default()).map_err(error::to_ruby)?;
+    Ok(handle_to_hash(&handle))
+}
+
 fn list() -> Result<RArray, Error> {
     let handles = block_on(microsandbox::Volume::list()).map_err(error::to_ruby)?;
     let arr = ruby().ary_new();
@@ -196,6 +204,7 @@ pub fn define(ruby: &Ruby, native: &RModule) -> Result<(), Error> {
     let class = native.define_class("Volume", ruby.class_object())?;
     class.define_singleton_method("create", function!(create, 2))?;
     class.define_singleton_method("get", function!(get, 1))?;
+    class.define_singleton_method("get_default", function!(get_default, 0))?;
     class.define_singleton_method("list", function!(list, 0))?;
     class.define_singleton_method("remove", function!(remove, 1))?;
     class.define_singleton_method("fs", function!(fs, 1))?;

data/lib/microsandbox/backend_info.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Secret-safe description of the active default backend, from
+  # {Microsandbox.default_backend_info} (runtime v0.6.9). Describes what
+  # selected the backend and where it points — never its credential: the API
+  # key is deliberately absent.
+  class BackendInfo
+    # @return [String, nil] effective cloud API endpoint (nil for local)
+    attr_reader :api_url
+    # @return [String, nil] the selected profile name, when a profile chose
+    #   the backend
+    attr_reader :profile
+
+    def initialize(data)
+      @kind = data["kind"]
+      @api_url = data["api_url"]
+      @source = data["source"]
+      @profile = data["profile"]
+    end
+
+    # @return [Symbol] :local or :cloud
+    def kind
+      @kind.to_sym
+    end
+
+    # What selected this backend: `:programmatic` (an SDK setter),
+    # `:MSB_BACKEND` / `:MSB_API_KEY` / `:MSB_PROFILE` (environment),
+    # `:profile` (an explicit SDK profile constructor), `:active_profile`
+    # (the SDK config file), or `:default` (the final local fallback).
+    # @return [Symbol]
+    def source
+      @source.to_sym
+    end
+
+    def local? = kind == :local
+
+    def cloud? = kind == :cloud
+
+    def inspect
+      "#<Microsandbox::BackendInfo kind=#{@kind} source=#{@source.inspect}" \
+        "#{" api_url=#{@api_url.inspect}" if @api_url}" \
+        "#{" profile=#{@profile.inspect}" if @profile}>"
+    end
+  end
+end

data/lib/microsandbox/errors.rb

@@ -39,6 +39,10 @@ module Microsandbox
   # Execution errors --------------------------------------------------------
   define_error(:ExecTimeoutError, "exec-timeout")
   define_error(:ExecFailedError, "exec-failed")
+  # v0.6.9: `exec_default`/`attach_default` on an image whose resolved
+  # ENTRYPOINT+CMD provide no executable command. Mirrors the Python SDK's
+  # NoDefaultCommandError.
+  define_error(:NoDefaultCommandError, "no-default-command")
 
   # Filesystem errors -------------------------------------------------------
   define_error(:FilesystemError, "filesystem-error")

data/lib/microsandbox/root_disk.rb

@@ -13,12 +13,18 @@ module Microsandbox
   # - {disk} — a user-supplied disk image attached writable as the upper. The
   #   file determines its own size; the runtime never creates, resizes, or
   #   deletes it. Cannot be snapshotted or patched.
+  # - {flat} — a single complete ext4 root disk materialized directly from the
+  #   OCI image (runtime v0.6.9), skipping the layered EROFS+OverlayFS stack at
+  #   runtime. Content-addressed and cached across sandboxes; resizable.
+  #   Pre-materialize with `msb pull IMAGE --materialize flat`.
   #
   # @example
   #   Sandbox.create("worker", image: "python", root_disk: 8192)
   #   Sandbox.create("ci", image: "python", root_disk: Microsandbox::RootDisk.tmpfs(2048))
   #   Sandbox.create("warm", image: "python",
   #     root_disk: Microsandbox::RootDisk.disk("./scratch.img", fstype: "ext4"))
+  #   Sandbox.create("fast", image: "python",
+  #     root_disk: Microsandbox::RootDisk.flat(8192, clone: :reflink))
   #
   # Mirrors the `RootDisk` factory in the official Python/Node/Go SDKs.
   module RootDisk
@@ -54,5 +60,23 @@ module Microsandbox
       h["fstype"] = fstype.to_s if fstype
       h
     end
+
+    # A complete, microsandbox-owned root disk materialized from the OCI image
+    # (runtime v0.6.9).
+    # @param size_mib [Integer, nil] resizable ext4 size in MiB
+    # @param fstype [String, nil] generated filesystem type (default "ext4")
+    # @param clone [Symbol, String, nil] how each sandbox's private disk is
+    #   created from the cached artifact: `:auto` (CoW clone when the host
+    #   filesystem supports it, else a sparse copy — the default), `:copy`
+    #   (always an independent sparse copy), or `:reflink` (require a CoW
+    #   clone; fail where unsupported)
+    # @return [Hash]
+    def flat(size_mib = nil, fstype: nil, clone: nil)
+      h = {"kind" => "flat"}
+      h["size_mib"] = Integer(size_mib) if size_mib
+      h["fstype"] = fstype.to_s if fstype
+      h["clone"] = clone.to_s if clone
+      h
+    end
   end
 end