microsandbox-rb 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 158469a5ebe84ee4863c2a141cbeb486407bfc5ee05866be9005f9aee3bd249d
-  data.tar.gz: ef08b6519ac87f66c20f704e4c55590f56b3d6c05fa01ab6f9187db46f8b43af
+  metadata.gz: f8cc1edaf4e221fe6e4addf4eea0d06e63370dd73bbcb1a7eb4d13e91bac7b40
+  data.tar.gz: 17f18d5aefead5fbb584a7b06ecd82d0aade2394c3e9c48aafd0f5d98673abfd
 SHA512:
-  metadata.gz: d63ed9d45bdf68fb2f8352927412b23debd45e5e011f30a835fd2e75bae206e2ce19d1875c6099ce72c808c7d5e05e62a459f81794589e090ab837b9541d5da7
-  data.tar.gz: '09a726c22f8b12ecb0d575f0c4e20ce446aa5761cf5ed8cc15155a6b567e7ee867c4f95545a9595f786b88ec2f6dbd75b1bfe721fb629025ce8bfc19aa63fda0'
+  metadata.gz: e7c98769be2508875e54b1449d290c18b63af3189af497d311c6222073b6018290950faa4438c165f656928d175e6f6a50ec0f7af6323a8174dbf0e460b99042
+  data.tar.gz: 7a8edef36f6f7e3c12a5075e684d64ca71570350dd678ebcd3b819a9ebfab309007e2b71e348f1c0925ab8e3beb474787aeec741935f5e803676f5ce00daf513

data/CHANGELOG.md

@@ -8,6 +8,80 @@ wraps, and the README's Versioning section keeps the full gem→runtime map.
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-06-25
+
+Gem-only release on the `v0.5.10` runtime (unchanged) — the two follow-ups to
+`0.8.0`'s runtime adoption that review surfaced.
+
+### Added
+
+- **Per-bind-mount guest-write quota override** (issue #19). An inline `volumes:`
+  bind mount now accepts a `quota_mib:` key to override the runtime's default
+  guest-write budget (4 GiB as of `v0.5.10`, documented in `0.8.0`), e.g.
+  `volumes: { "/out" => { bind: "/host/out", quota_mib: 16_384 } }`. The runtime
+  still applies the 4 GiB default when unset; there is no unbounded option, so
+  raise the value if a workload writes more. Valid on bind mounts only — the core
+  rejects it on tmpfs/disk/named mounts (set a named volume's quota via
+  `Volume.create(quota_mib:)`).
+
+### Fixed
+
+- **Stale local runtime is now re-provisioned instead of boot-failing**
+  (issue #18). `Microsandbox.ensure_runtime!` short-circuited as soon as
+  `installed?` was true, but that check confirms only that the `msb`/`libkrunfw`
+  files *exist*, not that their version matches the runtime this gem build links.
+  An older `msb` left in `~/.microsandbox` by a previous gem version therefore
+  passed and then failed every `Sandbox.create` at boot on a host↔guest
+  wire-protocol mismatch (e.g. a `v0.5.8` `msb` rejecting the `--config-fd` flag
+  the `v0.5.10` runtime passes). `ensure_runtime!` now delegates to the
+  idempotent, version-correcting installer on first use even when the runtime is
+  present (a cheap `msb --version`; re-downloads only on absence/mismatch), so an
+  upgrade-over-stale-install self-heals. Source-gem installs were already
+  corrected at build time; this closes the gap for the precompiled-gem upgrade
+  path. `MICROSANDBOX_NO_AUTO_INSTALL` still fully opts out.
+
+## [0.8.0] - 2026-06-25
+
+Adopts upstream runtime **`v0.5.10`** (up from the `v0.5.8` that `0.7.0` shipped).
+Runtime-only bump — no public Ruby API change.
+
+### Runtime
+
+- **Adopted upstream `v0.5.10`** — the `microsandbox`/`microsandbox-network` git
+  deps and `Microsandbox::RUNTIME_VERSION` now pin `v0.5.10`. This is the runtime
+  bump originally attempted against `v0.5.9` during the `0.7.0` cycle and reverted:
+  upstream's `v0.5.9` git tag predated its own crate-version bump, so the prebuilt
+  runtime-provisioning path (`PREBUILT_VERSION = env!("CARGO_PKG_VERSION")`)
+  resolved to `0.5.8` and downloaded a `msb` that rejected the new `--config-fd`
+  flag the SDK unconditionally passes — every `Sandbox.create` died at boot.
+  Upstream chose not to re-tag (most package registries forbid republishing a tag)
+  and instead cut a clean **`v0.5.10`** whose tag carries the matching crate
+  version `0.5.10` (upstream
+  [#1029](https://github.com/superradcompany/microsandbox/issues/1029)). The bump
+  carries the following upstream changes:
+  - **Heartbeat no longer reclaims busy sandboxes** (upstream #1011). The host
+    watchdog is now idle-detection only — a healthy sandbox with an active (or
+    briefly starved) `exec` session is never killed for a stale heartbeat, the
+    way it could be before.
+  - **Launch config moved off the process argv** (upstream #1006). Bulky and
+    secret-bearing config (the network blob, env) is handed to the sandbox over
+    an inherited, unlinked-tempfile fd instead of `--`-flags, so it no longer
+    leaks into `ps` / `/proc/<pid>/cmdline`.
+
+### Changed
+
+- **Directory bind mounts now carry a default 4 GiB guest-write quota**
+  (upstream #1020). Any `volumes:` entry that binds a host directory (e.g.
+  `volumes: { "/out" => "/host/out" }`) is given a `DEFAULT_BIND_QUOTA_MIB`
+  (4096 MiB) guest-write budget by the v0.5.10 runtime when no explicit quota is
+  set, so a sandbox can no longer fill the host disk through a bind mount. This
+  is a **behavior change**: a workload that wrote more than 4 GiB to a bind mount
+  under the `v0.5.8` runtime (`0.7.0`) will now fail with `ENOSPC`. The gem does
+  not yet expose a per-bind quota override (named-volume `Volume.create` accepts
+  `quota_mib:`, but the inline bind-mount path does not) — that escape hatch is a
+  tracked follow-up. Until then, route large-write mounts through a named volume
+  with an explicit `quota_mib:`.
+
 ## [0.7.0] - 2026-06-23
 
 A large parity release closing the binding gaps an audit against the upstream

data/Cargo.lock

@@ -3003,8 +3003,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "anyhow",
  "astral-tokio-tar",
@@ -3056,8 +3056,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-agent-client"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "ciborium",
  "microsandbox-protocol",
@@ -3069,8 +3069,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-db"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "async-trait",
  "sea-orm",
@@ -3081,8 +3081,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-filesystem"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "libc",
  "microsandbox-utils",
@@ -3094,8 +3094,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-image"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "astral-tokio-tar",
  "async-compression",
@@ -3120,8 +3120,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-metrics"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "chrono",
  "libc",
@@ -3131,8 +3131,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-migration"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "sea-orm-migration",
  "serde_json",
@@ -3140,8 +3140,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-network"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "base64",
  "bytes",
@@ -3180,8 +3180,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-protocol"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "chrono",
  "ciborium",
@@ -3195,8 +3195,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-runtime"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "bytes",
  "chrono",
@@ -3225,8 +3225,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-types"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "chrono",
  "serde",
@@ -3237,8 +3237,8 @@ dependencies = [
 
 [[package]]
 name = "microsandbox-utils"
-version = "0.5.8"
-source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.8#47d0cdf1ef3b4b41885eb3efd67b759fd5540e9e"
+version = "0.5.10"
+source = "git+https://github.com/superradcompany/microsandbox?tag=v0.5.10#a62c4e45da7320e89aafc44b8a44fc74ec49fb53"
 dependencies = [
  "dirs",
  "libc",
@@ -3249,7 +3249,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.7.0"
+version = "0.8.1"
 dependencies = [
  "chrono",
  "futures",

data/README.md

@@ -383,8 +383,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.6.0"  (the gem's own version)
-Microsandbox.runtime_version   # => "v0.5.8"  (the embedded upstream runtime tag)
+Microsandbox::VERSION          # => "0.8.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.5.10"  (the embedded upstream runtime tag)
 ```
 
 | Gem version | Upstream runtime | Notes |
@@ -396,6 +396,9 @@ Microsandbox.runtime_version   # => "v0.5.8"  (the embedded upstream runtime tag
 | `0.5.11` | `v0.5.8` | gem-only revision |
 | `0.5.12` | `v0.5.8` | gem-only revision |
 | `0.6.0`  | `v0.5.8` | gem version decoupled from the upstream tag; adds `runtime_version` |
+| `0.7.0`  | `v0.5.8` | SDK parity release (large binding-gap closure) |
+| `0.8.0`  | `v0.5.10` | adopts upstream `v0.5.10` (idle-only heartbeat, config-fd hardening, **4 GiB default bind-mount quota**); supersedes the reverted `v0.5.9` attempt |
+| `0.8.1`  | `v0.5.10` | gem-only: re-provision a stale local runtime; per-bind-mount `quota_mib:` override |
 
 **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.5.8).
-version = "0.7.0"
+# The core-crate dependency below stays pinned at its own tag (v0.5.10).
+version = "0.8.1"
 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.8", default-features = true, features = ["ssh"] }
-microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.5.8" }
+microsandbox = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.5.10", default-features = true, features = ["ssh"] }
+microsandbox-network = { git = "https://github.com/superradcompany/microsandbox", tag = "v0.5.10" }
 
 # 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/sandbox.rs

@@ -122,6 +122,10 @@ impl Sandbox {
                 .ok_or_else(|| error::base_error("volume mount is missing :kind"))?;
             let source = conv::opt_string(m, "source")?;
             let size_mib = conv::opt_u32(m, "size_mib")?;
+            // Bind-mount guest-write quota override (MiB). The core's MountBuilder
+            // applies it to bind mounts only and rejects it on tmpfs/disk/named at
+            // build(); we forward it as-is so that validation lives in one place.
+            let quota_mib = conv::opt_u32(m, "quota_mib")?;
             let fstype = conv::opt_string(m, "fstype")?;
             let readonly = conv::opt_bool(m, "readonly")?;
             let noexec = conv::opt_bool(m, "noexec")?;
@@ -161,6 +165,9 @@ impl Sandbox {
                 if let Some(n) = size_mib {
                     mb = mb.size(n);
                 }
+                if let Some(q) = quota_mib {
+                    mb = mb.quota(q);
+                }
                 if let Some(f) = format {
                     mb = mb.format(f);
                 }

data/lib/microsandbox/sandbox.rb

@@ -230,7 +230,10 @@ module Microsandbox
       #   `{ disk: "/img.raw", format: "raw", fstype: "ext4" }`. Any mount may add
       #   flags `ro:`/`readonly:`, `noexec:`, `nosuid:`, `nodev:`, and (bind/named
       #   only) `stat_virtualization:` (:strict/:relaxed/:off) and
-      #   `host_permissions:` (:private/:mirror).
+      #   `host_permissions:` (:private/:mirror). A bind mount accepts
+      #   `quota_mib:` to override the runtime's default guest-write budget
+      #   (4 GiB as of `v0.5.10`); the core rejects it on tmpfs/disk/named (for a
+      #   named volume, set its quota via {Volume.create}).
       # @param network [String, Symbol, NetworkPolicy, Hash, nil] network policy.
       #   A preset name ("public_only" (default), "none", "allow_all",
       #   "non_local"), a {NetworkPolicy} (e.g. {NetworkPolicy.custom}), or a Hash
@@ -677,11 +680,12 @@ module Microsandbox
       # Hashes for the native layer. A spec is a host path String (a read-write
       # bind mount) or a Hash describing the mount:
       #   { bind: "/host", ro: true, noexec: true }            # host bind mount
+      #   { bind: "/host", quota_mib: 16_384 }                  # raise the 4 GiB cap
       #   { named: "vol" }                                       # named volume
       #   { tmpfs: true, size_mib: 64 }                          # memory-backed
       #   { disk: "/img.raw", format: "raw", fstype: "ext4" }   # disk-image mount
       # Any mount may also carry stat_virtualization: (:strict/:relaxed/:off) and
-      # host_permissions: (:private/:mirror).
+      # host_permissions: (:private/:mirror); a bind mount may carry quota_mib:.
       def normalize_volumes(volumes)
         volumes.map do |guest, spec|
           mount = {"guest" => guest.to_s}
@@ -722,6 +726,12 @@ module Microsandbox
         mount["size_mib"] = Integer(size) if size
         fstype = spec[:fstype] || spec["fstype"]
         mount["fstype"] = fstype.to_s if fstype
+        # Bind-mount guest-write quota (MiB). Overrides the runtime's default
+        # budget (4 GiB as of v0.5.10); the core applies it only to bind mounts
+        # and rejects it on tmpfs/disk/named. `0` is forwarded as-is (a zero
+        # budget), not treated as "unset".
+        quota = spec[:quota_mib] || spec["quota_mib"]
+        mount["quota_mib"] = Integer(quota) if quota
       end
 
       # Apply a volume spec Hash's mount flags. `ro:`/`readonly:` makes the mount

data/lib/microsandbox/version.rb

@@ -8,12 +8,12 @@ module Microsandbox
   # Versioning section of the README for the full gem-to-runtime map. Must equal
   # the native ext's Cargo crate version (`Native.version`), enforced by
   # spec/unit/version_spec.rb.
-  VERSION = "0.7.0"
+  VERSION = "0.8.1"
 
   # The upstream microsandbox runtime release this gem build embeds — the `tag`
   # pinned on the `microsandbox`/`microsandbox-network` git deps in
   # ext/microsandbox/Cargo.toml. Exposed at runtime as
   # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
   # sync with the Cargo tag so it can't silently drift out of date.
-  RUNTIME_VERSION = "v0.5.8"
+  RUNTIME_VERSION = "v0.5.10"
 end

data/lib/microsandbox.rb

@@ -93,16 +93,27 @@ module Microsandbox
       Native.installed?
     end
 
-    # Ensure the `msb` runtime + `libkrunfw` are present, provisioning them on
-    # first use if not. Called automatically by {Sandbox.create}/{Sandbox.start}
-    # so precompiled-gem users (who never ran the source build) get a working
-    # runtime without a manual {install} step.
+    # Ensure the `msb` runtime + `libkrunfw` are present *and version-matched*,
+    # provisioning them on first use if not. Called automatically by
+    # {Sandbox.create}/{Sandbox.start} so precompiled-gem users (who never ran the
+    # source build) get a working runtime without a manual {install} step.
     #
-    # The download is attempted at most once per process. Opt out by setting
+    # Runs at most once per process. Opt out by setting
     # `MICROSANDBOX_NO_AUTO_INSTALL` (e.g. air-gapped hosts that provision the
-    # runtime out of band); the subsequent operation then surfaces the missing
-    # runtime itself. Already-installed runtimes (e.g. source builds) skip
-    # straight through with only a cheap presence check.
+    # runtime out of band); the runtime is then left untouched and a missing or
+    # stale one surfaces at the operation itself.
+    #
+    # NOTE: this delegates to {install} even when {installed?} is already true,
+    # rather than short-circuiting on presence. {installed?} (upstream
+    # `verify_installation`) only confirms the `msb`/`libkrunfw` files *exist*, not
+    # that their version matches the runtime this gem build links. {install} is
+    # idempotent and *version-correcting*: it runs a cheap `msb --version` and
+    # re-downloads ONLY when the binary is absent or its version differs, then
+    # no-ops. A presence-only short-circuit would let a stale `msb` left in
+    # `~/.microsandbox` by an older gem pass, then fail every {Sandbox.create} on a
+    # host↔guest wire-protocol mismatch (e.g. a `v0.5.8` `msb` rejecting the
+    # `--config-fd` flag the `v0.5.10` runtime passes). Keep the {install} call on
+    # this path — do not "optimize" it back to skip-when-present.
     # @return [nil]
     def ensure_runtime!
       return if @runtime_ready
@@ -111,14 +122,18 @@ module Microsandbox
       # uses the same lazy env/profile/config ladder every operation already
       # consults, so this adds no work for local hosts (the common case).
       return if default_backend_kind == :cloud
-      if installed?
+      # Opted out: the caller manages the runtime out of band, so don't fetch,
+      # verify, or repair it here. Memoize the decision (the env var is stable for
+      # the process); the operation resolves `msb` itself and surfaces any problem.
+      if auto_install_disabled?
         @runtime_ready = true
         return
       end
-      return if auto_install_disabled?
 
-      warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
-           "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip)..."
+      unless installed?
+        warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
+             "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip)..."
+      end
       install
       @runtime_ready = true
       nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - ya-luotao