microsandbox-rb 0.12.0 → 0.14.0

data/lib/microsandbox/sandbox.rb

@@ -288,7 +288,14 @@ module Microsandbox
       # @param hostname [String, nil] guest hostname
       # @param labels [Hash, nil] metadata labels
       # @param scripts [Hash, nil] named scripts to install
-      # @param entrypoint [Array<String>, nil] image entrypoint override
+      # @param entrypoint [Array<String>, nil] image ENTRYPOINT override. An
+      #   explicit `[]` clears the image's ENTRYPOINT (so `exec_default` runs
+      #   the CMD alone); `nil` (the default) inherits it.
+      # @param cmd [Array<String>, nil] image CMD override used by
+      #   default-workload execution ({Sandbox#exec_default} et al., runtime
+      #   v0.6.9). Durable configuration — it does **not** execute anything at
+      #   create time (`create` boots the VM only). An explicit `[]` clears the
+      #   image CMD; `nil` (the default) inherits it.
       # @param ports [Hash, nil] host_port => guest_port TCP publications
       # @param ports_udp [Hash, nil] host_port => guest_port UDP publications
       # @param volumes [Hash, nil] guest_path => mount spec. Each value is a host
@@ -322,6 +329,17 @@ module Microsandbox
       # @param ipv6_pool [String, nil] guest IPv6 address pool CIDR
       # @param max_connections [Integer, nil] cap on concurrent proxied connections
       # @param trust_host_cas [Boolean, nil] trust the host's CA bundle for upstream TLS
+      # @param rate_limiter [Hash, nil] per-sandbox egress/ingress token-bucket
+      #   limits (runtime v0.6.9, local backend):
+      #   `{ egress: { bandwidth: { size: 1_048_576, refill_time_ms: 1000,
+      #   one_time_burst: 0 }, ops: { size: 1000, refill_time_ms: 1000 } },
+      #   ingress: { ... } }`. `bandwidth` buckets meter bytes, `ops` buckets
+      #   meter network frames; an omitted bucket or direction is unlimited.
+      # @param vsock [Hash, Array, nil] host sockets exposed on guest-to-host
+      #   vsock ports (runtime v0.6.9): `{ "/host/api.sock" => 5000 }` (stream
+      #   sockets), or an Array of
+      #   `{ host_socket:, port:, socket_type: :stream|:dgram }` Hashes. Guests
+      #   connect to host CID 2 on the given port; no in-guest proxy required.
       # @param from_snapshot [String, nil] boot from a snapshot name or digest
       #   instead of an image (mutually exclusive with `image:`)
       # @param fstype [String, nil] inner filesystem type (e.g. "ext4") when
@@ -343,9 +361,12 @@ module Microsandbox
       #   disk (runtime v0.6.7). An Integer is the managed ext4 upper's size cap
       #   in MiB (default kind, 4 GiB when unset); a Hash picks a kind via the
       #   {RootDisk} factory — `RootDisk.managed(8192)`, `RootDisk.tmpfs(2048)`
-      #   (RAM-backed, pristine on every boot), or
+      #   (RAM-backed, pristine on every boot),
       #   `RootDisk.disk("./scratch.img", format: "raw", fstype: "ext4")`
-      #   (user-supplied image attached writable).
+      #   (user-supplied image attached writable), or
+      #   `RootDisk.flat(8192, clone: :auto)` (a single complete ext4 root disk
+      #   materialized from the OCI image, runtime v0.6.9 — skips the overlay
+      #   stack; content-addressed and cached across sandboxes).
       # @param oci_upper_size [Integer, nil] deprecated alias for
       #   `root_disk: <Integer>` (the managed kind); warns, and conflicts with
       #   `root_disk:`
@@ -418,9 +439,9 @@ module Microsandbox
       def build_create_opts(image: nil, cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
         env: nil, workdir: nil,
         shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
-        entrypoint: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
+        entrypoint: nil, cmd: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
         dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil,
-        max_connections: nil, trust_host_cas: nil,
+        max_connections: nil, trust_host_cas: nil, rate_limiter: nil, vsock: nil,
         patches: nil,
         from_snapshot: nil, fstype: nil, init: nil, ephemeral: false,
         log_level: nil, quiet_logs: false, security: nil,
@@ -465,7 +486,11 @@ module Microsandbox
         opts["env"] = stringify(env) if env
         opts["labels"] = stringify(labels) if labels
         opts["scripts"] = stringify(scripts) if scripts
-        opts["entrypoint"] = Array(entrypoint).map(&:to_s) if entrypoint
+        # entrypoint/cmd: an explicit empty Array clears the image's value
+        # (blocking the image-config merge), so presence is keyed on the kwarg
+        # itself — nil (the default) inherits from the image.
+        opts["entrypoint"] = Array(entrypoint).map(&:to_s) unless entrypoint.nil?
+        opts["cmd"] = Array(cmd).map(&:to_s) unless cmd.nil?
         opts["ports"] = intify_ports(ports) if ports
         opts["ports_udp"] = intify_ports(ports_udp) if ports_udp
         opts["volumes"] = normalize_volumes(volumes) if volumes
@@ -477,6 +502,8 @@ module Microsandbox
         opts["ipv6_pool"] = ipv6_pool.to_s if ipv6_pool
         opts["max_connections"] = Integer(max_connections) if max_connections
         set_bool(opts, "trust_host_cas", trust_host_cas)
+        opts["rate_limiter"] = normalize_rate_limiter(rate_limiter) if rate_limiter
+        opts["vsock"] = normalize_vsock(vsock) if vsock
         opts["log_level"] = log_level.to_s if log_level
         opts["quiet_logs"] = true if quiet_logs
         opts["security"] = security.to_s if security
@@ -638,6 +665,7 @@ module Microsandbox
       # always set (defaulting to "no_restart"); everything else is included only
       # when provided so an unset option means "leave unchanged".
       def build_modify_opts(cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
+        root_disk_size: nil,
         env: nil, remove_env: nil, labels: nil, remove_labels: nil, workdir: nil,
         secrets: nil, remove_secrets: nil, policy: nil, dry_run: false)
         opts = {}
@@ -645,6 +673,7 @@ module Microsandbox
         opts["max_cpus"] = Integer(max_cpus) if max_cpus
         opts["memory"] = Integer(memory) if memory
         opts["max_memory"] = Integer(max_memory) if max_memory
+        opts["root_disk_size"] = Integer(root_disk_size) if root_disk_size
         opts["env"] = stringify(env) if env
         opts["remove_env"] = Array(remove_env).map(&:to_s) if remove_env
         opts["labels"] = stringify(labels) if labels
@@ -831,6 +860,71 @@ module Microsandbox
       end
 
       # Normalize the `dns:` config Hash for the native layer.
+      # Normalize the `rate_limiter:` Hash (v0.6.9) — per-direction
+      # bandwidth/ops token buckets — for the native layer. Mirrors the Python
+      # SDK's `NetworkRateLimiter`/`RateLimiter`/`TokenBucket` shapes as plain
+      # Hashes: `{egress: {bandwidth: {size:, refill_time_ms:, one_time_burst:},
+      # ops: {...}}, ingress: {...}}`.
+      def normalize_rate_limiter(rl)
+        raise ArgumentError, "rate_limiter: must be a Hash" unless rl.is_a?(Hash)
+        out = {}
+        %i[egress ingress].each do |dir|
+          spec = fetch_opt(rl, dir)
+          next if spec.nil?
+          unless spec.is_a?(Hash)
+            raise ArgumentError, "rate_limiter #{dir}: must be a Hash"
+          end
+          dout = {}
+          %i[bandwidth ops].each do |dim|
+            bucket = fetch_opt(spec, dim)
+            next if bucket.nil?
+            unless bucket.is_a?(Hash)
+              raise ArgumentError, "rate_limiter #{dir} #{dim}: must be a Hash"
+            end
+            size = fetch_opt(bucket, :size)
+            refill = fetch_opt(bucket, :refill_time_ms)
+            if size.nil? || refill.nil?
+              raise ArgumentError,
+                "rate_limiter #{dir} #{dim}: requires size: and refill_time_ms:"
+            end
+            bout = {"size" => Integer(size), "refill_time_ms" => Integer(refill)}
+            burst = fetch_opt(bucket, :one_time_burst)
+            bout["one_time_burst"] = Integer(burst) if burst
+            dout[dim.to_s] = bout
+          end
+          out[dir.to_s] = dout
+        end
+        out
+      end
+
+      # Normalize the `vsock:` create option (v0.6.9) into the native array of
+      # route Hashes. Accepts the Python SDK's two shapes: a Hash of
+      # `{ host_socket => port }` (stream sockets), or an Array of
+      # `{host_socket:, port:, socket_type: :stream|:dgram}` Hashes.
+      def normalize_vsock(vsock)
+        if vsock.is_a?(Hash)
+          vsock.map { |path, port| {"host_socket" => path.to_s, "port" => Integer(port)} }
+        elsif vsock.is_a?(Array)
+          vsock.map do |route|
+            unless route.is_a?(Hash)
+              raise ArgumentError, "vsock: array entries must be Hashes {host_socket:, port:, socket_type:}"
+            end
+            path = fetch_opt(route, :host_socket)
+            port = fetch_opt(route, :port)
+            if path.nil? || port.nil?
+              raise ArgumentError, "vsock route requires host_socket: and port:"
+            end
+            out = {"host_socket" => path.to_s, "port" => Integer(port)}
+            st = fetch_opt(route, :socket_type)
+            out["socket_type"] = st.to_s if st
+            out
+          end
+        else
+          raise ArgumentError,
+            "vsock: must be a Hash of {host_socket => port} or an Array of route Hashes"
+        end
+      end
+
       def normalize_dns(dns)
         raise ArgumentError, "dns: must be a Hash" unless dns.is_a?(Hash)
         out = {}
@@ -928,9 +1022,29 @@ module Microsandbox
           h["format"] = spec["format"].to_s if spec["format"]
           h["fstype"] = spec["fstype"].to_s if spec["fstype"]
           h
+        when "flat"
+          %w[path format].each do |key|
+            if spec[key]
+              raise ArgumentError, "root_disk #{key}: is only valid for the disk kind"
+            end
+          end
+          h = {"kind" => "flat"}
+          if spec["size_mib"]
+            h["size_mib"] = coerce_root_disk_size(spec["size_mib"], "root_disk size_mib:")
+          end
+          h["fstype"] = spec["fstype"].to_s if spec["fstype"]
+          if spec["clone"]
+            clone = spec["clone"].to_s
+            unless %w[auto copy reflink].include?(clone)
+              raise ArgumentError,
+                "unknown root_disk clone strategy #{clone.inspect} (expected auto/copy/reflink)"
+            end
+            h["clone"] = clone
+          end
+          h
         else
           raise ArgumentError,
-            "unknown root_disk kind #{kind.inspect} (expected managed/tmpfs/disk)"
+            "unknown root_disk kind #{kind.inspect} (expected managed/tmpfs/disk/flat)"
         end
       end
 
@@ -1116,6 +1230,21 @@ module Microsandbox
         exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
     end
 
+    # Run the image's resolved OCI `ENTRYPOINT` and `CMD` — the **default
+    # workload** (runtime v0.6.9) — and collect output. {Sandbox.create} is
+    # strictly boot-only, so this is how the image's own command gets
+    # executed; override the durable CMD at create time via `cmd:`.
+    #
+    # Options match {#exec} minus the command itself.
+    # @return [ExecOutput]
+    # @raise [NoDefaultCommandError] when the image's effective entrypoint and
+    #   CMD resolve to no executable command
+    def exec_default(cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
+      ExecOutput.new(@native.exec_default(
+        exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)
+      ))
+    end
+
     # Run a command and stream its output as it arrives.
     #
     # Pass +stdin: :pipe+ to feed the process interactively: {ExecHandle#stdin}
@@ -1142,6 +1271,17 @@ module Microsandbox
         exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)))
     end
 
+    # Run the default workload (see {#exec_default}) and stream its output.
+    # @note Like {#exec_stream}, +timeout:+ is accepted but **not applied** on
+    #   the streaming path.
+    # @return [ExecHandle]
+    # @raise [NoDefaultCommandError] when no executable default command resolves
+    def exec_default_stream(cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
+      ExecHandle.new(@native.exec_default_stream(
+        exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)
+      ))
+    end
+
     # Attach an interactive terminal to a command in the sandbox.
     #
     # Puts the **host** terminal into raw mode and forwards keystrokes (and
@@ -1181,6 +1321,32 @@ module Microsandbox
       @native.attach_shell
     end
 
+    # Attach an interactive terminal to the image's resolved OCI `ENTRYPOINT`
+    # and `CMD` — the default workload (runtime v0.6.9). See {#attach} for the
+    # host-TTY requirements and {#exec_default} for default-workload semantics.
+    #
+    # @param cwd [String, nil] working directory
+    # @param user [String, nil] user to run as
+    # @param env [Hash, nil] extra environment variables
+    # @param detach_keys [String, nil] detach sequence (default "ctrl-]")
+    # @param rlimits [Hash, nil] resource limits (see {#exec})
+    # @return [Integer] the workload's exit code (or the code at detach)
+    # @raise [NoDefaultCommandError] when no executable default command resolves
+    def attach_default(cwd: nil, user: nil, env: nil, detach_keys: nil, rlimits: nil)
+      opts = {}
+      opts["cwd"] = cwd.to_s if cwd
+      opts["user"] = user.to_s if user
+      opts["env"] = env.each_with_object({}) { |(k, v), a| a[k.to_s] = v.to_s } if env
+      opts["detach_keys"] = detach_keys.to_s if detach_keys
+      if rlimits
+        opts["rlimits"] = rlimits.map do |resource, limit|
+          soft, hard = limit.is_a?(Array) ? [limit[0], limit[1]] : [limit, limit]
+          [resource.to_s, Integer(soft), Integer(hard)]
+        end
+      end
+      @native.attach_default(opts)
+    end
+
     # Guest filesystem operations.
     # @return [FS]
     def fs
@@ -1241,6 +1407,11 @@ module Microsandbox
     # @param max_cpus [Integer, nil] desired boot-time maximum vCPU ceiling
     # @param memory [Integer, nil] desired effective guest memory in MiB
     # @param max_memory [Integer, nil] desired boot-time maximum memory (MiB)
+    # @param root_disk_size [Integer, nil] desired root-disk size in MiB
+    #   (runtime v0.6.9): grows the sandbox-owned managed upper or flat root
+    #   disk. Growth-only, applied while the sandbox is stopped —
+    #   restart/next-start semantics and backing-specific limits are enforced
+    #   by the runtime
     # @param env [Hash, nil] environment variables to set for future execs
     # @param remove_env [Array<String>, nil] environment variable names to remove
     # @param labels [Hash, nil] labels to set
@@ -1406,8 +1577,9 @@ module Microsandbox
       when :pipe
         unless pipe_ok
           raise ArgumentError,
-            "stdin: :pipe is only valid for exec_stream/shell_stream — a blocking " \
-            "exec/shell cannot expose a writable stdin sink; pass a String to feed bytes"
+            "stdin: :pipe is only valid for the streaming variants (exec_stream/" \
+            "shell_stream/exec_default_stream) — a blocking exec cannot expose a " \
+            "writable stdin sink; pass a String to feed bytes"
         end
         opts["stdin_pipe"] = true
       when Symbol

data/lib/microsandbox/snapshot.rb

@@ -115,19 +115,21 @@ module Microsandbox
     end
   end
 
-  # The result of {Snapshot.verify}. Schema-1 descriptors always record
-  # integrity, so a returned report is always `:verified` — an integrity
-  # mismatch raises {SnapshotIntegrityError} instead of returning.
+  # The result of {Snapshot.verify}. Since runtime v0.6.9 payload integrity is
+  # recorded only when the snapshot was created with `record_integrity: true`:
+  # such snapshots report `:verified` (an integrity mismatch raises
+  # {SnapshotIntegrityError} instead of returning), snapshots without recorded
+  # integrity report `:not_recorded` with `algorithm`/`content_digest` nil.
   class SnapshotVerifyReport
     # @return [String] descriptor digest
     attr_reader :digest
     # @return [String] artifact directory path
     attr_reader :path
-    # @return [Symbol] :verified
+    # @return [Symbol] :verified or :not_recorded
     attr_reader :status
-    # @return [String] digest algorithm
+    # @return [String, nil] digest algorithm (nil when :not_recorded)
     attr_reader :algorithm
-    # @return [String] matched content digest
+    # @return [String, nil] matched content digest (nil when :not_recorded)
     attr_reader :content_digest
 
     def initialize(data)
@@ -161,8 +163,10 @@ module Microsandbox
       #   is written at `dest_dir/<name>` (default: the snapshots dir)
       # @param labels [Hash, nil] user labels
       # @param force [Boolean] overwrite an existing artifact at the destination
-      # @param record_integrity [Boolean] accepted for compatibility; schema-1
-      #   descriptors always record integrity, so this is a no-op
+      # @param record_integrity [Boolean] record persistent payload integrity
+      #   (a Merkle content digest) in the artifact — opt-in since runtime
+      #   v0.6.9 because hashing large allocated uppers is expensive; without
+      #   it {Snapshot.verify} reports `:not_recorded`
       # @param resumable [Boolean] request a resumable (memory+device) snapshot;
       #   raises {UnsupportedError} until VM pause/resume lands upstream
       # @return [SnapshotInfo]

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.12.0"
+  VERSION = "0.14.0"
 
   # 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.6.8"
+  RUNTIME_VERSION = "v0.6.9"
 end

data/lib/microsandbox/volume.rb

@@ -13,6 +13,7 @@ module Microsandbox
       @name = data["name"]
       @path = data["path"]
       @kind = data["kind"]
+      @default = data["default"]
       @quota_mib = data["quota_mib"]
       @used_bytes = data["used_bytes"]
       @capacity_bytes = data["capacity_bytes"]
@@ -28,6 +29,13 @@ module Microsandbox
       @kind&.to_sym
     end
 
+    # Whether this is the backend's default volume (runtime v0.6.9, see
+    # {Volume.get_default}).
+    # @return [Boolean]
+    def default?
+      !!@default
+    end
+
     # @return [Time, nil]
     def created_at
       @created_at_ms && Time.at(@created_at_ms / 1000.0)
@@ -154,6 +162,14 @@ module Microsandbox
         VolumeInfo.new(Native::Volume.get(name.to_s))
       end
 
+      # The backend's default volume (runtime v0.6.9). Cloud backend only —
+      # the full {VolumeInfo#fs} surface works against it; the local backend
+      # raises {UnsupportedError} to avoid accidental host access.
+      # @return [VolumeInfo]
+      def get_default
+        VolumeInfo.new(Native::Volume.get_default)
+      end
+
       # All volumes.
       # @return [Array<VolumeInfo>]
       def list

data/lib/microsandbox.rb

@@ -17,6 +17,7 @@ rescue LoadError
 end
 
 require_relative "microsandbox/errors"
+require_relative "microsandbox/backend_info"
 require_relative "microsandbox/exec_output"
 require_relative "microsandbox/exec_handle"
 require_relative "microsandbox/fs"
@@ -63,12 +64,13 @@ module Microsandbox
     # Download and install the `msb` runtime + `libkrunfw` into
     # `~/.microsandbox` (idempotent).
     #
-    # When the gem is built from source, the native extension provisions the
-    # runtime at build time, so this is usually a no-op. Precompiled platform
-    # gems (which skip the local Rust build) do NOT provision it that way, so the
-    # runtime is fetched on first use — see {ensure_runtime!}. Call this
-    # explicitly to provision ahead of time (e.g. while baking a container
-    # image) so the first {Sandbox.create} doesn't pay the download.
+    # This gem is SDK-only: nothing is provisioned at build/install time. The
+    # runtime comes from the companion `microsandbox-rb-binaries` gem when it is
+    # installed (see {ensure_runtime!}); otherwise it is fetched into
+    # `~/.microsandbox` on first use. Call this explicitly to provision ahead of
+    # time (e.g. while baking a container image) so the first {Sandbox.create}
+    # doesn't pay the download. Not needed — and not used — when the binaries
+    # gem supplies the runtime.
     # @return [nil]
     def install
       Native.install
@@ -101,10 +103,14 @@ module Microsandbox
 
     # 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.
+    # {Sandbox.create}/{Sandbox.start} so a freshly installed gem gets a working
+    # runtime without a manual {install} step.
     #
-    # Runs at most once per process. Opt out by setting
+    # Runs at most once per process. When the companion `microsandbox-rb-binaries`
+    # gem supplies the runtime (it was activated at load time and its `msb` is
+    # what the resolver now returns from {runtime_path}), nothing is downloaded
+    # or touched in `~/.microsandbox` — the bundled binaries are already the
+    # matching version. Opt out of the download by setting
     # `MICROSANDBOX_NO_AUTO_INSTALL` (e.g. air-gapped hosts that provision the
     # runtime out of band); the runtime is then left untouched and a missing or
     # stale one surfaces at the operation itself.
@@ -128,6 +134,14 @@ 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
+      # The binaries gem won the resolver: its vendored msb (and the libkrunfw
+      # beside it) are exactly the version this gem was built for, so there is
+      # nothing to verify or download. (If `MSB_PATH` overrides it, the user owns
+      # the runtime and we fall through to the existing behaviour.)
+      if bundled_runtime_active?
+        @runtime_ready = true
+        return
+      end
       # 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.
@@ -138,7 +152,8 @@ module Microsandbox
 
       unless installed?
         warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
-             "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip)..."
+             "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip, " \
+             "or install the microsandbox-rb-binaries gem to ship it with your bundle)..."
       end
       install
       @runtime_ready = true
@@ -154,9 +169,17 @@ module Microsandbox
     # resolver, below only the `MSB_PATH` environment variable). Process-level
     # and set-once: a second call is silently ignored, and the `MSB_PATH`
     # environment variable still wins. Mirrors {libkrunfw_path=}.
+    #
+    # The companion `microsandbox-rb-binaries` gem claims this same slot when
+    # `require "microsandbox"` activates it, so with that gem installed this
+    # setter is a no-op — use `MSB_PATH` to override a bundled runtime.
     # @param path [String]
     # @return [void]
     def runtime_path=(path)
+      if @bundled_msb_path && path.to_s != @bundled_msb_path
+        warn "[microsandbox] runtime_path= ignored: the microsandbox-rb-binaries gem already " \
+             "claimed the set-once SDK slot (#{@bundled_msb_path}); set MSB_PATH to override it"
+      end
       Native.set_runtime_msb_path(path.to_s)
     end
 
@@ -172,9 +195,13 @@ module Microsandbox
 
     # Install a process-wide default backend (v0.5.8 backend routing). Without a
     # call to this, operations use a local libkrun backend; the env/profile
-    # ladder (`MSB_BACKEND`, `MSB_API_URL`+`MSB_API_KEY`, `MSB_PROFILE`,
-    # `~/.microsandbox/config.json`) is resolved lazily on first use. Call once
-    # at startup, before any sandbox operations.
+    # ladder (`MSB_BACKEND` → `MSB_PROFILE` → `~/.microsandbox/config.json`) is
+    # resolved lazily on first use. Since runtime v0.6.9 a bare `MSB_API_KEY`
+    # no longer selects the cloud — cloud intent must be explicit via
+    # `MSB_BACKEND=cloud` (paired with `MSB_API_URL`/`MSB_API_KEY`), a cloud
+    # profile, or this method; invalid cloud config raises
+    # {InvalidConfigError} instead of falling back to local. Call once at
+    # startup, before any sandbox operations.
     #
     # @param kind ["local","cloud", Symbol] backend kind
     # @param url [String, nil] cloud control-plane URL (cloud, unless `profile:`)
@@ -216,6 +243,14 @@ module Microsandbox
       Native.default_backend_kind.to_sym
     end
 
+    # Secret-safe description of the active default backend (runtime v0.6.9).
+    # Like {default_backend_kind}, the first call freezes ambient env/profile
+    # resolution for the process. The API key is never included.
+    # @return [BackendInfo]
+    def default_backend_info
+      BackendInfo.new(Native.default_backend_info)
+    end
+
     # Latest resource-usage snapshot for every running sandbox, keyed by name.
     # Mirrors the official `all_sandbox_metrics`/`allSandboxMetrics` helpers.
     # @return [Hash{String => Metrics}]
@@ -244,5 +279,101 @@ module Microsandbox
       v = ENV["MICROSANDBOX_NO_AUTO_INSTALL"]
       !v.nil? && !v.empty? && !%w[0 false no].include?(v.downcase)
     end
+
+    # Wire the companion `microsandbox-rb-binaries` gem into the core resolver.
+    # Runs once, at `require "microsandbox"` time (like the Node SDK, which pushes
+    # its platform package's msb into the same set-once SDK slot at module load)
+    # so every entry point that spawns msb — not just {Sandbox.create} — sees it.
+    #
+    # The gem is optional and has no dependency edge to this one (cloud-only
+    # users skip the ~50 MB download; RubyGems has no optional dependencies), so
+    # discovery is by require: absent → nothing happens and the resolver's lower
+    # tiers (`~/.microsandbox`, then `PATH`) plus the first-use download take
+    # over. Present but built for a different upstream runtime → warn and skip
+    # it rather than hand the core a mismatched msb (a stale runtime passes an
+    # exists-check and then fails every create on a wire-protocol mismatch).
+    # Only `MSB_PATH` (env) outranks the slot claimed here.
+    #
+    # Never raises: a broken companion gem must not take `require "microsandbox"`
+    # down with it.
+    # @return [String, nil] the activated msb path
+    def activate_bundled_runtime!
+      @bundled_msb_path = nil
+      begin
+        # Pin the lockstep version when RubyGems (not Bundler) picks the gem, so
+        # a newer/older companion left around doesn't get activated over the
+        # matching one. Under Bundler the Gemfile already decides; a companion
+        # that isn't in the bundle raises here and `require` then fails below.
+        gem "microsandbox-rb-binaries", "= #{VERSION}"
+      rescue Gem::LoadError
+        # Not installed at this version — `require` settles it.
+      end
+      begin
+        require "microsandbox/binaries"
+      rescue LoadError
+        return nil
+      end
+      # A bare require activates the newest gem of ANY name that ships this
+      # feature path; only accept the companion gem itself, this gem's own tree
+      # (a source checkout, where Bundler's path gem spans the whole repo and so
+      # owns binaries/lib too), or a plain load path (RUBYLIB/-I) no gem owns.
+      owner = bundled_runtime_owner
+      if owner && !TRUSTED_BINARIES_OWNERS.include?(owner)
+        warn "[microsandbox] ignoring microsandbox/binaries provided by the #{owner} gem " \
+             "(only microsandbox-rb-binaries is trusted for the bundled runtime)"
+        return nil
+      end
+      # Lockstep gate on BOTH constants. The runtime tag is what the wire
+      # protocol depends on; the gem version is the documented contract
+      # ("install both at the same version") and also covers this file's own
+      # API/packaging — the `gem "…", "= VERSION"` pin above is best-effort (it
+      # raises under Bundler whenever the bundle picked any other version, and
+      # that is swallowed), so it cannot be what enforces it.
+      unless Binaries::VERSION == VERSION && Binaries::RUNTIME_VERSION == RUNTIME_VERSION
+        warn "[microsandbox] ignoring microsandbox-rb-binaries #{Binaries::VERSION} " \
+             "(runtime #{Binaries::RUNTIME_VERSION}): microsandbox-rb #{VERSION} " \
+             "(runtime #{RUNTIME_VERSION}) needs the companion gem at the same version. " \
+             "Install both gems at the same version; falling back to ~/.microsandbox."
+        return nil
+      end
+      msb = Binaries.msb_path
+      unless msb && Binaries.libkrunfw_path
+        warn "[microsandbox] microsandbox-rb-binaries #{Binaries::VERSION} is installed but " \
+             "carries no runtime under #{Binaries.root}; falling back to ~/.microsandbox."
+        return nil
+      end
+      Native.set_runtime_msb_path(msb)
+      @bundled_msb_path = msb
+    rescue StandardError, ScriptError => e
+      # ScriptError too: a corrupt or newer-syntax binaries.rb raises
+      # SyntaxError (not a StandardError) out of `require`, and the optional
+      # companion must never take `require "microsandbox"` down with it.
+      warn "[microsandbox] could not activate microsandbox-rb-binaries: #{e.class}: #{e.message}"
+      nil
+    end
+
+    # Gems allowed to provide `microsandbox/binaries` (see activate_bundled_runtime!).
+    TRUSTED_BINARIES_OWNERS = %w[microsandbox-rb-binaries microsandbox-rb].freeze
+    private_constant :TRUSTED_BINARIES_OWNERS
+
+    # Name of the loaded gem whose files define Microsandbox::Binaries, or nil
+    # when it came from a bare load path.
+    def bundled_runtime_owner
+      source = Binaries.method(:msb_path).source_location&.first
+      return nil unless source
+      spec = Gem.loaded_specs.values.find { |s| source.start_with?(File.join(s.full_gem_path, "")) }
+      spec&.name
+    end
+
+    # Whether the binaries gem's msb is what the resolver actually returns — i.e.
+    # it was activated and nothing higher in the ladder (`MSB_PATH`) overrides it.
+    def bundled_runtime_active?
+      return false unless @bundled_msb_path
+      runtime_path == @bundled_msb_path
+    rescue Microsandbox::Error
+      false
+    end
   end
+
+  send(:activate_bundled_runtime!)
 end