microsandbox-rb 0.5.9 → 0.5.10

data/lib/microsandbox/sandbox.rb

@@ -1,41 +1,119 @@
 # frozen_string_literal: true
 
 module Microsandbox
-  # Lightweight metadata about a sandbox, returned by {Sandbox.get} and
-  # {Sandbox.list}. This is a snapshot, not a live handle.
-  class SandboxInfo
+  # A controllable handle to a sandbox, returned by {Sandbox.get}, {Sandbox.list},
+  # and {Sandbox.list_with}. Carries a metadata snapshot (captured when fetched)
+  # plus the fine-grained lifecycle surface — `stop_with_timeout`, `request_stop`,
+  # `request_kill`, `request_drain`, `wait_until_stopped` — that mirrors the
+  # official SDKs' `SandboxHandle`. (The live {Sandbox} from {Sandbox.create}/
+  # {Sandbox.start} carries only the high-level `stop`/`kill`/`drain`/`wait`.)
+  #
+  # As of v0.5.8 this replaces the old read-only `SandboxInfo` (kept as a
+  # deprecated constant alias); `#status` here is a synchronous snapshot.
+  class SandboxHandle
+    def initialize(native)
+      @native = native
+    end
+
     # @return [String]
-    attr_reader :name
-    # @return [Symbol] :running, :draining, :paused, :stopped, or :crashed
-    attr_reader :status
+    def name = @native.name
 
-    def initialize(data)
-      @name = data["name"]
-      @status = data["status"].to_sym
-      @created_at_ms = data["created_at_ms"]
-      @updated_at_ms = data["updated_at_ms"]
-    end
+    # @return [Symbol] :created, :starting, :running, :draining, :paused,
+    #   :stopped, or :crashed (a snapshot, captured when this handle was fetched)
+    def status = @native.status.to_sym
 
-    def running? = @status == :running
-    def stopped? = @status == :stopped
+    # Whether the fetch-time {#status} snapshot is `:running` / `:stopped`.
+    # Like {#status}, these do NOT refresh: to observe a state change after
+    # {#request_stop}/{#request_kill}/{#request_drain}, use {#wait_until_stopped}
+    # or re-fetch the handle with {Sandbox.get}.
+    def running? = status == :running
+    def stopped? = status == :stopped
 
     # @return [Time, nil]
     def created_at
-      @created_at_ms && Time.at(@created_at_ms / 1000.0)
+      ms = @native.created_at_ms
+      ms && Time.at(ms / 1000.0)
     end
 
     # @return [Time, nil]
     def updated_at
-      @updated_at_ms && Time.at(@updated_at_ms / 1000.0)
+      ms = @native.updated_at_ms
+      ms && Time.at(ms / 1000.0)
+    end
+
+    # Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default).
+    # @return [nil]
+    def stop
+      @native.stop
+      nil
+    end
+
+    # Gracefully stop with a custom escalation timeout.
+    # @param timeout [Numeric] seconds to wait before escalating to SIGKILL
+    # @return [nil]
+    def stop_with_timeout(timeout)
+      @native.stop_with_timeout(Sandbox.send(:coerce_duration, timeout, "timeout"))
+      nil
+    end
+
+    # Force-kill the sandbox (SIGKILL).
+    # @return [nil]
+    def kill
+      @native.kill
+      nil
+    end
+
+    # Force-kill, waiting up to `timeout` seconds for the process to disappear.
+    # @param timeout [Numeric]
+    # @return [nil]
+    def kill_with_timeout(timeout)
+      @native.kill_with_timeout(Sandbox.send(:coerce_duration, timeout, "timeout"))
+      nil
+    end
+
+    # Send the graceful-shutdown request and return immediately, without waiting.
+    # Pair with {#wait_until_stopped}.
+    # @return [nil]
+    def request_stop
+      @native.request_stop
+      nil
+    end
+
+    # Send the force-kill request and return immediately, without waiting.
+    # @return [nil]
+    def request_kill
+      @native.request_kill
+      nil
+    end
+
+    # Request a graceful drain (SIGUSR1) and return immediately, without waiting.
+    # @return [nil]
+    def request_drain
+      @native.request_drain
+      nil
+    end
+
+    # Block until the sandbox is observed in a terminal (non-running) state.
+    # @return [SandboxStopResult]
+    def wait_until_stopped
+      SandboxStopResult.new(@native.wait_until_stopped)
     end
 
     def inspect
-      "#<Microsandbox::SandboxInfo name=#{@name.inspect} status=#{@status}>"
+      "#<Microsandbox::SandboxHandle name=#{name.inspect} status=#{status}>"
     end
   end
 
+  # @deprecated since v0.5.8. {Sandbox.get}/{Sandbox.list} now return a
+  #   controllable {SandboxHandle}; this constant remains as an alias so code
+  #   that referenced the old read-only metadata type by name (e.g. `is_a?`
+  #   checks) still resolves. Note it is now the same class as {SandboxHandle},
+  #   whose constructor takes a native handle, not the metadata Hash the old
+  #   `SandboxInfo.new` accepted — construct via {Sandbox.get}/{Sandbox.list}.
+  SandboxInfo = SandboxHandle
+
   # The terminal observation of a stopped sandbox, returned by
-  # {Sandbox#wait_until_stopped}. Mirrors the official SDKs' `SandboxStopResult`.
+  # {SandboxHandle#wait_until_stopped}. Mirrors the official SDKs' `SandboxStopResult`.
   class SandboxStopResult
     # @return [String]
     attr_reader :name
@@ -67,7 +145,7 @@ module Microsandbox
 
     def inspect
       "#<Microsandbox::SandboxStopResult name=#{@name.inspect} status=#{@status}" \
-        "#{@exit_code ? " exit_code=#{@exit_code}" : ""}#{@signal ? " signal=#{@signal}" : ""}>"
+        "#{" exit_code=#{@exit_code}" if @exit_code}#{" signal=#{@signal}" if @signal}>"
     end
   end
 
@@ -143,15 +221,21 @@ module Microsandbox
       # @yieldparam sandbox [Sandbox]
       # @return [Sandbox, Object] the sandbox, or the block's return value
       def create(name,
-                 image: nil, cpus: nil, 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,
-                 patches: nil,
-                 from_snapshot: nil, log_level: nil, quiet_logs: false, security: nil,
-                 oci_upper_size: nil, max_duration: nil, idle_timeout: nil, rlimits: nil,
-                 pull_policy: nil, registry_auth: nil, registry_insecure: false,
-                 registry_ca_certs: nil, secrets: nil,
-                 detached: false, replace: false, replace_with_timeout: nil)
+        image: nil, cpus: nil, 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,
+        patches: nil,
+        from_snapshot: nil, log_level: nil, quiet_logs: false, security: nil,
+        oci_upper_size: nil, max_duration: nil, idle_timeout: nil, rlimits: nil,
+        pull_policy: nil, registry_auth: nil, registry_insecure: false,
+        registry_ca_certs: nil, secrets: nil,
+        detached: false, replace: false, replace_with_timeout: nil)
+        # A sandbox boots from exactly one rootfs source. The core would reject a
+        # contradictory pair, but only after a runtime round-trip; fail fast and
+        # clearly here (the Python SDK validates this the same way).
+        if image && from_snapshot
+          raise ArgumentError, "provide either image: or from_snapshot:, not both"
+        end
         Microsandbox.ensure_runtime!
         opts = {}
         opts["image"] = image.to_s if image
@@ -183,7 +267,7 @@ module Microsandbox
         opts["secrets"] = normalize_secrets(secrets) if secrets
         opts["detached"] = true if detached
         if replace_with_timeout
-          opts["replace_with_timeout"] = Float(replace_with_timeout)
+          opts["replace_with_timeout"] = coerce_duration(replace_with_timeout, "replace_with_timeout")
         elsif replace
           opts["replace"] = true
         end
@@ -206,27 +290,27 @@ module Microsandbox
       # @return [Sandbox]
       def start(name, detached: false)
         Microsandbox.ensure_runtime!
-        new(Native::Sandbox.start(name.to_s, { "detached" => detached }))
+        new(Native::Sandbox.start(name.to_s, {"detached" => detached}))
       end
 
-      # Fetch metadata for a sandbox by name.
-      # @return [SandboxInfo]
+      # Fetch a controllable handle for a sandbox by name (running or not).
+      # @return [SandboxHandle]
       def get(name)
-        SandboxInfo.new(Native::Sandbox.get(name.to_s))
+        SandboxHandle.new(Native::Sandbox.get(name.to_s))
       end
 
-      # List all sandboxes.
-      # @return [Array<SandboxInfo>]
+      # List all sandboxes as controllable handles.
+      # @return [Array<SandboxHandle>]
       def list
-        Native::Sandbox.list.map { |info| SandboxInfo.new(info) }
+        Native::Sandbox.list.map { |h| SandboxHandle.new(h) }
       end
 
       # List sandboxes carrying all of the given labels (AND-matched).
       # @param labels [Hash] required key => value labels
-      # @return [Array<SandboxInfo>]
+      # @return [Array<SandboxHandle>]
       def list_with(labels: {})
-        opts = { "labels" => stringify(labels) }
-        Native::Sandbox.list_with(opts).map { |info| SandboxInfo.new(info) }
+        opts = {"labels" => stringify(labels)}
+        Native::Sandbox.list_with(opts).map { |h| SandboxHandle.new(h) }
       end
 
       # Remove a (stopped) sandbox by name.
@@ -238,6 +322,19 @@ module Microsandbox
 
       private
 
+      # Coerce a seconds value to a finite, non-negative Float. Rejects negatives,
+      # NaN, and infinities *here* (a clean ArgumentError) rather than letting them
+      # reach the native layer, where `Duration::from_secs_f64` panics across the
+      # FFI boundary on exactly those inputs. Shared by every duration option.
+      def coerce_duration(value, label)
+        seconds = Float(value)
+        unless seconds.finite? && seconds >= 0
+          raise ArgumentError,
+            "#{label} must be a finite, non-negative number of seconds (got #{value.inspect})"
+        end
+        seconds
+      end
+
       def stringify(hash)
         hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
       end
@@ -256,7 +353,7 @@ module Microsandbox
           unless username && password
             # Report only the keys given, never the values — auth carries secrets.
             raise ArgumentError,
-                  "registry_auth needs :username and :password (got keys: #{auth.keys.inspect})"
+              "registry_auth needs :username and :password (got keys: #{auth.keys.inspect})"
           end
           opts["registry_username"] = username.to_s
           opts["registry_password"] = password.to_s
@@ -358,33 +455,39 @@ module Microsandbox
     # @param env [Hash, nil] extra environment variables
     # @param timeout [Numeric, nil] kill after N seconds
     # @param tty [Boolean] allocate a pseudo-terminal
-    # @param stdin [String, nil] data to feed to stdin
+    # @param stdin [String, Symbol, nil] bytes to feed to stdin, or +:pipe+ to
+    #   open a streaming stdin pipe (write/close it via {ExecHandle#stdin}; only
+    #   useful with the streaming variants)
     # @return [ExecOutput]
     def exec(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
       ExecOutput.new(@native.exec(command.to_s, Array(args).map(&:to_s),
-                                  exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+        exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
     end
 
     # Run a shell script (pipes, redirects, etc. allowed) and collect output.
     # @return [ExecOutput]
     def shell(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
       ExecOutput.new(@native.shell(script.to_s,
-                                   exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+        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}
+    # then returns a writable sink; close it to send EOF (a process like +cat+
+    # that reads until EOF will otherwise block forever).
     # @return [ExecHandle]
     # @see ExecHandle
     def exec_stream(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
       ExecHandle.new(@native.exec_stream(command.to_s, Array(args).map(&:to_s),
-                                         exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+        exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)))
     end
 
     # Run a shell script and stream its output as it arrives.
     # @return [ExecHandle]
     def shell_stream(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
       ExecHandle.new(@native.shell_stream(script.to_s,
-                                          exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
+        exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)))
     end
 
     # Attach an interactive terminal to a command in the sandbox.
@@ -469,7 +572,7 @@ module Microsandbox
     # @param interval [Numeric] seconds between snapshots
     # @return [MetricsStream] an {Enumerable} of {Metrics}
     def metrics_stream(interval: 1.0)
-      MetricsStream.new(@native.metrics_stream(Float(interval)))
+      MetricsStream.new(@native.metrics_stream(coerce_duration(interval, "interval")))
     end
 
     # Stream captured logs as they appear.
@@ -492,48 +595,46 @@ module Microsandbox
       LogStream.new(@native.log_stream(opts))
     end
 
-    # Gracefully stop the sandbox (and wait for it to terminate).
-    # @param timeout [Numeric, nil] seconds to wait before SIGKILL
+    # Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default) and
+    # wait for it to terminate. For a custom timeout or fire-and-return
+    # `request_*` control, fetch a {SandboxHandle} via {Sandbox.get}.
     # @return [nil]
-    def stop(timeout: nil)
-      @native.stop(timeout && Float(timeout))
+    def stop
+      @native.stop
       nil
     end
 
-    # Force-kill the sandbox (SIGKILL).
-    # @param timeout [Numeric, nil] seconds to wait
-    # @return [nil]
-    def kill(timeout: nil)
-      @native.kill(timeout && Float(timeout))
-      nil
+    # Gracefully stop, then wait for the process to exit.
+    # @return [ExitStatus]
+    def stop_and_wait
+      ExitStatus.new(@native.stop_and_wait)
     end
 
-    # Send the graceful-shutdown request and return immediately, without waiting
-    # for the sandbox to terminate. Pair with {#wait_until_stopped}.
+    # Force-kill the sandbox (SIGKILL).
     # @return [nil]
-    def request_stop
-      @native.request_stop
+    def kill
+      @native.kill
       nil
     end
 
-    # Send the force-kill request and return immediately, without waiting.
+    # Trigger a graceful drain (SIGUSR1).
     # @return [nil]
-    def request_kill
-      @native.request_kill
+    def drain
+      @native.drain
       nil
     end
 
-    # Request a graceful drain and return immediately, without waiting.
-    # @return [nil]
-    def request_drain
-      @native.request_drain
-      nil
+    # Wait for the sandbox process to exit.
+    # @return [ExitStatus]
+    def wait
+      ExitStatus.new(@native.wait)
     end
 
-    # Block until the sandbox is observed in a terminal (non-running) state.
-    # @return [SandboxStopResult]
-    def wait_until_stopped
-      SandboxStopResult.new(@native.wait_until_stopped)
+    # The live status, fetched from the backend (a round-trip per call).
+    # @return [Symbol] :created, :starting, :running, :draining, :paused,
+    #   :stopped, or :crashed
+    def status
+      @native.status.to_sym
     end
 
     # @return [Boolean] whether this handle owns the sandbox process lifecycle
@@ -556,14 +657,37 @@ module Microsandbox
 
     private
 
-    def exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)
+    # Instance-side shim for the shared, class-private duration validator (used
+    # by #exec/#shell timeouts, #stop/#kill, and #metrics_stream).
+    def coerce_duration(value, label)
+      self.class.send(:coerce_duration, value, label)
+    end
+
+    def exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: false)
       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["timeout"] = Float(timeout) if timeout
+      opts["timeout"] = coerce_duration(timeout, "timeout") if timeout
       opts["tty"] = true if tty
-      opts["stdin"] = stdin.to_s if stdin
+      # `stdin: :pipe` opens a streaming stdin pipe — write to it via
+      # {ExecHandle#stdin} and close to send EOF. It is only meaningful for the
+      # streaming variants (which return an ExecHandle); a blocking exec/shell
+      # collects to completion and has nowhere to hand back the sink, so a piped
+      # process that reads stdin would block forever waiting for EOF. Reject it
+      # there. Any other truthy value is fed as a fixed byte buffer (closed
+      # automatically). nil means no stdin.
+      case stdin
+      when nil then nil
+      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"
+        end
+        opts["stdin_pipe"] = true
+      else opts["stdin"] = stdin.to_s
+      end
       if rlimits
         opts["rlimits"] = rlimits.map do |resource, limit|
           soft, hard = limit.is_a?(Array) ? [limit[0], limit[1]] : [limit, limit]

data/lib/microsandbox/snapshot.rb

@@ -43,7 +43,7 @@ module Microsandbox
     end
 
     def inspect
-      "#<Microsandbox::SnapshotInfo digest=#{@digest.inspect}#{@name ? " name=#{@name.inspect}" : ""}>"
+      "#<Microsandbox::SnapshotInfo digest=#{@digest.inspect}#{" name=#{@name.inspect}" if @name}>"
     end
   end
 
@@ -142,7 +142,7 @@ module Microsandbox
       # @param dest [String, nil] explicit destination directory
       # @return [SnapshotInfo]
       def import(archive_path, dest: nil)
-        SnapshotInfo.new(Native::Snapshot.import(archive_path.to_s, dest && dest.to_s))
+        SnapshotInfo.new(Native::Snapshot.import(archive_path.to_s, dest&.to_s))
       end
 
       private

data/lib/microsandbox/ssh.rb

@@ -218,7 +218,7 @@ module Microsandbox
     # @yieldparam client [SshClient]
     # @return [SshClient, Object]
     def open_client(user: "root", term: nil, sftp: true)
-      opts = { "user" => user.to_s, "sftp" => sftp ? true : false }
+      opts = {"user" => user.to_s, "sftp" => sftp ? true : false}
       opts["term"] = term.to_s if term
       client = SshClient.new(@native.ssh_open_client(opts))
       return client unless block_given?
@@ -237,7 +237,7 @@ module Microsandbox
     # @param sftp [Boolean] enable the SFTP subsystem (default true)
     # @return [SshServer]
     def prepare_server(host_key_path: nil, authorized_keys_path: nil, user: nil, sftp: true)
-      opts = { "sftp" => sftp ? true : false }
+      opts = {"sftp" => sftp ? true : false}
       opts["host_key_path"] = host_key_path.to_s if host_key_path
       opts["authorized_keys_path"] = authorized_keys_path.to_s if authorized_keys_path
       opts["user"] = user.to_s if user

data/lib/microsandbox/version.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Microsandbox
-  # Gem version. Tracks the upstream microsandbox runtime (currently `v0.5.7`,
+  # Gem version. Tracks the upstream microsandbox runtime (currently `v0.5.8`,
   # the pinned core-crate tag); the patch segment advances for gem-only revisions
   # that add bindings atop the same core. Must equal the native ext's Cargo crate
   # version (`Native.version`), enforced by spec/unit/version_spec.rb.
-  VERSION = "0.5.9"
+  VERSION = "0.5.10"
 end

data/lib/microsandbox/volume.rb

@@ -7,7 +7,7 @@ module Microsandbox
   # (`kind`, `used_bytes`, …) are populated when returned from {Volume.get}/{Volume.list}.
   class VolumeInfo
     attr_reader :name, :path, :quota_mib, :used_bytes, :capacity_bytes,
-                :disk_format, :disk_fstype, :labels
+      :disk_format, :disk_fstype, :labels
 
     def initialize(data)
       @name = data["name"]
@@ -33,7 +33,7 @@ module Microsandbox
     end
 
     def inspect
-      "#<Microsandbox::VolumeInfo name=#{@name.inspect}#{@kind ? " kind=#{@kind}" : ""}>"
+      "#<Microsandbox::VolumeInfo name=#{@name.inspect}#{" kind=#{@kind}" if @kind}>"
     end
   end
 
@@ -49,7 +49,7 @@ module Microsandbox
       # @param labels [Hash, nil]
       # @return [VolumeInfo]
       def create(name, kind: "dir", size_mib: nil, quota_mib: nil, labels: nil)
-        opts = { "kind" => kind.to_s }
+        opts = {"kind" => kind.to_s}
         opts["size_mib"] = Integer(size_mib) if size_mib
         opts["quota_mib"] = Integer(quota_mib) if quota_mib
         opts["labels"] = labels.each_with_object({}) { |(k, v), a| a[k.to_s] = v.to_s } if labels

data/lib/microsandbox.rb

@@ -78,6 +78,11 @@ module Microsandbox
     # @return [nil]
     def ensure_runtime!
       return if @runtime_ready
+      # A cloud backend has no local msb/libkrunfw runtime to provision: skip the
+      # presence check and the first-use download entirely. Resolving the kind
+      # 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?
         @runtime_ready = true
         return
@@ -104,6 +109,62 @@ module Microsandbox
       Native.set_runtime_msb_path(path.to_s)
     end
 
+    # Override the `libkrunfw` shared-library path (SDK tier of the resolver,
+    # below the `MSB_LIBKRUNFW_PATH` environment variable). Process-level and
+    # set-once: a second call is silently ignored, and the env var still wins.
+    # Mirrors {runtime_path=} for libkrunfw.
+    # @param path [String]
+    # @return [void]
+    def libkrunfw_path=(path)
+      Native.set_runtime_libkrunfw_path(path.to_s)
+    end
+
+    # 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.
+    #
+    # @param kind ["local","cloud", Symbol] backend kind
+    # @param url [String, nil] cloud control-plane URL (cloud, unless `profile:`)
+    # @param api_key [String, nil] cloud API key (cloud, unless `profile:`)
+    # @param profile [String, nil] named profile from `~/.microsandbox/config.json`
+    # @return [void]
+    def set_default_backend(kind, url: nil, api_key: nil, profile: nil)
+      Native.set_default_backend(kind.to_s, url&.to_s, api_key&.to_s, profile&.to_s)
+    end
+
+    # Run the given block with a temporary default backend, restoring the
+    # previous one afterward (even on error). NOTE: the swap is process-wide
+    # while the block runs, not fiber/thread-local — concurrent threads observe
+    # the temporary backend. It is also NOT safe to call from multiple threads
+    # at once: two interleaved `with_backend` calls can restore each other's
+    # saved backend out of order and leave a temporary backend installed
+    # permanently. Use it only when no other thread is changing the backend, and
+    # avoid calling {set_default_backend} inside the block (the restore on exit
+    # would overwrite that change). Mirrors the official SDKs' scoped-backend helper.
+    #
+    # @param kind ["local","cloud", Symbol]
+    # @param url [String, nil]
+    # @param api_key [String, nil]
+    # @param profile [String, nil]
+    # @yield with the temporary backend installed
+    # @return [Object] the block's return value
+    def with_backend(kind, url: nil, api_key: nil, profile: nil)
+      token = Native.push_default_backend(kind.to_s, url&.to_s, api_key&.to_s, profile&.to_s)
+      begin
+        yield
+      ensure
+        Native.pop_default_backend(token)
+      end
+    end
+
+    # @return [Symbol] the active default backend kind, :local or :cloud.
+    #   The first call resolves the env/profile/config ladder.
+    def default_backend_kind
+      Native.default_backend_kind.to_sym
+    end
+
     # Latest resource-usage snapshot for every running sandbox, keyed by name.
     # Mirrors the official `all_sandbox_metrics`/`allSandboxMetrics` helpers.
     # @return [Hash{String => Metrics}]