microsandbox-rb 0.10.0 → 0.12.0

data/lib/microsandbox/image.rb

@@ -107,6 +107,44 @@ module Microsandbox
       def prune
         ImagePruneReport.new(Native::Image.prune)
       end
+
+      # Load images into the cache from a local `docker save` tarball or an
+      # OCI Image Layout archive. Pass `"-"` to read the archive from `$stdin`
+      # (spooled to a temp file first, like the Python SDK — the core reads
+      # seekable files only). Mirrors the Python `Image.load` / Node
+      # `imageLoad` (runtime v0.6.7).
+      # @param input_path [String] archive path (or "-")
+      # @param tag [String, Array<String>, nil] retag the loaded image(s)
+      # @return [Array<ImageInfo>] one entry per loaded image
+      def load(input_path, tag: nil)
+        tags = Array(tag).map(&:to_s)
+        path = input_path.to_s
+        if path == "-"
+          require "tempfile"
+          Tempfile.create(["msb-image-load", ".tar"]) do |tmp|
+            tmp.binmode
+            IO.copy_stream($stdin, tmp)
+            tmp.flush
+            return Native::Image.load(tmp.path, tags).map { |info| ImageInfo.new(info) }
+          end
+        end
+        Native::Image.load(path, tags).map { |info| ImageInfo.new(info) }
+      end
+
+      # Save cached image(s) into a local archive.
+      # Mirrors the Python `Image.save` / Node `imageSave` (runtime v0.6.7).
+      # @param reference [String, Array<String>] image reference(s) to save
+      # @param output_path [String] destination archive path
+      # @param format [:docker, :oci] archive layout (default :docker, the
+      #   shape `docker load` expects)
+      # @return [nil]
+      def save(reference, output_path:, format: :docker)
+        refs = Array(reference).map(&:to_s)
+        raise ArgumentError, "at least one image reference is required" if refs.empty?
+
+        Native::Image.save(refs, output_path.to_s, format.to_s)
+        nil
+      end
     end
   end
 end

data/lib/microsandbox/network.rb

@@ -62,6 +62,24 @@ module Microsandbox
       build("deny", destination, direction, protocol, protocols, port, ports)
     end
 
+    # Allow plain DNS (UDP/53 and TCP/53) to the sandbox gateway — the rule
+    # the composable profiles prepend automatically. Use it in custom policies
+    # that need name resolution. Expands to the same rule as the core's
+    # `Rule::allow_dns` (egress → group :host, udp+tcp, port 53).
+    # @return [Hash]
+    def allow_dns
+      {"action" => "allow", "direction" => "egress",
+       "destination_kind" => "group", "destination" => "host",
+       "protocols" => %w[udp tcp], "ports" => ["53"]}
+    end
+
+    # Deny plain DNS to the sandbox gateway — the deny counterpart of
+    # {allow_dns}, useful as an override placed before profile-generated rules.
+    # @return [Hash]
+    def deny_dns
+      allow_dns.merge("action" => "deny")
+    end
+
     # @api private
     def build(action, destination, direction, protocol, protocols, port, ports)
       rule = {"action" => action, "direction" => direction.to_s}
@@ -84,20 +102,29 @@ module Microsandbox
     end
   end
 
-  # A sandbox network policy: a preset, or a custom set of allow/deny {Rule}s
-  # with per-direction default actions and bulk domain denials.
+  # A sandbox network policy: composed profiles, a terminal preset, or a custom
+  # set of allow/deny {Rule}s with per-direction default actions and bulk
+  # domain denials.
   #
-  # Pass to {Sandbox.create} via `network:` — either a {NetworkPolicy}, a preset
-  # name (String/Symbol), or a plain Hash with the same keys as {custom}.
+  # Pass to {Sandbox.create} via `network:` — a {NetworkPolicy}, an Array of
+  # profile names (`[:public, :host]`), a single profile or preset name
+  # (String/Symbol), or a plain Hash with the same keys as {custom}.
   #
-  # @example presets
-  #   Sandbox.create("b", image: "alpine", network: NetworkPolicy.public_only)
+  # Profiles (runtime v0.6.7) compose: `:public` (public internet), `:private`
+  # (LAN/private ranges), `:host` (the host machine/gateway). Any non-empty
+  # combination automatically allows gateway DNS. The default policy — public
+  # internet only — equals `from_profiles(:public)`.
+  #
+  # @example profiles
+  #   Sandbox.create("b", image: "alpine", network: [:public, :private])
   #   Sandbox.create("b", image: "alpine", network: :none)
+  #   Sandbox.create("b", image: "alpine", network: NetworkPolicy.from_profiles(:host))
   #
   # @example custom
   #   policy = Microsandbox::NetworkPolicy.custom(
   #     default_egress: :deny,
   #     rules: [
+  #       Microsandbox::Rule.allow_dns,
   #       Microsandbox::Rule.allow(destination: "api.openai.com", protocol: :tcp, port: "443"),
   #     ],
   #     deny_domain_suffixes: [".ads.example"],
@@ -106,18 +133,47 @@ module Microsandbox
   #
   # Mirrors `NetworkPolicy` / `Network` in the official Python/Node/Go SDKs.
   class NetworkPolicy
-    # Canonical preset names keyed by every accepted alias.
+    # Composable profile names (runtime v0.6.7).
+    PROFILES = %w[public private host].freeze
+
+    # Canonical preset names keyed by every accepted alias. Only the terminal
+    # presets survive v0.6.7; the removed ones get migration guidance in
+    # {canonical_preset}.
     PRESET_ALIASES = {
       "none" => "none", "disabled" => "none", "disable" => "none", "airgapped" => "none",
-      "public" => "public_only", "public_only" => "public_only", "public-only" => "public_only",
-      "default" => "public_only",
-      "all" => "allow_all", "allow_all" => "allow_all", "allow-all" => "allow_all",
-      "non_local" => "non_local", "non-local" => "non_local", "nonlocal" => "non_local"
+      "all" => "allow_all", "allow_all" => "allow_all", "allow-all" => "allow_all"
+    }.freeze
+
+    # Removed v0.6.6 preset spellings → the exact profile replacement, used to
+    # build actionable migration errors. (`public_only` expanded to precisely
+    # `from_profiles(:public)`, `non_local` to `from_profiles(:public, :private)` —
+    # the replacements are rule-for-rule equivalent.)
+    REMOVED_PRESETS = {
+      "public_only" => "network: [:public] (or NetworkPolicy.from_profiles(:public); " \
+        "this is still the default policy)",
+      "public-only" => "network: [:public]",
+      "non_local" => "network: [:public, :private] " \
+        "(or NetworkPolicy.from_profiles(:public, :private))",
+      "non-local" => "network: [:public, :private]",
+      "nonlocal" => "network: [:public, :private]"
     }.freeze
 
     class << self
-      # @return [NetworkPolicy] allow only public internet (the default)
-      def public_only = preset("public_only")
+      # Compose a policy from network profiles (`:public`, `:private`, `:host`).
+      # Order and duplicates don't matter — the runtime expands the set into a
+      # canonical rule list plus a gateway-DNS allow. An empty set is a valid
+      # deny-egress/allow-ingress policy with no rules (and no DNS).
+      # @return [NetworkPolicy]
+      def from_profiles(*profiles)
+        list = normalize_profiles(profiles)
+        if list.empty?
+          # Same semantics as the runtime's from_profiles([]) — expressed as an
+          # explicit empty custom policy so the wire needs no empty-array case.
+          custom(default_egress: :deny, default_ingress: :allow, rules: [])
+        else
+          new("profiles" => list)
+        end
+      end
 
       # @return [NetworkPolicy] block all network access
       def none = preset("none")
@@ -125,19 +181,17 @@ module Microsandbox
       # @return [NetworkPolicy] permit all traffic
       def allow_all = preset("allow_all")
 
-      # @return [NetworkPolicy] allow public internet plus private/LAN egress
-      def non_local = preset("non_local")
-
-      # @return [NetworkPolicy] a bare preset policy
+      # @return [NetworkPolicy] a bare preset policy (:none or :allow_all)
       def preset(name)
         new("preset" => canonical_preset(name))
       end
 
       # Build a custom policy — an ordered rule list with per-direction default
-      # actions. A custom policy stands on its own (no preset); to start from a
-      # preset, use the preset factories (optionally with `deny_domains:` via the
-      # Hash form passed to {Sandbox.create}). `preset:` and custom rules/defaults
-      # are mutually exclusive, mirroring the official SDKs.
+      # actions. A custom policy stands on its own; to start from a profile
+      # base, use the Hash form passed to {Sandbox.create} (`profiles:` composes
+      # with `rules:`/deny lists). A terminal `preset:` stays exclusive with
+      # custom rules/defaults, mirroring the official SDKs. Custom policies
+      # need an explicit {Rule.allow_dns} if the sandbox should resolve names.
       #
       # @param default_egress [:deny, :allow, nil] fall-through for unmatched
       #   outbound traffic (default :deny)
@@ -163,26 +217,64 @@ module Microsandbox
       def coerce(network)
         case network
         when NetworkPolicy then network.to_h
-        when String, Symbol then {"preset" => canonical_preset(network)}
+        when Array then from_profiles(*network).to_h
+        when String, Symbol then coerce_name(network)
         when Hash then from_hash(network)
         else
           raise ArgumentError,
-            "network: expects a preset name, a Microsandbox::NetworkPolicy, or a Hash " \
+            "network: expects profile(s) (:public/:private/:host, or an Array of them), " \
+            "a preset (:none/:allow_all), a Microsandbox::NetworkPolicy, or a Hash " \
             "(got #{network.class})"
         end
       end
 
       private
 
-      # A `network:` Hash is either a preset (`preset:` + optional deny lists) or
-      # a custom policy (`default_egress:`/`default_ingress:`/`rules:` + optional
-      # deny lists). The two are mutually exclusive: a preset already defines its
-      # rules and defaults, so layering custom rules/defaults on top would silently
-      # override them (and diverge from the official SDKs, where preset and custom
-      # are separate paths). A bare preset (only `preset:`, no deny lists) is
-      # routed to the preset path by {Sandbox.create}, so its own defaults apply.
+      # A bare String/Symbol names a single profile (`:public`/`:private`/
+      # `:host`) or a terminal preset (`:none`/`:allow_all` and aliases).
+      # `"default"` stays accepted and means the default policy, which is
+      # exactly the `:public` profile.
+      def coerce_name(name)
+        key = name.to_s.downcase
+        return {"profiles" => [key]} if PROFILES.include?(key)
+        return {"profiles" => ["public"]} if key == "default"
+
+        {"preset" => canonical_preset(key)}
+      end
+
+      # Validate + stringify a profile list. Removed-preset spellings get the
+      # same migration guidance here as in {canonical_preset}, since
+      # `network: [:non_local]` is a plausible mis-migration.
+      def normalize_profiles(profiles)
+        Array(profiles).flatten.map do |p|
+          key = p.to_s.downcase
+          next key if PROFILES.include?(key)
+
+          if (replacement = REMOVED_PRESETS[key])
+            raise ArgumentError,
+              "#{p.inspect} is a removed v0.6.6 network preset, not a profile; use #{replacement}"
+          end
+          raise ArgumentError,
+            "unknown network profile #{p.inspect} (expected :public/:private/:host)"
+        end
+      end
+
+      # A `network:` Hash is composed profiles (`profiles:` + optional rules/
+      # defaults/deny lists), a terminal preset (`preset:` + optional deny
+      # lists), or a custom policy (`default_egress:`/`default_ingress:`/
+      # `rules:` + optional deny lists). Profiles compose with everything —
+      # they expand to an ordinary rule base that explicit rules append to —
+      # but a preset stays exclusive with rules/defaults: it already defines
+      # its rules and defaults, so layering more on top would silently override
+      # them. A bare preset or bare profile list is routed to its dedicated
+      # wire key by {Sandbox.create}, so the runtime's own expansion applies.
       def from_hash(hash)
         sym = hash.transform_keys(&:to_sym)
+        profiles = sym.key?(:profiles) ? normalize_profiles(sym[:profiles]) : nil
+        if profiles && sym.key?(:preset)
+          raise ArgumentError, "network profiles: and preset: are mutually exclusive"
+        end
+
         if sym.key?(:preset)
           if sym.key?(:rules) || sym.key?(:default_egress) || sym.key?(:default_ingress)
             raise ArgumentError,
@@ -193,6 +285,18 @@ module Microsandbox
           h = {"preset" => canonical_preset(sym[:preset])}
           add_deny_lists(h, sym[:deny_domains], sym[:deny_domain_suffixes])
           h
+        elsif profiles
+          h = {}
+          h["profiles"] = profiles unless profiles.empty?
+          h["default_egress"] = action_str(sym[:default_egress]) if sym[:default_egress]
+          h["default_ingress"] = action_str(sym[:default_ingress]) if sym[:default_ingress]
+          rules = Array(sym[:rules]).map { |r| normalize_rule(r) }
+          h["rules"] = rules unless rules.empty?
+          add_deny_lists(h, sym[:deny_domains], sym[:deny_domain_suffixes])
+          # `profiles: []` alone is the runtime's empty composed policy:
+          # deny-egress/allow-ingress with no rules (and no DNS).
+          h = {"default_egress" => "deny", "default_ingress" => "allow", "rules" => []} if h.empty?
+          h
         elsif sym.key?(:rules) || sym.key?(:default_egress) || sym.key?(:default_ingress)
           # An explicit custom policy: the caller chose the rule list and/or the
           # fall-through defaults (which default to :deny / :allow).
@@ -231,10 +335,14 @@ module Microsandbox
 
       def canonical_preset(name)
         key = name.to_s.downcase
+        if (replacement = REMOVED_PRESETS[key])
+          raise ArgumentError,
+            "the #{name.inspect} network preset was removed in runtime v0.6.7; use #{replacement}"
+        end
         PRESET_ALIASES[key] ||
           raise(ArgumentError,
             "unknown network preset #{name.inspect} " \
-            "(expected one of public_only/none/allow_all/non_local)")
+            "(expected none/allow_all, or profiles :public/:private/:host)")
       end
 
       def action_str(action)

data/lib/microsandbox/root_disk.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Factory for an OCI sandbox's writable **root disk** spec (runtime v0.6.7),
+  # passed to {Sandbox.create} via `root_disk:`. Three kinds:
+  #
+  # - {managed} — the default: a sparse ext4 upper file created and resized by
+  #   the runtime (4 GiB cap when no size is given). A bare Integer passed to
+  #   `root_disk:` means the same thing.
+  # - {tmpfs} — RAM-backed upper, so the rootfs is pristine on every boot.
+  #   Default size is half the sandbox memory; the size must not exceed sandbox
+  #   memory (no swap in the guest). Cannot be snapshotted or patched.
+  # - {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.
+  #
+  # @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"))
+  #
+  # Mirrors the `RootDisk` factory in the official Python/Node/Go SDKs.
+  module RootDisk
+    module_function
+
+    # The managed sparse-ext4 upper (the default kind).
+    # @param size_mib [Integer, nil] size cap in MiB (default 4096)
+    # @return [Hash]
+    def managed(size_mib = nil)
+      h = {"kind" => "managed"}
+      h["size_mib"] = Integer(size_mib) if size_mib
+      h
+    end
+
+    # A RAM-backed tmpfs upper — pristine rootfs on every boot.
+    # @param size_mib [Integer, nil] size in MiB (default: half sandbox memory)
+    # @return [Hash]
+    def tmpfs(size_mib = nil)
+      h = {"kind" => "tmpfs"}
+      h["size_mib"] = Integer(size_mib) if size_mib
+      h
+    end
+
+    # A user-supplied disk image attached writable as the upper.
+    # @param path [String] path to the image file
+    # @param format ["raw", "qcow2", nil] image format (inferred from the
+    #   .img/.raw/.qcow2 extension when omitted)
+    # @param fstype [String, nil] filesystem type inside the image, e.g. "ext4"
+    # @return [Hash]
+    def disk(path, format: nil, fstype: nil)
+      h = {"kind" => "disk", "path" => path.to_s}
+      h["format"] = format.to_s if format
+      h["fstype"] = fstype.to_s if fstype
+      h
+    end
+  end
+end

data/lib/microsandbox/sandbox.rb

@@ -142,20 +142,16 @@ module Microsandbox
 
     # Snapshot this (stopped) sandbox under a bare name, resolved under the
     # snapshots dir. Convenience equivalent of
-    # `Snapshot.create(name, name: <snapshot-name>)` addressed by this handle.
+    # `Snapshot.create(<snapshot-name>, from_sandbox: <this sandbox>)`.
+    # (`snapshot_to(path)` was removed in 0.11.0 with runtime v0.6.7 — for
+    # explicit placement use `Snapshot.create(name, from_sandbox:, dest_dir:)`;
+    # the artifact lands at `dest_dir/<name>`.)
     # @param name [String] destination snapshot name
     # @return [SnapshotInfo]
     def snapshot(name)
       SnapshotInfo.new(@native.snapshot(name.to_s))
     end
 
-    # Snapshot this (stopped) sandbox to an explicit filesystem path.
-    # @param path [String] destination directory
-    # @return [SnapshotInfo]
-    def snapshot_to(path)
-      SnapshotInfo.new(@native.snapshot_to(path.to_s))
-    end
-
     def inspect
       "#<Microsandbox::SandboxHandle name=#{name.inspect} status=#{status}>"
     end
@@ -206,6 +202,48 @@ module Microsandbox
     end
   end
 
+  # One page of sandbox handles, returned by {Sandbox.list} and
+  # {Sandbox.list_with} — sandbox listing is cursor-paginated as of runtime
+  # v0.6.8. Enumerable over its {SandboxHandle}s; fetch the following page by
+  # passing {#next_cursor} to {Sandbox.list_with}.
+  #
+  # @example Walk every page
+  #   page = Microsandbox::Sandbox.list
+  #   loop do
+  #     page.each { |h| puts h.name }
+  #     break if page.last_page?
+  #     page = Microsandbox::Sandbox.list_with(cursor: page.next_cursor)
+  #   end
+  class SandboxPage
+    include Enumerable
+
+    # @return [Array<SandboxHandle>] the sandboxes in this page
+    attr_reader :sandboxes
+    # @return [String, nil] opaque cursor for the next page; nil on the final page
+    attr_reader :next_cursor
+
+    # @api private — construct via {Sandbox.list}/{Sandbox.list_with}.
+    def initialize(sandboxes, next_cursor)
+      @sandboxes = sandboxes
+      @next_cursor = next_cursor
+    end
+
+    def each(&) = @sandboxes.each(&)
+
+    # @return [Integer]
+    def size = @sandboxes.size
+    alias_method :length, :size
+
+    def empty? = @sandboxes.empty?
+
+    # Whether this is the final page (no cursor to continue from).
+    def last_page? = @next_cursor.nil?
+
+    def inspect
+      "#<Microsandbox::SandboxPage size=#{size} next_cursor=#{@next_cursor.inspect}>"
+    end
+  end
+
   # A running sandbox (microVM) — the primary entry point of the SDK.
   #
   # @example Block form (auto-stops on exit)
@@ -262,13 +300,18 @@ module Microsandbox
       #   `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
-      #   describing a custom policy (`default_egress:`, `default_ingress:`,
-      #   `rules:`, `deny_domains:`, `deny_domain_suffixes:`). See {NetworkPolicy}
-      #   and {Rule}.
+      #   named volume, set its quota via {Volume.create}). Bind/named mounts
+      #   also accept `follow_root_symlinks: true` to opt out of the default-on
+      #   mount-root symlink protection (runtime v0.6.7).
+      # @param network [Array, String, Symbol, NetworkPolicy, Hash, nil] network
+      #   policy. Composable profiles (`[:public]` (the default), `[:public,
+      #   :private]`, `:host`, …), a terminal preset (:none, :allow_all), a
+      #   {NetworkPolicy} (e.g. {NetworkPolicy.from_profiles},
+      #   {NetworkPolicy.custom}), or a Hash describing a custom policy
+      #   (`profiles:`, `default_egress:`, `default_ingress:`, `rules:`,
+      #   `deny_domains:`, `deny_domain_suffixes:`). See {NetworkPolicy} and
+      #   {Rule}. The v0.6.6 `public_only`/`non_local` presets were removed in
+      #   runtime v0.6.7 — use `[:public]` / `[:public, :private]`.
       # @param dns [Hash, nil] custom DNS: `{ nameservers: [...],
       #   rebind_protection: true, query_timeout_ms: 2000 }`
       # @param tls [Hash, nil] TLS-interception tuning: `{ bypass: [...patterns],
@@ -296,7 +339,16 @@ module Microsandbox
       # @param log_level ["error","warn","info","debug","trace", nil] guest log verbosity
       # @param quiet_logs [Boolean] suppress sandbox process logs
       # @param security ["default", "restricted", nil] exec security profile
-      # @param oci_upper_size [Integer, nil] writable upper-layer size cap, in MiB
+      # @param root_disk [Integer, Hash, nil] the OCI sandbox's writable root
+      #   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
+      #   `RootDisk.disk("./scratch.img", format: "raw", fstype: "ext4")`
+      #   (user-supplied image attached writable).
+      # @param oci_upper_size [Integer, nil] deprecated alias for
+      #   `root_disk: <Integer>` (the managed kind); warns, and conflicts with
+      #   `root_disk:`
       # @param max_duration [Integer, nil] hard wall-clock lifetime, in seconds
       # @param idle_timeout [Integer, nil] stop after this many idle seconds
       # @param rlimits [Hash, nil] resource limits: { resource => limit } or
@@ -372,7 +424,7 @@ module Microsandbox
         patches: nil,
         from_snapshot: nil, fstype: nil, init: nil, ephemeral: false,
         log_level: nil, quiet_logs: false, security: nil,
-        oci_upper_size: nil, max_duration: nil, idle_timeout: nil, rlimits: nil,
+        root_disk: 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, on_secret_violation: nil,
         detached: false, replace: false, replace_with_timeout: nil)
@@ -382,6 +434,9 @@ module Microsandbox
         if image && from_snapshot
           raise ArgumentError, "provide either image: or from_snapshot:, not both"
         end
+        if root_disk && oci_upper_size
+          raise ArgumentError, "pass either root_disk: or oci_upper_size:, not both"
+        end
         Microsandbox.ensure_runtime!
         # `fstype:` names the inner filesystem of a disk-image rootfs, so it only
         # applies when `image:` is a disk-image path (a local path ending in
@@ -425,7 +480,14 @@ module Microsandbox
         opts["log_level"] = log_level.to_s if log_level
         opts["quiet_logs"] = true if quiet_logs
         opts["security"] = security.to_s if security
-        opts["oci_upper_size"] = Integer(oci_upper_size) if oci_upper_size
+        if oci_upper_size
+          warn "Microsandbox: oci_upper_size: is deprecated; use root_disk: " \
+               "(an Integer size in MiB, or RootDisk.managed/tmpfs/disk)",
+            uplevel: 2
+          opts["root_disk"] = coerce_root_disk_size(oci_upper_size, "oci_upper_size:")
+        elsif root_disk
+          opts["root_disk"] = normalize_root_disk(root_disk)
+        end
         opts["max_duration"] = Integer(max_duration) if max_duration
         opts["idle_timeout"] = Integer(idle_timeout) if idle_timeout
         opts["rlimits"] = normalize_rlimits(rlimits) if rlimits
@@ -458,18 +520,25 @@ module Microsandbox
         SandboxHandle.new(Native::Sandbox.get(name.to_s))
       end
 
-      # List all sandboxes as controllable handles.
-      # @return [Array<SandboxHandle>]
+      # List the first page of sandboxes (default page size 20) as controllable
+      # handles. Cursor-paginated as of runtime v0.6.8 — follow
+      # {SandboxPage#next_cursor} via {.list_with} for subsequent pages.
+      # @return [SandboxPage]
       def list
-        Native::Sandbox.list.map { |h| SandboxHandle.new(h) }
+        build_page(Native::Sandbox.list)
       end
 
-      # List sandboxes carrying all of the given labels (AND-matched).
-      # @param labels [Hash] required key => value labels
-      # @return [Array<SandboxHandle>]
-      def list_with(labels: {})
+      # List one configured page of sandboxes.
+      # @param labels [Hash] required key => value labels (AND-matched)
+      # @param limit [Integer, nil] page size, 1..100 (upstream default 20)
+      # @param cursor [String, nil] opaque cursor from a previous page's
+      #   {SandboxPage#next_cursor}
+      # @return [SandboxPage]
+      def list_with(labels: {}, limit: nil, cursor: nil)
         opts = {"labels" => stringify(labels)}
-        Native::Sandbox.list_with(opts).map { |h| SandboxHandle.new(h) }
+        opts["limit"] = Integer(limit) if limit
+        opts["cursor"] = cursor.to_s if cursor
+        build_page(Native::Sandbox.list_with(opts))
       end
 
       # Remove a (stopped) sandbox by name.
@@ -498,6 +567,15 @@ module Microsandbox
         hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v.to_s }
       end
 
+      # Wrap a native page Hash ({"sandboxes" => [...], "next_cursor" => ...})
+      # into a {SandboxPage} of {SandboxHandle}s.
+      def build_page(data)
+        SandboxPage.new(
+          data["sandboxes"].map { |h| SandboxHandle.new(h) },
+          data["next_cursor"]
+        )
+      end
+
       def intify_ports(ports)
         ports.each_with_object({}) { |(k, v), acc| acc[Integer(k)] = Integer(v) }
       end
@@ -816,6 +894,58 @@ module Microsandbox
       #   { 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); a bind mount may carry quota_mib:.
+      # Coerce the `root_disk:` argument — an Integer (managed size in MiB), a
+      # {RootDisk} factory Hash, or an equivalent hand-written Hash — into the
+      # wire shape, validating kind/field combinations up front (mirrors the
+      # Python SDK's extract_root_disk guards).
+      def normalize_root_disk(root_disk)
+        return coerce_root_disk_size(root_disk, "root_disk:") unless root_disk.is_a?(Hash)
+
+        spec = root_disk.transform_keys(&:to_s)
+        kind = (spec["kind"] || "managed").to_s
+        case kind
+        when "managed", "tmpfs"
+          %w[path format fstype].each do |key|
+            if spec[key]
+              raise ArgumentError, "root_disk #{key}: is only valid for the disk kind"
+            end
+          end
+          h = {"kind" => kind}
+          if spec["size_mib"]
+            h["size_mib"] = coerce_root_disk_size(spec["size_mib"], "root_disk size_mib:")
+          end
+          h
+        when "disk", "disk-image", "disk_image"
+          path = spec["path"]
+          if path.nil? || path.to_s.empty?
+            raise ArgumentError, "root_disk disk kind requires path:"
+          end
+          if spec["size_mib"]
+            raise ArgumentError, "root_disk size_mib: is not valid for a disk image " \
+              "(the image file determines the size)"
+          end
+          h = {"kind" => "disk", "path" => path.to_s}
+          h["format"] = spec["format"].to_s if spec["format"]
+          h["fstype"] = spec["fstype"].to_s if spec["fstype"]
+          h
+        else
+          raise ArgumentError,
+            "unknown root_disk kind #{kind.inspect} (expected managed/tmpfs/disk)"
+        end
+      end
+
+      # Coerce + range-check a root-disk size. The wire carries u32 MiB; an
+      # out-of-range value would otherwise surface as a confusing ext-level
+      # type error (or a raw RangeError from the native conversion).
+      def coerce_root_disk_size(value, label)
+        mib = Integer(value)
+        unless mib.positive? && mib <= 4_294_967_295
+          raise ArgumentError,
+            "#{label} must be a positive size in MiB that fits in 32 bits (got #{mib})"
+        end
+        mib
+      end
+
       def normalize_volumes(volumes)
         volumes.map do |guest, spec|
           mount = {"guest" => guest.to_s}
@@ -868,6 +998,9 @@ module Microsandbox
       # read-only; `noexec:`/`nosuid:`/`nodev:` set the matching flags;
       # `stat_virtualization:`/`host_permissions:` set the passthrough policies
       # (only valid on bind/named — the core rejects them on tmpfs/disk).
+      # `follow_root_symlinks:` opts out of the default-on mount-root symlink
+      # protection (runtime v0.6.7; bind/named only — the core silently ignores
+      # it on tmpfs/disk mounts, so reject those here instead).
       def apply_mount_flags(mount, spec)
         mount["readonly"] = true if spec[:ro] || spec["ro"] || spec[:readonly] || spec["readonly"]
         mount["noexec"] = true if spec[:noexec] || spec["noexec"]
@@ -878,6 +1011,15 @@ module Microsandbox
         mount["stat_virtualization"] = sv.to_s if sv
         hp = spec[:host_permissions] || spec["host_permissions"]
         mount["host_permissions"] = hp.to_s if hp
+        follow = spec.fetch(:follow_root_symlinks, spec["follow_root_symlinks"])
+        unless follow.nil?
+          unless %w[bind named].include?(mount["kind"])
+            raise ArgumentError,
+              "follow_root_symlinks: only applies to bind/named mounts " \
+              "(got a #{mount["kind"]} mount); a #{mount["kind"]} mount has no host root to protect"
+          end
+          mount["follow_root_symlinks"] = !!follow
+        end
       end
 
       # Translate the pre-0.7.0 `options:` array form (e.g. options: %w[ro noexec])
@@ -918,16 +1060,18 @@ module Microsandbox
         end
       end
 
-      # Route the `network:` argument to either the preset path
-      # (`opts["network"]`, the original string-preset behavior) or the custom
-      # policy path (`opts["network_policy"]`). Accepts a preset String/Symbol, a
-      # {NetworkPolicy}, or a plain Hash.
+      # Route the `network:` argument to the preset path (`opts["network"]`),
+      # the composed-profiles path (`opts["network_profiles"]`), or the custom
+      # policy path (`opts["network_policy"]`). Accepts profile Symbol(s)/Array,
+      # a preset String/Symbol, a {NetworkPolicy}, or a plain Hash.
       def apply_network_opts(opts, network)
         norm = NetworkPolicy.coerce(network)
         return if norm.empty? # e.g. network: {} — leave the default policy in place
 
         if norm.keys == ["preset"]
           opts["network"] = norm["preset"]
+        elsif norm.keys == ["profiles"]
+          opts["network_profiles"] = norm["profiles"]
         else
           opts["network_policy"] = norm
         end