microsandbox-rb 0.5.7 → 0.5.9

data/lib/microsandbox/network.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Factory for network-policy **rule destinations**. A destination is what an
+  # egress rule reaches (or, for an ingress rule, the connecting peer). Use the
+  # explicit constructors for unambiguous typing, or pass a plain String to
+  # {Rule.allow}/{Rule.deny} for shorthand classification (see {Rule}).
+  #
+  # @example
+  #   Microsandbox::Destination.cidr("10.0.0.0/8")
+  #   Microsandbox::Destination.domain("api.openai.com")
+  #   Microsandbox::Destination.group(:public)
+  #
+  # Mirrors the `Destination` factory in the official Python/Node/Go SDKs.
+  module Destination
+    module_function
+
+    # Match any destination.
+    def any = { "destination_kind" => "any" }
+
+    # A single IP address (stored as a /32 or /128).
+    def ip(value) = { "destination_kind" => "ip", "destination" => value.to_s }
+
+    # An IP network in CIDR notation (e.g. "10.0.0.0/8").
+    def cidr(value) = { "destination_kind" => "cidr", "destination" => value.to_s }
+
+    # An exact domain name (matched against the resolved-hostname cache / SNI).
+    def domain(value) = { "destination_kind" => "domain", "destination" => value.to_s }
+
+    # A domain suffix — matches the apex and any subdomain (e.g. ".internal").
+    def domain_suffix(value) = { "destination_kind" => "domain_suffix", "destination" => value.to_s }
+
+    # A predefined group: :public, :loopback, :private, :link_local, :metadata,
+    # :multicast, or :host.
+    def group(value) = { "destination_kind" => "group", "destination" => value.to_s.tr("_", "-") }
+  end
+
+  # Factory for a single network-policy **rule**. A rule pairs an action
+  # (allow/deny) with a direction, a destination, and optional protocol/port
+  # filters; rules are evaluated first-match-wins per direction.
+  #
+  # @example
+  #   Microsandbox::Rule.allow(destination: "1.1.1.1", protocol: :tcp, port: "443")
+  #   Microsandbox::Rule.deny(destination: Microsandbox::Destination.group(:metadata))
+  #   Microsandbox::Rule.allow(direction: :ingress, destination: "10.0.0.0/8", port: "8000-9000")
+  #
+  # `destination:` accepts a {Destination} Hash, a shorthand String
+  # ("*", "public", "1.1.1.1", "10.0.0.0/8", ".internal", "api.example.com"),
+  # or nil (any). Mirrors the `Rule` factory in the official SDKs.
+  module Rule
+    module_function
+
+    # Build an allow rule. See {Rule} for argument semantics.
+    # @return [Hash]
+    def allow(destination: nil, direction: :egress, protocol: nil, protocols: nil, port: nil, ports: nil)
+      build("allow", destination, direction, protocol, protocols, port, ports)
+    end
+
+    # Build a deny rule.
+    # @return [Hash]
+    def deny(destination: nil, direction: :egress, protocol: nil, protocols: nil, port: nil, ports: nil)
+      build("deny", destination, direction, protocol, protocols, port, ports)
+    end
+
+    # @api private
+    def build(action, destination, direction, protocol, protocols, port, ports)
+      rule = { "action" => action, "direction" => direction.to_s }
+      rule.merge!(normalize_destination(destination))
+      protos = (Array(protocols) + Array(protocol)).compact.map(&:to_s)
+      rule["protocols"] = protos unless protos.empty?
+      prts = (Array(ports) + Array(port)).compact.map(&:to_s)
+      rule["ports"] = prts unless prts.empty?
+      rule
+    end
+
+    # @api private
+    def normalize_destination(dest)
+      case dest
+      when nil then {}
+      when Hash then dest.each_with_object({}) { |(k, v), a| a[k.to_s] = v }
+      when String, Symbol then { "destination" => dest.to_s }
+      else raise ArgumentError, "invalid rule destination: #{dest.inspect}"
+      end
+    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.
+  #
+  # Pass to {Sandbox.create} via `network:` — either a {NetworkPolicy}, a 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)
+  #   Sandbox.create("b", image: "alpine", network: :none)
+  #
+  # @example custom
+  #   policy = Microsandbox::NetworkPolicy.custom(
+  #     default_egress: :deny,
+  #     rules: [
+  #       Microsandbox::Rule.allow(destination: "api.openai.com", protocol: :tcp, port: "443"),
+  #     ],
+  #     deny_domain_suffixes: [".ads.example"],
+  #   )
+  #   Sandbox.create("b", image: "alpine", network: policy)
+  #
+  # Mirrors `NetworkPolicy` / `Network` in the official Python/Node/Go SDKs.
+  class NetworkPolicy
+    # Canonical preset names keyed by every accepted alias.
+    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"
+    }.freeze
+
+    class << self
+      # @return [NetworkPolicy] allow only public internet (the default)
+      def public_only = preset("public_only")
+
+      # @return [NetworkPolicy] block all network access
+      def none = preset("none")
+
+      # @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
+      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.
+      #
+      # @param default_egress [:deny, :allow, nil] fall-through for unmatched
+      #   outbound traffic (default :deny)
+      # @param default_ingress [:deny, :allow, nil] fall-through for unmatched
+      #   inbound traffic (default :allow)
+      # @param rules [Array<Hash>] ordered {Rule}s (first match wins per direction)
+      # @param deny_domains [Array<String>] exact domains to deny egress to
+      #   (prepended, so they outrank later allow rules)
+      # @param deny_domain_suffixes [Array<String>] domain suffixes to deny
+      # @return [NetworkPolicy]
+      def custom(default_egress: :deny, default_ingress: :allow, rules: [],
+                 deny_domains: [], deny_domain_suffixes: [])
+        h = {}
+        h["default_egress"] = action_str(default_egress) unless default_egress.nil?
+        h["default_ingress"] = action_str(default_ingress) unless default_ingress.nil?
+        h["rules"] = Array(rules).map { |r| normalize_rule(r) }
+        add_deny_lists(h, deny_domains, deny_domain_suffixes)
+        new(h)
+      end
+
+      # Coerce a user-facing `network:` value into a normalized wire Hash.
+      # @api private
+      def coerce(network)
+        case network
+        when NetworkPolicy then network.to_h
+        when String, Symbol then { "preset" => canonical_preset(network) }
+        when Hash then from_hash(network)
+        else
+          raise ArgumentError,
+                "network: expects a preset name, 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.
+      def from_hash(hash)
+        sym = hash.transform_keys(&:to_sym)
+        if sym.key?(:preset)
+          if sym.key?(:rules) || sym.key?(:default_egress) || sym.key?(:default_ingress)
+            raise ArgumentError,
+                  "network preset: cannot be combined with rules:/default_egress:/" \
+                  "default_ingress: (the preset already defines its rules and defaults); " \
+                  "only deny_domains:/deny_domain_suffixes: may be layered on a preset"
+          end
+          h = { "preset" => canonical_preset(sym[:preset]) }
+          add_deny_lists(h, sym[:deny_domains], sym[:deny_domain_suffixes])
+          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).
+          custom(
+            default_egress: sym.fetch(:default_egress, :deny),
+            default_ingress: sym.fetch(:default_ingress, :allow),
+            rules: sym[:rules] || [],
+            deny_domains: sym[:deny_domains] || [],
+            deny_domain_suffixes: sym[:deny_domain_suffixes] || []
+          ).to_h
+        else
+          # Deny-list-only shorthand (`network: { deny_domains: [...] }`): keep the
+          # rest of the network reachable and just block the listed domains, using
+          # permissive defaults — mirrors the official SDKs' "full network minus
+          # blocked domains" semantics. An empty Hash is a no-op (leaves the
+          # default policy in place).
+          dd = Array(sym[:deny_domains]).map(&:to_s)
+          ds = Array(sym[:deny_domain_suffixes]).map(&:to_s)
+          return {} if dd.empty? && ds.empty?
+
+          h = { "default_egress" => "allow", "default_ingress" => "allow" }
+          add_deny_lists(h, dd, ds)
+          h
+        end
+      end
+
+      # Append `deny_domains`/`deny_domain_suffixes` to a wire Hash, omitting
+      # empty lists. Returns the Hash.
+      def add_deny_lists(h, deny_domains, deny_domain_suffixes)
+        dd = Array(deny_domains).map(&:to_s)
+        h["deny_domains"] = dd unless dd.empty?
+        ds = Array(deny_domain_suffixes).map(&:to_s)
+        h["deny_domain_suffixes"] = ds unless ds.empty?
+        h
+      end
+
+      def canonical_preset(name)
+        key = name.to_s.downcase
+        PRESET_ALIASES[key] ||
+          raise(ArgumentError,
+                "unknown network preset #{name.inspect} " \
+                "(expected one of public_only/none/allow_all/non_local)")
+      end
+
+      def action_str(action)
+        case action.to_s.downcase
+        when "allow" then "allow"
+        when "deny" then "deny"
+        else raise ArgumentError, "network action must be :allow or :deny (got #{action.inspect})"
+        end
+      end
+
+      # Canonicalize a rule Hash (from the {Rule} factory or hand-written) into
+      # the wire shape the native parser reads. Accepts singular `protocol`/`port`
+      # (the spelling the Go/Python `PolicyRule` use) as well as the plural
+      # `protocols`/`ports`, and a `destination` that is a shorthand String or a
+      # {Destination} Hash — so a hand-written `{ action:, destination:, protocol:,
+      # port: }` rule behaves identically to a factory-built one (without this, a
+      # singular `protocol`/`port` was silently dropped, widening the rule).
+      def normalize_rule(rule)
+        unless rule.is_a?(Hash)
+          raise ArgumentError, "rule must be a Hash (use Microsandbox::Rule.allow/deny): #{rule.inspect}"
+        end
+        sym = rule.transform_keys { |k| k.to_s.to_sym }
+        out = {}
+        out["action"] = sym[:action].to_s if sym[:action]
+        out["direction"] = sym[:direction].to_s if sym[:direction]
+        normalize_rule_destination(sym, out)
+        protos = (Array(sym[:protocols]) + Array(sym[:protocol])).compact.map(&:to_s)
+        out["protocols"] = protos unless protos.empty?
+        ports = (Array(sym[:ports]) + Array(sym[:port])).compact.map(&:to_s)
+        out["ports"] = ports unless ports.empty?
+        out
+      end
+
+      # Resolve a rule's destination (explicit kind+value, a {Destination} Hash,
+      # or a shorthand String) onto the wire `out` Hash.
+      def normalize_rule_destination(sym, out)
+        if sym.key?(:destination_kind)
+          out["destination_kind"] = sym[:destination_kind].to_s
+          out["destination"] = sym[:destination].to_s unless sym[:destination].nil?
+        elsif sym[:destination].is_a?(Hash)
+          dest = sym[:destination].transform_keys(&:to_s)
+          out["destination_kind"] = dest["destination_kind"].to_s if dest["destination_kind"]
+          out["destination"] = dest["destination"].to_s if dest.key?("destination")
+        elsif !sym[:destination].nil?
+          out["destination"] = sym[:destination].to_s
+        end
+      end
+    end
+
+    def initialize(wire)
+      @wire = wire
+    end
+
+    # @return [Hash] the normalized wire representation
+    def to_h
+      @wire
+    end
+
+    def inspect
+      "#<Microsandbox::NetworkPolicy #{@wire.inspect}>"
+    end
+  end
+end

data/lib/microsandbox/patch.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Microsandbox
+  # Factory for **rootfs patches** — modifications applied to a sandbox's root
+  # filesystem *before* the microVM boots. Pass them to {Sandbox.create} via the
+  # `patches:` keyword:
+  #
+  # @example
+  #   Microsandbox::Sandbox.create("box", image: "alpine",
+  #     patches: [
+  #       Microsandbox::Patch.text("/etc/app.conf", "key = value\n", mode: 0o644),
+  #       Microsandbox::Patch.mkdir("/opt/app"),
+  #       Microsandbox::Patch.copy_file("./cert.pem", "/etc/ssl/app.pem"),
+  #       Microsandbox::Patch.symlink("/etc/app.conf", "/etc/app.link"),
+  #       Microsandbox::Patch.remove("/etc/motd"),
+  #     ]) do |sb|
+  #     # ...
+  #   end
+  #
+  # Patches apply to OverlayFS (OCI) and bind rootfs; they are **not** compatible
+  # with disk-image roots. Each factory returns a plain Hash, so a patch list is
+  # just an Array of Hashes — you may also build them by hand. Mirrors the
+  # `Patch` factory in the official Python/Node/Go SDKs.
+  module Patch
+    module_function
+
+    # Write UTF-8 text to a file, creating it (or replacing it when +replace+).
+    # @param path [String] absolute guest path
+    # @param content [String] text to write
+    # @param mode [Integer, nil] file mode (e.g. 0o644)
+    # @param replace [Boolean] allow shadowing a path already in the rootfs
+    # @return [Hash]
+    def text(path, content, mode: nil, replace: false)
+      h = { "kind" => "text", "path" => path.to_s, "content" => content.to_s, "replace" => replace ? true : false }
+      h["mode"] = Integer(mode) unless mode.nil?
+      h
+    end
+
+    # Write raw bytes to a file (binary-safe; content may contain NUL).
+    # @param path [String] absolute guest path
+    # @param content [String] raw bytes to write
+    # @param mode [Integer, nil] file mode
+    # @param replace [Boolean]
+    # @return [Hash]
+    def file(path, content, mode: nil, replace: false)
+      h = { "kind" => "file", "path" => path.to_s, "content" => content.to_s, "replace" => replace ? true : false }
+      h["mode"] = Integer(mode) unless mode.nil?
+      h
+    end
+
+    # Append text to an existing file. For OCI roots, a file living only in a
+    # lower image layer is copied up first, then appended.
+    # @return [Hash]
+    def append(path, content)
+      { "kind" => "append", "path" => path.to_s, "content" => content.to_s }
+    end
+
+    # Copy a host file into the rootfs.
+    # @param src [String] host path
+    # @param dst [String] absolute guest destination
+    # @param mode [Integer, nil] file mode (preserves source mode when nil)
+    # @param replace [Boolean]
+    # @return [Hash]
+    def copy_file(src, dst, mode: nil, replace: false)
+      h = { "kind" => "copy_file", "src" => src.to_s, "dst" => dst.to_s, "replace" => replace ? true : false }
+      h["mode"] = Integer(mode) unless mode.nil?
+      h
+    end
+
+    # Copy a host directory (recursively) into the rootfs.
+    # @return [Hash]
+    def copy_dir(src, dst, replace: false)
+      { "kind" => "copy_dir", "src" => src.to_s, "dst" => dst.to_s, "replace" => replace ? true : false }
+    end
+
+    # Create a symlink at +link+ pointing to +target+.
+    # @return [Hash]
+    def symlink(target, link, replace: false)
+      { "kind" => "symlink", "target" => target.to_s, "link" => link.to_s, "replace" => replace ? true : false }
+    end
+
+    # Create a directory (idempotent — no error if it already exists).
+    # @param path [String] absolute guest path
+    # @param mode [Integer, nil] directory mode (e.g. 0o755)
+    # @return [Hash]
+    def mkdir(path, mode: nil)
+      h = { "kind" => "mkdir", "path" => path.to_s }
+      h["mode"] = Integer(mode) unless mode.nil?
+      h
+    end
+
+    # Remove a file or directory (idempotent — no error if absent).
+    # @return [Hash]
+    def remove(path)
+      { "kind" => "remove", "path" => path.to_s }
+    end
+  end
+end

data/lib/microsandbox/sandbox.rb

@@ -108,8 +108,15 @@ module Microsandbox
       # @param entrypoint [Array<String>, nil] image entrypoint override
       # @param ports [Hash, nil] host_port => guest_port TCP publications
       # @param ports_udp [Hash, nil] host_port => guest_port UDP publications
-      # @param network ["public_only", "none", "allow_all", "non_local", nil] network
-      #   policy preset (default public_only)
+      # @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}.
+      # @param patches [Array<Hash>, nil] rootfs patches applied before boot, each
+      #   built with the {Patch} factory (e.g. `Patch.text(...)`, `Patch.mkdir(...)`).
+      #   Not compatible with disk-image roots.
       # @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
@@ -119,6 +126,14 @@ module Microsandbox
       # @param rlimits [Hash, nil] resource limits: { resource => limit } or
       #   { resource => [soft, hard] } (e.g. { nofile: 65_535 })
       # @param pull_policy ["always","if-missing","never", nil] image pull behavior
+      # @param registry_auth [Hash, nil] credentials for a private/authenticated
+      #   registry: { username:, password: } (the password may be a token).
+      #   Without this the core's default resolution chain still applies (OS
+      #   keyring, global config, `~/.docker/config.json`).
+      # @param registry_insecure [Boolean] reach the registry over plain HTTP
+      #   instead of HTTPS (for local/self-hosted registries)
+      # @param registry_ca_certs [String, Array<String>, nil] extra PEM-encoded CA
+      #   root certificate(s) to trust (for a registry with a private CA)
       # @param secrets [Array<Hash>, nil] placeholder-protected secrets, each
       #   { env:, value:, host: } — the value is substituted by the TLS proxy only
       #   for the allowed host (auto-enables TLS interception)
@@ -131,10 +146,13 @@ module Microsandbox
                  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, secrets: nil,
+                 pull_policy: nil, registry_auth: nil, registry_insecure: false,
+                 registry_ca_certs: nil, secrets: nil,
                  detached: false, replace: false, replace_with_timeout: nil)
+        Microsandbox.ensure_runtime!
         opts = {}
         opts["image"] = image.to_s if image
         opts["from_snapshot"] = from_snapshot.to_s if from_snapshot
@@ -151,7 +169,8 @@ module Microsandbox
         opts["ports"] = intify_ports(ports) if ports
         opts["ports_udp"] = intify_ports(ports_udp) if ports_udp
         opts["volumes"] = normalize_volumes(volumes) if volumes
-        opts["network"] = network.to_s if network
+        opts["patches"] = normalize_patches(patches) if patches
+        apply_network_opts(opts, network) unless network.nil?
         opts["log_level"] = log_level.to_s if log_level
         opts["quiet_logs"] = true if quiet_logs
         opts["security"] = security.to_s if security
@@ -160,6 +179,7 @@ module Microsandbox
         opts["idle_timeout"] = Integer(idle_timeout) if idle_timeout
         opts["rlimits"] = normalize_rlimits(rlimits) if rlimits
         opts["pull_policy"] = pull_policy.to_s if pull_policy
+        apply_registry_opts(opts, registry_auth, registry_insecure, registry_ca_certs)
         opts["secrets"] = normalize_secrets(secrets) if secrets
         opts["detached"] = true if detached
         if replace_with_timeout
@@ -185,6 +205,7 @@ module Microsandbox
       # Restart a previously-defined sandbox by name.
       # @return [Sandbox]
       def start(name, detached: false)
+        Microsandbox.ensure_runtime!
         new(Native::Sandbox.start(name.to_s, { "detached" => detached }))
       end
 
@@ -225,6 +246,25 @@ module Microsandbox
         ports.each_with_object({}) { |(k, v), acc| acc[Integer(k)] = Integer(v) }
       end
 
+      # Flatten the registry options into the native layer's `registry_*` keys.
+      # `auth` is a Hash { username:, password: } (string or symbol keys); both
+      # are required when given. `ca_certs` accepts one PEM string or an Array.
+      def apply_registry_opts(opts, auth, insecure, ca_certs)
+        if auth
+          username = auth[:username] || auth["username"]
+          password = auth[:password] || auth["password"]
+          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})"
+          end
+          opts["registry_username"] = username.to_s
+          opts["registry_password"] = password.to_s
+        end
+        opts["registry_insecure"] = true if insecure
+        opts["registry_ca_certs"] = Array(ca_certs).map(&:to_s) if ca_certs
+      end
+
       # Normalize secrets into [env, value, host] triples for the native layer.
       # Each entry is a Hash { env:, value:, host: } (string or symbol keys).
       def normalize_secrets(secrets)
@@ -271,6 +311,33 @@ module Microsandbox
           end
         end
       end
+
+      # Normalize a list of patches (each a Hash from the {Patch} factory, or a
+      # plain Hash) into string-keyed Hashes for the native layer. Values are
+      # passed through unchanged (mode stays Integer, content stays String).
+      def normalize_patches(patches)
+        Array(patches).map do |p|
+          unless p.is_a?(Hash)
+            raise ArgumentError, "patch must be a Hash (use Microsandbox::Patch.*): #{p.inspect}"
+          end
+          p.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+        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.
+      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"]
+        else
+          opts["network_policy"] = norm
+        end
+      end
     end
 
     def initialize(native)
@@ -320,12 +387,60 @@ module Microsandbox
                                           exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
     end
 
+    # Attach an interactive terminal to a command in the sandbox.
+    #
+    # Puts the **host** terminal into raw mode and forwards keystrokes (and
+    # SIGWINCH resizes) to the guest until the command exits or the detach
+    # sequence is typed. Requires a real TTY on stdin/stdout, so it is for CLI
+    # use, not library/automation code (use {#exec}/{#exec_stream} there). Blocks
+    # until the session ends. Mirrors the official SDKs' `attach`.
+    #
+    # @param command [String] the program to run
+    # @param args [Array<String>] its arguments
+    # @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 (e.g. "ctrl-p,ctrl-q";
+    #   default "ctrl-]")
+    # @param rlimits [Hash, nil] resource limits (see {#exec})
+    # @return [Integer] the command's exit code (or the code at detach)
+    def attach(command, args = [], 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(command.to_s, Array(args).map(&:to_s), opts)
+    end
+
+    # Attach an interactive terminal running the sandbox's default shell.
+    # See {#attach} for the host-TTY requirements.
+    # @return [Integer] the shell's exit code (or the code at detach)
+    def attach_shell
+      @native.attach_shell
+    end
+
     # Guest filesystem operations.
     # @return [FS]
     def fs
       @fs ||= FS.new(@native)
     end
 
+    # SSH access to the sandbox — open a native in-process SSH client or prepare
+    # a reusable server endpoint.
+    # @return [SshOps]
+    # @example
+    #   sb.ssh.open_client { |c| puts c.exec("hostname").stdout }
+    def ssh
+      SshOps.new(@native)
+    end
+
     # Latest resource-usage snapshot.
     # @return [Metrics]
     def metrics