microsandbox-rb 0.5.7 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d79b0ba5b32f44bda4e984d0a231c842a0ce938ffe6859776ead5270c1043561
-  data.tar.gz: 96a97a6c3008070fdb3c32189973736f72d522942d94761d2656e0ffa0dfc030
+  metadata.gz: 56e1f366f8e18a95965bc917c65b739426499a147f1da4a2defb090dba4c375d
+  data.tar.gz: 689f3c5518ddc52e6fd851d290e2629d3a3a9a043ba09653a6ce1041039a9a37
 SHA512:
-  metadata.gz: 75291b5c9e1de3fe6b8b444d327d1716be099846fb87121ed9d5d00bf514bae39168cb4f7d246dabe6e41e8383b975f10e2bb7d68e0080ee9fb4ff59d546fad5
-  data.tar.gz: eaeb263b8b666f55f6614d88f9a2643379820d7f3be293c2b87ab1810bf164be3a7c6e5f5cb36860abcbd6ab03120cd7f7a91bdaeb1652e5048f369b396758ef
+  metadata.gz: 503d0a3460f47855742e5179ccafab4e7b65132e71af5d3c39ed77b14542ac231e6bdbb9ebe2021e06ff2da912f702c8ad44f5a0dd882343879954d529581729
+  data.tar.gz: '08880c49fc0803d36ba7d1ee3b457c130528155a0ede5d3360c34fc805bc94feb4f6b88f7ae16287b97bdfefc32bbb8c1fdb7a7c89cfee3d46606c6a071efd6d'

data/CHANGELOG.md

@@ -6,7 +6,12 @@ upstream microsandbox runtime.
 
 ## [Unreleased]
 
-Closes the `Sandbox`-class lifecycle gap with the official Python/Node/Go 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 +47,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 +115,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.8"
 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,14 +137,16 @@ 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), `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`,
+`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`.
 
@@ -135,7 +154,7 @@ add per-call `rlimits`.
 
 The binding is verified at four levels:
 
-1. **Unit** (130 examples) — the Ruby layer's option normalization and value
+1. **Unit** (140 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
@@ -153,7 +172,7 @@ The binding is verified at four levels:
 
 **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,
+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.

data/README.md

@@ -21,7 +21,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 +41,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 +71,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 +109,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 +126,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 +149,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 +170,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 +187,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 +205,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 +252,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 +270,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,15 +352,25 @@ 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
 lifecycle (including the async `request_stop`/`request_kill`/`request_drain`/
@@ -320,8 +381,10 @@ 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.
+take per-call `rlimits`, and `create` accepts `registry_auth`/`registry_insecure`/
+`registry_ca_certs` for private and authenticated registries. Still on the
+roadmap: custom per-rule network policies, file patches, interactive `attach`,
+SSH, and the raw agent client.
 
 ## 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.8"
 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`).

data/ext/microsandbox/src/sandbox.rs

@@ -19,6 +19,7 @@ use microsandbox::sandbox::{
     SandboxMetrics, SandboxStatus, SandboxStopResult, SecurityProfile,
 };
 use microsandbox::LogLevel;
+use microsandbox::RegistryAuth;
 use microsandbox_network::policy::NetworkPolicy;
 
 use crate::conv;
@@ -137,6 +138,14 @@ impl Sandbox {
         if let Some(mib) = conv::opt_u32(opts, "oci_upper_size")? {
             b = b.oci_upper_size(mib);
         }
+        // Registry connection settings, for private / non-default registries:
+        // Basic auth (username + password/token), plain-HTTP `insecure`, and
+        // extra PEM CA roots. The Ruby layer flattens `registry_auth: {...}`
+        // into these keys; mirrors the Python `registry_auth=` and Node
+        // `.registry(r => r.auth(...))` surfaces.
+        if let Some(rc) = parse_registry_config(opts)? {
+            b = b.registry(move |r| rc.apply(r));
+        }
         if let Some(secs) = conv::opt::<u64>(opts, "max_duration")? {
             b = b.max_duration(secs);
         }
@@ -502,6 +511,65 @@ fn parse_rlimits(opts: RHash) -> Result<Vec<(RlimitResource, u64, u64)>, Error>
     Ok(out)
 }
 
+//--------------------------------------------------------------------------------------------------
+// Registry option parsing
+//--------------------------------------------------------------------------------------------------
+
+/// Parsed registry connection settings (auth + transport). Built from the flat
+/// `registry_*` option keys the Ruby layer normalizes `registry_auth:` into.
+struct RegistryConfig {
+    auth: Option<RegistryAuth>,
+    insecure: bool,
+    ca_certs: Vec<String>,
+}
+
+impl RegistryConfig {
+    fn apply(
+        self,
+        mut r: microsandbox::sandbox::RegistryConfigBuilder,
+    ) -> microsandbox::sandbox::RegistryConfigBuilder {
+        if let Some(auth) = self.auth {
+            r = r.auth(auth);
+        }
+        if self.insecure {
+            r = r.insecure();
+        }
+        for pem in self.ca_certs {
+            r = r.ca_certs(pem.into_bytes());
+        }
+        r
+    }
+}
+
+/// Read the `registry_*` options, returning `None` when none are set (so the
+/// default credential-resolution chain in the core is left untouched).
+fn parse_registry_config(opts: RHash) -> Result<Option<RegistryConfig>, Error> {
+    let username = conv::opt_string(opts, "registry_username")?;
+    let password = conv::opt_string(opts, "registry_password")?;
+    let insecure = conv::opt_bool(opts, "registry_insecure")?;
+    let ca_certs = conv::opt_string_vec(opts, "registry_ca_certs")?;
+
+    let auth = match (username, password) {
+        (Some(username), Some(password)) => Some(RegistryAuth::Basic { username, password }),
+        (None, None) => None,
+        // A half-specified credential is a caller bug, not a silent anonymous pull.
+        _ => {
+            return Err(error::base_error(
+                "registry_auth requires both :username and :password",
+            ))
+        }
+    };
+
+    if auth.is_none() && !insecure && ca_certs.is_empty() {
+        return Ok(None);
+    }
+    Ok(Some(RegistryConfig {
+        auth,
+        insecure,
+        ca_certs,
+    }))
+}
+
 //--------------------------------------------------------------------------------------------------
 // Exec option parsing
 //--------------------------------------------------------------------------------------------------

data/lib/microsandbox/sandbox.rb

@@ -119,6 +119,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)
@@ -133,8 +141,10 @@ module Microsandbox
                  entrypoint: nil, ports: nil, ports_udp: nil, volumes: nil, network: 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
@@ -160,6 +170,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 +196,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 +237,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)

data/lib/microsandbox/version.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module Microsandbox
-  # Gem version. Kept in lock-step with the upstream microsandbox runtime and
-  # the official Python/Node/Go SDKs (workspace version in the microsandbox repo).
-  VERSION = "0.5.7"
+  # Gem version. Tracks the upstream microsandbox runtime (currently `v0.5.7`,
+  # the pinned core-crate tag); the patch segment advances for gem-only revisions
+  # that add bindings atop the same core. Must equal the native ext's Cargo crate
+  # version (`Native.version`), enforced by spec/unit/version_spec.rb.
+  VERSION = "0.5.8"
 end

data/lib/microsandbox.rb

@@ -42,8 +42,14 @@ module Microsandbox
     end
 
     # Download and install the `msb` runtime + `libkrunfw` into
-    # `~/.microsandbox` (idempotent). Usually unnecessary: the native
-    # extension provisions the runtime at build time.
+    # `~/.microsandbox` (idempotent).
+    #
+    # When the gem is built from source, the native extension provisions the
+    # runtime at build time, so this is usually a no-op. Precompiled platform
+    # gems (which skip the local Rust build) do NOT provision it that way, so the
+    # runtime is fetched on first use — see {ensure_runtime!}. Call this
+    # explicitly to provision ahead of time (e.g. while baking a container
+    # image) so the first {Sandbox.create} doesn't pay the download.
     # @return [nil]
     def install
       Native.install
@@ -55,6 +61,32 @@ module Microsandbox
       Native.installed?
     end
 
+    # Ensure the `msb` runtime + `libkrunfw` are present, provisioning them on
+    # first use if not. Called automatically by {Sandbox.create}/{Sandbox.start}
+    # so precompiled-gem users (who never ran the source build) get a working
+    # runtime without a manual {install} step.
+    #
+    # The download is attempted at most once per process. Opt out by setting
+    # `MICROSANDBOX_NO_AUTO_INSTALL` (e.g. air-gapped hosts that provision the
+    # runtime out of band); the subsequent operation then surfaces the missing
+    # runtime itself. Already-installed runtimes (e.g. source builds) skip
+    # straight through with only a cheap presence check.
+    # @return [nil]
+    def ensure_runtime!
+      return if @runtime_ready
+      if installed?
+        @runtime_ready = true
+        return
+      end
+      return if auto_install_disabled?
+
+      warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
+           "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip)..."
+      install
+      @runtime_ready = true
+      nil
+    end
+
     # @return [String] the resolved path to the `msb` runtime binary
     def runtime_path
       Native.resolved_msb_path
@@ -74,5 +106,14 @@ module Microsandbox
     def all_sandbox_metrics
       Native.all_sandbox_metrics.transform_values { |m| Metrics.new(m) }
     end
+
+    private
+
+    # Auto-provisioning is on by default; any non-empty, non-"0"/"false" value
+    # of MICROSANDBOX_NO_AUTO_INSTALL disables it.
+    def auto_install_disabled?
+      v = ENV["MICROSANDBOX_NO_AUTO_INSTALL"]
+      !v.nil? && !v.empty? && !%w[0 false no].include?(v.downcase)
+    end
   end
 end

data/sig/microsandbox.rbs

@@ -6,6 +6,7 @@ module Microsandbox
   def self.version: () -> String
   def self.install: () -> nil
   def self.installed?: () -> bool
+  def self.ensure_runtime!: () -> nil
   def self.runtime_path: () -> String
   def self.runtime_path=: (String path) -> void
   def self.all_sandbox_metrics: () -> Hash[String, Metrics]
@@ -143,6 +144,8 @@ module Microsandbox
                       ?log_level: (String | Symbol)?, ?quiet_logs: bool, ?security: (String | Symbol)?,
                       ?oci_upper_size: Integer?, ?max_duration: Integer?, ?idle_timeout: Integer?,
                       ?rlimits: Hash[untyped, untyped]?, ?pull_policy: (String | Symbol)?,
+                      ?registry_auth: Hash[untyped, untyped]?, ?registry_insecure: bool,
+                      ?registry_ca_certs: (String | Array[String])?,
                       ?secrets: Array[Hash[untyped, untyped]]?, ?detached: bool,
                       ?replace: bool, ?replace_with_timeout: Numeric?)
                       ?{ (Sandbox) -> untyped } -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.8
 platform: ruby
 authors:
 - ya-luotao