microsandbox-rb 0.9.2 → 0.11.0

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

@@ -116,22 +116,42 @@ module Microsandbox
       JSON.parse(@native.config_json)
     end
 
+    # Health-check the guest agent without refreshing the idle timer. Connects
+    # to the running sandbox and sends `core.ping`; a stopped sandbox raises
+    # {SandboxNotRunningError} (it is not started implicitly). Mirrors the
+    # official SDKs' `ping`.
+    # @return [PingResult]
+    def ping
+      PingResult.new(@native.ping)
+    end
+
+    # Explicitly refresh this sandbox's idle-activity timer. A stopped sandbox
+    # raises {SandboxNotRunningError}. Mirrors the official SDKs' `touch`.
+    # @return [TouchResult]
+    def touch
+      TouchResult.new(@native.touch)
+    end
+
+    # Plan or apply a live modification of this sandbox. See {Sandbox#modify} for
+    # the full option set.
+    # @return [ModificationPlan]
+    def modify(**kwargs)
+      opts = Sandbox.send(:build_modify_opts, **kwargs)
+      ModificationPlan.new(JSON.parse(@native.modify(opts)))
+    end
+
     # 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
@@ -213,7 +233,12 @@ module Microsandbox
       # @param name [String] sandbox name (max 128 UTF-8 bytes)
       # @param image [String, nil] OCI image reference (e.g. "python")
       # @param cpus [Integer, nil] number of vCPUs
+      # @param max_cpus [Integer, nil] boot-time maximum vCPU ceiling a later live
+      #   {Sandbox#modify} can grow up to (defaults to `cpus`; must be >= `cpus`)
       # @param memory [Integer, nil] memory in MiB
+      # @param max_memory [Integer, nil] boot-time maximum memory ceiling (MiB) a
+      #   later live {Sandbox#modify} can grow up to (defaults to `memory`; must
+      #   be >= `memory`)
       # @param env [Hash, nil] environment variables
       # @param workdir [String, nil] working directory inside the guest
       # @param shell [String, nil] default shell (for {#shell})
@@ -233,13 +258,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],
@@ -267,7 +297,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
@@ -334,7 +373,8 @@ module Microsandbox
 
       # @api private
       # Shared keyword-option builder for {create}/{create_with_progress}.
-      def build_create_opts(image: nil, cpus: nil, memory: nil, env: nil, workdir: nil,
+      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,
         dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil,
@@ -342,7 +382,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)
@@ -352,6 +392,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
@@ -370,7 +413,9 @@ module Microsandbox
         opts["from_snapshot"] = from_snapshot.to_s if from_snapshot
         opts["fstype"] = fstype.to_s if fstype
         opts["cpus"] = Integer(cpus) if cpus
+        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["workdir"] = workdir.to_s if workdir
         opts["shell"] = shell.to_s if shell
         opts["user"] = user.to_s if user
@@ -393,7 +438,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
@@ -522,6 +574,99 @@ module Microsandbox
         Array(secrets).map { |spec| normalize_secret(spec) }
       end
 
+      # @api private
+      # Shared keyword-option builder for {Sandbox#modify}/{SandboxHandle#modify}.
+      # Produces the string-keyed Hash the native `modify` reads. `policy` is
+      # 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,
+        env: nil, remove_env: nil, labels: nil, remove_labels: nil, workdir: nil,
+        secrets: nil, remove_secrets: nil, policy: nil, dry_run: false)
+        opts = {}
+        opts["cpus"] = Integer(cpus) if cpus
+        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["env"] = stringify(env) if env
+        opts["remove_env"] = Array(remove_env).map(&:to_s) if remove_env
+        opts["labels"] = stringify(labels) if labels
+        opts["remove_labels"] = Array(remove_labels).map(&:to_s) if remove_labels
+        opts["workdir"] = workdir.to_s if workdir
+        opts["secrets"] = normalize_modify_secrets(secrets) if secrets
+        opts["remove_secrets"] = Array(remove_secrets).map(&:to_s) if remove_secrets
+        opts["policy"] = normalize_modify_policy(policy)
+        opts["dry_run"] = true if dry_run
+        opts
+      end
+
+      # Normalize the `secrets:` modify option — a Hash of `{ name => spec }` —
+      # into the native array of specs, sorted by name for deterministic patch
+      # (and plan) ordering. The modify secret vocabulary differs from create's
+      # (source-or-value with `env:`/`store:`/`value:` mutually exclusive, keyed
+      # by secret name), mirroring the upstream `SecretModifySpec`.
+      def normalize_modify_secrets(secrets)
+        unless secrets.is_a?(Hash)
+          raise ArgumentError, "secrets: must be a Hash of { name => spec } (got #{secrets.class})"
+        end
+        out = secrets.map { |name, spec| normalize_modify_secret(name, spec) }
+          .sort_by { |h| h["name"] }
+        # A Symbol and a String key stringify to the same secret name, yielding
+        # two same-name specs. Upstream's fluent API dedupes those; the patch
+        # path we drive does not, and duplicates make the live value and the
+        # persisted config diverge nondeterministically — reject them loudly.
+        dup = out.group_by { |h| h["name"] }.find { |_, specs| specs.size > 1 }
+        if dup
+          raise ArgumentError,
+            "secrets: duplicate entries for #{dup.first.inspect} (a Symbol and a String key stringify to the same name)"
+        end
+        out
+      end
+
+      def normalize_modify_secret(name, spec)
+        spec ||= {}
+        unless spec.is_a?(Hash)
+          # Reject before any spec access: a non-Hash spec (e.g. the tempting
+          # `{ name => raw_value }` shorthand) must never reach a method call
+          # whose NoMethodError would embed the receiver — cleartext — in the
+          # message on Ruby < 3.3.
+          raise ArgumentError,
+            "secret #{name.to_s.inspect}: spec must be a Hash (e.g. { value: ... } or { env: ... }), got #{spec.class}"
+        end
+        env = fetch_opt(spec, :env)
+        value = fetch_opt(spec, :value)
+        store = fetch_opt(spec, :store)
+        present = {"env" => env, "value" => value, "store" => store}.reject { |_, v| v.nil? }
+        if present.size > 1
+          # Report only the conflicting KEYS, never the values — a secret spec's
+          # :value is cleartext and error messages routinely land in logs and
+          # error trackers. Mirrors normalize_secret above.
+          keys = present.keys.map(&:inspect).join(" and ")
+          raise ArgumentError,
+            "secret #{name.to_s.inspect}: #{keys} are mutually exclusive; set at most one"
+        end
+        out = {"name" => name.to_s}
+        out["env"] = env.to_s if env
+        out["value"] = value.to_s if value
+        out["store"] = store.to_s if store
+        pl = fetch_opt(spec, :placeholder)
+        out["placeholder"] = pl.to_s if pl
+        hosts = spec[:allowed_hosts] || spec["allowed_hosts"]
+        out["allowed_hosts"] = Array(hosts).map(&:to_s) if hosts
+        out
+      end
+
+      # Normalize the `policy:` modify option (Symbol or String) to the native
+      # string, defaulting to "no_restart".
+      def normalize_modify_policy(policy)
+        return "no_restart" if policy.nil?
+        s = policy.to_s
+        unless %w[no_restart next_start restart].include?(s)
+          raise ArgumentError,
+            "policy: must be :no_restart, :next_start, or :restart (got #{policy.inspect})"
+        end
+        s
+      end
+
       def normalize_secret(spec)
         env = spec[:env] || spec["env"]
         value = spec[:value] || spec["value"]
@@ -691,6 +836,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}
@@ -743,6 +940,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"]
@@ -753,6 +953,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])
@@ -793,16 +1002,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
@@ -941,6 +1152,57 @@ module Microsandbox
       Metrics.new(@native.metrics)
     end
 
+    # Health-check the guest agent without refreshing the idle timer. Sends
+    # `core.ping` to the running sandbox and reports the round-trip latency.
+    # Mirrors the official SDKs' `ping`.
+    # @return [PingResult]
+    def ping
+      PingResult.new(@native.ping)
+    end
+
+    # Explicitly refresh this sandbox's idle-activity timer (resetting any
+    # `idle_timeout:` countdown). Mirrors the official SDKs' `touch`.
+    # @return [TouchResult]
+    def touch
+      TouchResult.new(@native.touch)
+    end
+
+    # Plan or apply a live modification of this sandbox: resize CPU/memory,
+    # adjust env/labels/workdir, and rotate/remove secrets, without recreating
+    # the sandbox. The apply is all-or-nothing under the chosen `policy:`: the
+    # default `:no_restart` applies only changes that are live-capable *right
+    # now* and raises if any requested change needs a restart (on a running
+    # sandbox that includes env/labels/workdir and *adding* a secret — rotating
+    # or removing an existing one is live). Pass `policy: :next_start` to
+    # persist restart-required changes for the next start, or `:restart` to
+    # restart and apply them now; use `dry_run: true` to preview each change's
+    # disposition without applying anything. Mirrors the official SDKs'
+    # `modify`. Returns a {ModificationPlan} classifying each change.
+    #
+    # @param cpus [Integer, nil] desired effective vCPU count
+    # @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 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
+    # @param remove_labels [Array<String>, nil] label keys to remove
+    # @param workdir [String, nil] desired working directory for future execs
+    # @param secrets [Hash, nil] desired secret specs keyed by secret name. Each
+    #   spec is a Hash with at most one of `env:` (host env var to read),
+    #   `store:` (host secret-store reference), or `value:` (raw material), plus
+    #   optional `placeholder:` and `allowed_hosts:` (Array of host patterns).
+    # @param remove_secrets [Array<String>, nil] secret names to remove
+    # @param policy [Symbol, String, nil] `:no_restart` (default — apply only
+    #   changes that need no restart), `:next_start` (persist for the next
+    #   start), or `:restart` (restart to apply restart-required changes)
+    # @param dry_run [Boolean] compute the plan without applying anything
+    # @return [ModificationPlan]
+    def modify(**kwargs)
+      opts = Sandbox.send(:build_modify_opts, **kwargs)
+      ModificationPlan.new(JSON.parse(@native.modify(opts)))
+    end
+
     # Read captured logs.
     #
     # @param tail [Integer, nil] only the last N entries