microsandbox-rb 0.5.7 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d79b0ba5b32f44bda4e984d0a231c842a0ce938ffe6859776ead5270c1043561
-  data.tar.gz: 96a97a6c3008070fdb3c32189973736f72d522942d94761d2656e0ffa0dfc030
+  metadata.gz: 045a5bf021edaf5afcfcf487cf0d980c38018560cc842c44018863570236f4ed
+  data.tar.gz: 25791e8bab4051711794cb8c1e08bbabc2b4dbc79bf080b02908b620ee0bd06e
 SHA512:
-  metadata.gz: 75291b5c9e1de3fe6b8b444d327d1716be099846fb87121ed9d5d00bf514bae39168cb4f7d246dabe6e41e8383b975f10e2bb7d68e0080ee9fb4ff59d546fad5
-  data.tar.gz: eaeb263b8b666f55f6614d88f9a2643379820d7f3be293c2b87ab1810bf164be3a7c6e5f5cb36860abcbd6ab03120cd7f7a91bdaeb1652e5048f369b396758ef
+  metadata.gz: 1b89148498194edb82241979432ee2e47599f2b657805b05718bfd18a8e1104318833ef84eb5f5e47a66f3cec8dc369f742897bbfe60cdb07fb613b597ef6ac5
+  data.tar.gz: c25b033291b4fb5195349030dcf2296006fa8b3563c7e1f6804441ed5e554e496583b22ddbca32828dff1b36127082b4cb1e995ab654573afc46b09e012031fd

data/CHANGELOG.md

@@ -6,7 +6,60 @@ upstream microsandbox runtime.
 
 ## [Unreleased]
 
-Closes the `Sandbox`-class lifecycle gap with the official Python/Node/Go SDKs.
+## [0.5.9] - 2026-06-18
+
+Closes the remaining roadmap items, bringing the binding surface to parity with
+the official Python/Node/Go SDKs (still wrapping the same upstream core,
+`v0.5.7`).
+
+### Added
+
+- **Rootfs patches** — `Sandbox.create(patches: [...])` applies modifications to
+  the root filesystem before boot, built with the new `Microsandbox::Patch`
+  factory: `Patch.text`/`file`/`append`/`copy_file`/`copy_dir`/`symlink`/`mkdir`/
+  `remove`. Mirrors the `Patch` factory in the official SDKs. (OverlayFS/bind
+  roots only — not disk images.)
+- **Custom per-rule network policies** — `Sandbox.create(network:)` now accepts,
+  besides the existing preset names, a `Microsandbox::NetworkPolicy` or a Hash
+  describing an ordered allow/deny rule list with per-direction defaults and bulk
+  domain denials. New `Microsandbox::NetworkPolicy` (`public_only`/`none`/
+  `allow_all`/`non_local`/`custom`), `Microsandbox::Rule` (`allow`/`deny`), and
+  `Microsandbox::Destination` (`any`/`ip`/`cidr`/`domain`/`domain_suffix`/
+  `group`, plus shorthand-string classification) factories. Destination
+  classification and rule composition mirror the official binding exactly.
+- **Raw agent client** — `Microsandbox::AgentClient.connect_sandbox`/
+  `connect_path`/`socket_path` open the byte-level transport to a sandbox's
+  `agentd` relay socket: `request`, `stream` (→ `Microsandbox::AgentStream`,
+  `Enumerable` over `Microsandbox::AgentFrame`), `send_frame`, `ready_bytes`,
+  `close`, with the `FLAG_TERMINAL`/`FLAG_SESSION_START`/`FLAG_SHUTDOWN` frame
+  flags. Mirrors the official `AgentClient`.
+- **SSH** — `Sandbox#ssh` returns a `Microsandbox::SshOps` to `open_client`
+  (→ `Microsandbox::SshClient`: `exec` → `Microsandbox::SshOutput`, `attach`,
+  `sftp` → `Microsandbox::SftpClient` with `read`/`write`/`mkdir`/`remove_file`/
+  `remove_dir`/`rename`/`symlink`/`real_path`/`read_link`, `close`) or
+  `prepare_server` (→ `Microsandbox::SshServer`: `serve_connection`, `close`).
+- **Interactive attach** — `Sandbox#attach(command, args, …)` and
+  `Sandbox#attach_shell` couple the host terminal (raw mode, SIGWINCH) to a
+  command (or the default shell) in the sandbox and return its exit code. For
+  CLI use — requires a real TTY.
+- RBS signatures for all of the above.
+
+### Notes
+
+- Network policy: a `preset` and custom `rules:`/`default_egress:`/`default_ingress:`
+  are mutually exclusive (a preset already defines its rules and defaults); a
+  preset may still be layered with `deny_domains:`/`deny_domain_suffixes:`. A
+  hand-written rule Hash accepts the singular `protocol:`/`port:` keys (the
+  spelling the Go/Python `PolicyRule` use) as well as the plural forms. The
+  deny-list-only shorthand (`network: { deny_domains: [...] }`) keeps the rest of
+  the network reachable (permissive defaults), matching the official SDKs.
+
+## [0.5.8] - 2026-06-17
+
+Closes the `Sandbox`-class lifecycle gap with the official Python/Node/Go SDKs
+and adds private/authenticated registry support plus first-use runtime
+auto-provisioning (the keystone for precompiled gems). Wraps the same upstream
+core (`v0.5.7`); this is a gem-only revision atop it.
 
 ### Added
 
@@ -42,6 +95,25 @@ Closes the `Sandbox`-class lifecycle gap with the official Python/Node/Go SDKs.
 - CI now runs the real-microVM integration suite (`spec/integration`) on a
   KVM-enabled runner, so the Rust↔core round-trip is exercised in automation —
   not just compilation and unit tests.
+- Registry authentication for `Sandbox.create`: `registry_auth: { username:,
+  password: }` (the password may be a token) for private/authenticated
+  registries and to lift Docker Hub's anonymous rate limit, plus
+  `registry_insecure:` (plain HTTP) and `registry_ca_certs:` (a PEM String or
+  Array) for self-hosted registries. Mirrors the Python/Node `registry_auth`
+  surface; without it the core's default resolution (OS keyring, global config,
+  `~/.docker/config.json`) still applies.
+- `Microsandbox.ensure_runtime!` — provisions the `msb` runtime + `libkrunfw` on
+  first use, called automatically by `Sandbox.create`/`start`. This makes
+  **precompiled platform gems** usable without a manual `install` step (a
+  precompiled-gem user never ran the source build, so the runtime is fetched
+  lazily by the running host's arch). Opt out with `MICROSANDBOX_NO_AUTO_INSTALL`.
+
+### Changed
+
+- The `cross-gems` release job now installs `libcap-ng-dev:arm64` via Debian
+  multiarch for the `aarch64-linux` cross-build (the extension links `-lcap-ng`
+  for the target arch). Precompiled gems remain `workflow_dispatch`-only and are
+  promoted to the publish path manually after per-platform validation.
 
 ## [0.5.7] - 2026-06-17
 
@@ -91,4 +163,6 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.8...HEAD
+[0.5.8]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.7...v0.5.8
 [0.5.7]: https://github.com/superradcompany/microsandbox/releases/tag/v0.5.7

data/Cargo.lock

@@ -3232,7 +3232,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.5.7"
+version = "0.5.9"
 dependencies = [
  "chrono",
  "futures",

data/DESIGN.md

@@ -76,6 +76,15 @@ SDK-set path (`Microsandbox.runtime_path=`) → config file → workspace build
 expose the core `setup::install`/`is_installed` for explicit, idempotent
 provisioning (mirrors the Python `install()`/`is_installed()`).
 
+Build-time provisioning only helps the **source gem**, where `build.rs` runs on
+the user's own machine. A **precompiled gem** is built in CI, so its build-time
+download lands on the CI host, not the user's — the user's `~/.microsandbox` is
+empty. `Microsandbox.ensure_runtime!` closes that gap: `Sandbox.create`/`start`
+call it to fetch the runtime on first use (by the *running* host's arch, which is
+always correct), at most once per process. `MICROSANDBOX_NO_AUTO_INSTALL` opts
+out (air-gapped hosts that provision out of band). libkrunfw is `dlopen`'d by
+`msb` at runtime and is never linked into the extension.
+
 ## Core-crate dependency (self-contained)
 
 `ext/microsandbox/Cargo.toml` depends on the core crate via a **pinned git tag**
@@ -90,14 +99,22 @@ git. The override must never be committed — it would break container builds.
 
 * **Source gem**: compiles the extension via `extconf.rb` (rb-sys
   `create_rust_makefile`); requires a Rust toolchain (MSRV below).
-* **Precompiled platform gems**: built in CI on a `vX.Y.Z` tag
+* **Precompiled platform gems**: built best-effort by the `cross-gems` job
   (`.github/workflows/release.yml`) with `oxidize-rb/cross-gem-action`
   (`rake-compiler-dock`) per `Gem::Platform`, shipping multi-ABI
   `lib/microsandbox/<ruby_abi>/` native artifacts — the same model Node uses with
-  per-platform packages. End users then install with no Rust toolchain. Published
+  per-platform packages. End users then install with no Rust toolchain, and the
+  runtime is fetched on first use (see above). The guest `agentd` is baked into
+  the extension by *target* arch (`filesystem/build.rs` uses
+  `CARGO_CFG_TARGET_ARCH` + `include_bytes!`), so it cross-compiles correctly;
+  the real cross work is linking the *target* native libs — `libcap-ng` on Linux
+  (via Debian multiarch for `aarch64-linux`) and the Hypervisor + Security
+  frameworks on macOS (via osxcross; `arm64-darwin` is the platform still to
+  confirm — if osxcross can't link them, move it to a native `macos-14` runner).
+  The job is gated to `workflow_dispatch` and **not** auto-published on tags:
+  since CI can't boot a microVM to prove a built gem actually works, gems are
+  promoted to the publish path manually after per-platform validation. Published
   to RubyGems via Trusted Publishing (OIDC). See [Releasing](README.md#releasing).
-  Whether the heavy core cross-builds for `arm64-darwin` under osxcross is
-  confirmed on first run; if not, that platform moves to a native macOS runner.
 
 ## Build requirements
 
@@ -120,22 +137,32 @@ API (`fs.read`/`write`/`list`/`mkdir`/`remove`/`stat`/…), `metrics`,
 **OCI image-cache management** (`Image.get`/`list`/`inspect`/`remove`/`prune`),
 **named volumes** (`Volume.create`/`get`/`list`/`remove` + `volumes:` mounts),
 **snapshots** (`Snapshot.create`/`get`/`list`/`remove`/`verify`/`export`/`import`
-+ `from_snapshot:` boot), `version`/`install`/`installed?`, and
-the typed error hierarchy.
++ `from_snapshot:` boot), **rootfs patches** (`Patch.text`/`file`/`append`/
+`copy_file`/`copy_dir`/`symlink`/`mkdir`/`remove` via `create(patches:)`),
+**custom per-rule network policies** (`NetworkPolicy`/`Rule`/`Destination` —
+CIDR/IP/domain/suffix/group allow-deny rules with per-direction defaults and
+bulk domain denials, alongside the presets), interactive **`attach`/
+`attach_shell`** (host-TTY coupled — raw mode + SIGWINCH), **SSH**
+(`Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`), the **raw agent client**
+(`AgentClient` → `AgentStream`/`AgentFrame`),
+`version`/`install`/`installed?`/`ensure_runtime!`, **registry auth**
+(`registry_auth`/`registry_insecure`/`registry_ca_certs` on `create`, for
+private/authenticated registries), and the typed error hierarchy.
 
 Create options now cover `image`, `cpus`, `memory`, `oci_upper_size`, `env`,
 `workdir`, `shell`, `user`, `hostname`, `labels`, `scripts`, `entrypoint`,
-`ports`/`ports_udp`, `volumes`, `network` policy presets
-(`public_only`/`none`/`allow_all`/`non_local`), `log_level`, `quiet_logs`,
-`security`, `max_duration`, `idle_timeout`, `rlimits`, `pull_policy`, `secrets`,
-`from_snapshot`, `detached`, and `replace`/`replace_with_timeout`. `exec`/`shell`
-add per-call `rlimits`.
+`ports`/`ports_udp`, `volumes`, `patches`, `network` (policy presets
+`public_only`/`none`/`allow_all`/`non_local`, or a custom `NetworkPolicy`/Hash),
+`log_level`, `quiet_logs`, `security`, `max_duration`, `idle_timeout`, `rlimits`,
+`pull_policy`, `registry_auth`/`registry_insecure`/`registry_ca_certs`,
+`secrets`, `from_snapshot`, `detached`, and `replace`/`replace_with_timeout`.
+`exec`/`shell` add per-call `rlimits`.
 
 ## Verification
 
 The binding is verified at four levels:
 
-1. **Unit** (130 examples) — the Ruby layer's option normalization and value
+1. **Unit** (192 examples) — the Ruby layer's option normalization and value
    objects, with the native layer stubbed.
 2. **Real-microVM integration** (`spec/integration`, opt-in via
    `MICROSANDBOX_INTEGRATION=1`) — boots actual sandboxes and round-trips
@@ -151,9 +178,10 @@ The binding is verified at four levels:
    shipped Rust source via `extconf.rb` and the installed gem boots a real
    microVM, confirming the gem manifest and source-install path are complete.
 
-**Roadmap:** custom per-rule network policies (CIDR/domain/group allow-deny
-rules — the presets and secret-host allowances are covered), file patches,
-registry auth, interactive `attach`/`attach_shell` (host-TTY coupled — raw mode,
-SIGWINCH), SSH (`SshClient`/`SftpClient`/`SshServer`), and the raw agent client.
-The native layer is structured so these slot in module-by-module, exactly as in
-the Python binding.
+**Roadmap:** the v1 roadmap (custom per-rule network policies, file patches,
+interactive `attach`/`attach_shell`, SSH, and the raw agent client) is now
+implemented — see the list above. What remains is upstream-gated rather than a
+binding gap: surfacing newer core features as the pinned core-crate tag advances
+(e.g. additional network knobs like DNS/TLS-proxy tuning and per-mount stat
+virtualization), which slot in module-by-module exactly as the existing bindings
+do.

data/README.md

@@ -14,6 +14,10 @@ This is an **unofficial, community-maintained** Ruby implementation — not part
 - **Command execution** — run commands or shell scripts and collect output
 - **Guest filesystem access** — read, write, list, copy, stat files inside a running sandbox
 - **Metrics & logs** — CPU, memory, disk and network I/O; captured stdout/stderr/system logs
+- **Rootfs patches** — inject files, dirs, and symlinks into the image before boot (`Microsandbox::Patch`)
+- **Fine-grained networking** — policy presets *and* custom CIDR/domain/group allow-deny rules (`Microsandbox::NetworkPolicy`)
+- **SSH & SFTP** — native in-process SSH client/server and file transfer (`Sandbox#ssh`)
+- **Raw agent client** — byte-level access to the guest `agentd` protocol (`Microsandbox::AgentClient`)
 - **Idiomatic Ruby** — keyword arguments, block-scoped lifecycle, a typed error hierarchy
 - **Thread-friendly** — the GVL is released during sandbox calls, so other Ruby threads keep running
 
@@ -21,7 +25,9 @@ This is an **unofficial, community-maintained** Ruby implementation — not part
 
 - **Ruby** >= 3.1
 - **Linux** with KVM enabled, or **macOS** on Apple Silicon (M-series)
-- Building from source additionally needs a **Rust** toolchain (stable >= 1.91)
+- A **Rust** toolchain (stable >= 1.91) — needed only when installing the source
+  gem (it compiles the native extension on install). Precompiled per-platform
+  gems, where available, require no Rust toolchain; see [Releasing](#releasing)
 
 ## Installation
 
@@ -39,19 +45,29 @@ bundle install
 gem install microsandbox-rb
 ```
 
-The first build downloads the `msb` runtime and `libkrunfw` firmware into
-`~/.microsandbox`. You can (re)provision them explicitly at any time:
+Installing the **source gem** compiles the Rust extension, so the first install
+takes a few minutes and needs a Rust toolchain (`rustc >= 1.91`) on `PATH`. When
+a **precompiled platform gem** is available for your OS/architecture, RubyGems
+picks it automatically and no Rust toolchain is required.
+
+Either way the `msb` runtime and `libkrunfw` firmware are provisioned into
+`~/.microsandbox` automatically on first use (the first `Sandbox.create`/`start`
+downloads them if missing). To provision ahead of time — e.g. while baking a
+container image, or to avoid the first-call latency — call `install` explicitly:
 
 ```ruby
 Microsandbox.install unless Microsandbox.installed?
 ```
 
+Set `MICROSANDBOX_NO_AUTO_INSTALL` to disable the automatic first-use download
+(e.g. on air-gapped hosts that provision the runtime out of band).
+
 ## Quick start
 
 ```ruby
 require "microsandbox"
 
-Microsandbox::Sandbox.create("hello", image: "python") do |sb|
+Microsandbox::Sandbox.create("hello", image: "public.ecr.aws/docker/library/python:3-slim") do |sb|
   output = sb.exec("python", ["-c", "print('Hello, World!')"])
   puts output.stdout      # => "Hello, World!\n"
   puts output.success?    # => true
@@ -59,18 +75,25 @@ end
 # the sandbox is stopped automatically when the block returns
 ```
 
+> **Why `public.ecr.aws/docker/library/...`?** The examples pull from AWS's
+> public mirror of the Docker Library because anonymous **Docker Hub** pulls are
+> rate-limited and often fail with `registry error: Not authorized`. Plain short
+> names like `image: "python"` work too if you aren't rate-limited. For private
+> or authenticated registries (including authenticated Docker Hub), pass
+> `registry_auth:` — see [Private & authenticated registries](#private--authenticated-registries).
+
 ## Usage
 
 ### Lifecycle
 
 ```ruby
 # Block form — recommended; stops the sandbox automatically (even on error)
-Microsandbox::Sandbox.create("box", image: "alpine") do |sb|
+Microsandbox::Sandbox.create("box", image: "public.ecr.aws/docker/library/alpine:latest") do |sb|
   # ...
 end
 
 # Manual form — you are responsible for stopping it
-sb = Microsandbox::Sandbox.create("box", image: "alpine")
+sb = Microsandbox::Sandbox.create("box", image: "public.ecr.aws/docker/library/alpine:latest")
 begin
   # ...
 ensure
@@ -90,7 +113,7 @@ Microsandbox::Sandbox.remove("box")   # remove a stopped sandbox
 ```ruby
 Microsandbox::Sandbox.create(
   "configured",
-  image:    "python",
+  image:    "public.ecr.aws/docker/library/python:3-slim",
   cpus:     2,
   memory:   1024,                      # MiB
   env:      { "API_BASE" => "https://example.com" },
@@ -107,7 +130,7 @@ end
 ### Executing commands
 
 ```ruby
-Microsandbox::Sandbox.create("exec-demo", image: "alpine") do |sb|
+Microsandbox::Sandbox.create("exec-demo", image: "public.ecr.aws/docker/library/alpine:latest") do |sb|
   # Direct command (no shell)
   out = sb.exec("ls", ["-la", "/etc"], cwd: "/", timeout: 30)
   out.exit_code   # => 0
@@ -130,7 +153,7 @@ failures (e.g. command not found) and timeouts raise typed errors (see below).
 ### Guest filesystem
 
 ```ruby
-Microsandbox::Sandbox.create("fs-demo", image: "alpine") do |sb|
+Microsandbox::Sandbox.create("fs-demo", image: "public.ecr.aws/docker/library/alpine:latest") do |sb|
   sb.fs.write("/tmp/data.txt", "hello")
   sb.fs.read_text("/tmp/data.txt")     # => "hello"  (UTF-8)
   sb.fs.read("/tmp/data.txt")          # => raw bytes (ASCII-8BIT)
@@ -151,7 +174,7 @@ end
 ### Metrics & logs
 
 ```ruby
-Microsandbox::Sandbox.create("obs", image: "alpine") do |sb|
+Microsandbox::Sandbox.create("obs", image: "public.ecr.aws/docker/library/alpine:latest") do |sb|
   m = sb.metrics                       # => Microsandbox::Metrics
   m.cpu_percent
   m.memory_bytes
@@ -168,7 +191,7 @@ end
 For long-running commands, stream events as they arrive instead of waiting:
 
 ```ruby
-Microsandbox::Sandbox.create("stream", image: "python") do |sb|
+Microsandbox::Sandbox.create("stream", image: "public.ecr.aws/docker/library/python:3-slim") do |sb|
   handle = sb.exec_stream("python", ["-u", "-c", "import time\nfor i in range(3): print(i); time.sleep(1)"])
   handle.each do |event|       # ExecHandle is Enumerable
     print event.text if event.stdout?
@@ -186,13 +209,45 @@ Manage the local OCI image cache (images are pulled automatically on `create`):
 
 ```ruby
 Microsandbox::Image.list           # => [Microsandbox::ImageInfo, ...]
-Microsandbox::Image.get("alpine")  # => Microsandbox::ImageInfo
-Microsandbox::Image.inspect("alpine").layers  # => [{...}, ...]
-Microsandbox::Image.remove("alpine", force: true)
+Microsandbox::Image.get("public.ecr.aws/docker/library/alpine:latest")  # => Microsandbox::ImageInfo
+Microsandbox::Image.inspect("public.ecr.aws/docker/library/alpine:latest").layers  # => [{...}, ...]
+Microsandbox::Image.remove("public.ecr.aws/docker/library/alpine:latest", force: true)
 report = Microsandbox::Image.prune
 report.bytes_reclaimed
 ```
 
+### Private & authenticated registries
+
+Images are pulled automatically on `create`. For a private registry — or to lift
+Docker Hub's anonymous rate limit — pass `registry_auth:` with a username and a
+password or token:
+
+```ruby
+Microsandbox::Sandbox.create(
+  "private",
+  image: "registry.example.com/team/app:latest",
+  registry_auth: { username: "ci-bot", password: ENV.fetch("REGISTRY_TOKEN") }
+) do |sb|
+  # ...
+end
+```
+
+For self-hosted registries you can also reach the registry over plain HTTP and
+trust a private CA:
+
+```ruby
+Microsandbox::Sandbox.create(
+  "internal",
+  image: "registry.internal:5000/app:latest",
+  registry_insecure: true,                                  # plain HTTP instead of HTTPS
+  registry_ca_certs: File.read("/etc/pki/internal-ca.pem")  # String or Array of PEMs
+)
+```
+
+Without `registry_auth:`, the core's default credential resolution still applies
+(OS keyring, global config, and `~/.docker/config.json`), so an existing
+`docker login` is honored automatically.
+
 ### Named volumes
 
 Persistent storage that outlives individual sandboxes:
@@ -201,7 +256,7 @@ Persistent storage that outlives individual sandboxes:
 Microsandbox::Volume.create("cache", kind: "disk", size_mib: 512)
 Microsandbox::Volume.list           # => [Microsandbox::VolumeInfo, ...]
 
-Microsandbox::Sandbox.create("with-vol", image: "alpine",
+Microsandbox::Sandbox.create("with-vol", image: "public.ecr.aws/docker/library/alpine:latest",
                              volumes: { "/data" => { named: "cache" } }) do |sb|
   sb.fs.write("/data/state.txt", "persisted")
 end
@@ -219,8 +274,8 @@ All errors descend from `Microsandbox::Error` and carry a stable `#code`:
 
 ```ruby
 begin
-  Microsandbox::Sandbox.create("dup", image: "alpine")
-  Microsandbox::Sandbox.create("dup", image: "alpine")  # name clash
+  Microsandbox::Sandbox.create("dup", image: "public.ecr.aws/docker/library/alpine:latest")
+  Microsandbox::Sandbox.create("dup", image: "public.ecr.aws/docker/library/alpine:latest")  # name clash
 rescue Microsandbox::SandboxAlreadyExistsError => e
   warn "#{e.code}: #{e.message}"       # => "sandbox-already-exists: ..."
 rescue Microsandbox::Error => e
@@ -301,27 +356,42 @@ one bound to the gem.
 1. Bump `Microsandbox::VERSION` (and the `tag = "vX.Y.Z"` on the core-crate
    dependency in `ext/microsandbox/Cargo.toml`) to match the upstream runtime,
    update `CHANGELOG.md`.
-2. *(Recommended first time)* run the workflow's manual `dry_run` dispatch to
-   build all platform gems without publishing — confirms the `arm64-darwin`
-   cross-build succeeds.
-3. Push a `vX.Y.Z` tag. CI builds precompiled, multi-ABI platform gems
-   (`x86_64-linux`, `aarch64-linux`, `arm64-darwin`) with `rake-compiler-dock`,
-   plus the source gem, and pushes them to RubyGems. The publish job uses
-   `rubygems/configure-rubygems-credentials` (OIDC) with `id-token: write` — no
+2. Push a `vX.Y.Z` tag. CI builds the **source gem** and pushes it to RubyGems
+   via `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
    `RUBYGEMS_API_KEY` secret required.
 
+> **Precompiled per-platform gems** are built best-effort by the `cross-gems`
+> job, gated to manual `workflow_dispatch` so you can iterate
+> (`gh workflow run release.yml`) without failing tag releases. They are not
+> auto-published on tags yet: a gem that *compiles but can't boot a microVM*
+> would be served to users ahead of the source gem, and CI can't boot a VM to
+> prove otherwise — so promotion is manual after validating the artifact on each
+> platform. A precompiled gem ships the compiled extension (with the guest
+> `agentd` baked in by *target* arch); the host-side `msb` + `libkrunfw` runtime
+> is fetched into `~/.microsandbox` on first use by `Microsandbox.ensure_runtime!`
+> (libkrunfw is `dlopen`'d by `msb` at runtime, never linked into the gem). The
+> real cross-compile work is linking the *target* native libraries — `libcap-ng`
+> on Linux (handled via Debian multiarch in the workflow) and the Hypervisor +
+> Security frameworks on macOS (via osxcross; the one platform left to confirm).
+> Until promoted, users install the source gem (which compiles via `rb_sys`).
+
 See [DESIGN.md](DESIGN.md) for the architecture and the implemented-surface
-section for what's covered today vs. on the roadmap. Covered: full sandbox
+section. The binding now covers the full official-SDK surface: sandbox
 lifecycle (including the async `request_stop`/`request_kill`/`request_drain`/
 `wait_until_stopped`/`detach`/`owns_lifecycle?` controls and label-filtered
-`list_with`), `exec`/`shell` (collected and streaming), the full guest
-filesystem, metrics (per-sandbox, `Microsandbox.all_sandbox_metrics`, and
-streaming `metrics_stream`/`log_stream`), logs, OCI image-cache management,
-named volumes, and snapshots (create/list/verify/export/import +
-boot-from-snapshot). Create options span resources, network policy presets,
-`log_level`/`security`/`rlimits`/`pull_policy`/`secrets` and more; `exec`/`shell`
-take per-call `rlimits`. Still on the roadmap: custom per-rule network policies,
-file patches, registry auth, interactive `attach`, SSH, and the raw agent client.
+`list_with`), `exec`/`shell` (collected and streaming), interactive `attach`/
+`attach_shell`, the full guest filesystem, metrics (per-sandbox,
+`Microsandbox.all_sandbox_metrics`, and streaming `metrics_stream`/`log_stream`),
+logs, OCI image-cache management, named volumes, snapshots (create/list/verify/
+export/import + boot-from-snapshot), **rootfs patches** (`Microsandbox::Patch`),
+**custom per-rule network policies** (`Microsandbox::NetworkPolicy`/`Rule`/
+`Destination`, alongside the presets), **SSH** (`Sandbox#ssh` →
+`SshClient`/`SftpClient`/`SshServer`), and the **raw agent client**
+(`Microsandbox::AgentClient`). Create options span resources, network policy,
+`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches` and more;
+`exec`/`shell` take per-call `rlimits`, and `create` accepts
+`registry_auth`/`registry_insecure`/`registry_ca_certs` for private and
+authenticated registries.
 
 ## License
 

data/ext/microsandbox/Cargo.toml

@@ -4,7 +4,10 @@
 # `microsandbox/microsandbox_rb` and stays hidden behind `require "microsandbox"`.
 name = "microsandbox_rb"
 description = "Ruby SDK native extension for microsandbox — secure, fast microVM-based sandboxing."
-version = "0.5.7"
+# Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
+# returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
+# The core-crate dependency below stays pinned at its own tag (v0.5.7).
+version = "0.5.9"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"

data/ext/microsandbox/extconf.rb

@@ -3,6 +3,41 @@
 require "mkmf"
 require "rb_sys/mkmf"
 
+# Preflight: the embedded microsandbox core is edition 2024 and pulls smoltcp,
+# which sets a Minimum Supported Rust Version of 1.91. A `cargo` from an older
+# toolchain (commonly Homebrew's rustc, which shadows a newer rustup on PATH and
+# ignores this gem's rust-toolchain.toml) fails deep in the build with a cryptic
+# "rustc X is not supported by smoltcp" error. Detect it up front and explain
+# the fix instead.
+MSRV = Gem::Version.new("1.91")
+rustc_version = begin
+  out = `rustc --version 2>/dev/null`
+  out[/\d+\.\d+(\.\d+)?/] && Gem::Version.new(out[/\d+\.\d+(\.\d+)?/])
+rescue StandardError
+  nil
+end
+
+if rustc_version && rustc_version < MSRV
+  which_rustc = (`which rustc 2>/dev/null`.strip rescue "")
+  abort(<<~MSG)
+
+    [microsandbox-rb] Rust #{rustc_version} is too old — the embedded core requires rustc >= #{MSRV}.
+      Found: #{which_rustc.empty? ? "rustc" : which_rustc} (#{rustc_version})
+
+    This usually means an older rustc (e.g. Homebrew's) is ahead of a newer
+    rustup toolchain on your PATH. Fixes:
+
+      • Put rustup's toolchain first for the install:
+          PATH="$HOME/.cargo/bin:$PATH" gem install microsandbox-rb
+      • Or make a recent stable the default and ensure no other rustc shadows it:
+          rustup install stable && rustup default stable
+      • Or upgrade your system Rust to >= #{MSRV}.
+
+    (This gem ships a rust-toolchain.toml pinning `stable`; the rustup `cargo`
+    shim honors it, but a non-rustup `cargo` does not.)
+  MSG
+end
+
 # Builds the Rust cdylib and installs it as lib/microsandbox/microsandbox.{bundle,so}.
 # The Cargo profile is selected via the RB_SYS_CARGO_PROFILE env var (defaults to
 # release for installed gems, dev for `rake compile`).