microsandbox-rb 0.17.0 → 0.17.1

data/docs/observability.md

@@ -0,0 +1,99 @@
+# Metrics, logs, and live modification
+
+## Metrics & logs
+
+```ruby
+Microsandbox::Sandbox.create("obs", image: "public.ecr.aws/docker/library/alpine:latest") do |sb|
+  # On v0.6.x runtimes the metrics slot goes live a beat after create returns,
+  # so `metrics` can briefly raise "no live metrics slot" right after boot —
+  # retry for a few hundred ms rather than treating the first failure as fatal.
+  m = sb.metrics                       # => Microsandbox::Metrics
+  m.cpu_percent
+  m.memory_bytes
+  m.uptime_secs
+
+  sb.logs(tail: 100, sources: ["stdout", "stderr"]).each do |entry|
+    puts "[#{entry.source}] #{entry.text}"
+  end
+end
+```
+
+Streaming counterparts: `sb.metrics_stream` (`MetricsStream` over `Metrics`)
+and `sb.log_stream` (`LogStream` over `LogEntry`) — both single-pass, see
+[execution.md](execution.md#streams-are-single-pass).
+`Microsandbox.all_sandbox_metrics` reports every running sandbox at once.
+
+`MetricsDisabledError` means metrics are turned off for the sandbox. The
+metrics slot goes live a moment *after* `create` returns; a call inside that
+window raises the base `Microsandbox::Error` with a message containing
+`no live metrics slot` (not `MetricsUnavailableError`, which the pinned runtime
+never raises). Retry on that message:
+
+```ruby
+metrics = begin
+  sb.metrics
+rescue Microsandbox::Error => e
+  raise unless e.message.include?("no live metrics slot")
+  sleep 0.1
+  retry
+end
+```
+
+`sb.log_stream(follow: true)` keeps waiting for new entries and **does not end
+when the sandbox stops** — the runtime follows the log file, not the sandbox —
+and the wait cannot be interrupted. A thread blocked in it also keeps the
+process from exiting normally. Read what exists with `sb.logs` or
+`sb.log_stream` (no `follow:`), or follow from a separate process you can kill.
+
+## Live modification and health
+
+Resize, reconfigure, or rotate secrets on a sandbox **without recreating it**,
+and probe the guest agent's liveness. To leave headroom for a live CPU/memory
+resize, reserve a ceiling at create time with `max_cpus:`/`max_memory:`:
+
+```ruby
+Microsandbox::Sandbox.create("live", image: "public.ecr.aws/docker/library/alpine:latest",
+  cpus: 1, max_cpus: 4, memory: 512, max_memory: 2048) do |sb|
+  # Health check — does NOT refresh the idle timer:
+  ping = sb.ping                       # => Microsandbox::PingResult
+  ping.latency_ms                      # round-trip latency
+
+  # Explicitly refresh the idle-activity timer (resets any idle_timeout:):
+  sb.touch.activity_seq                # => Microsandbox::TouchResult
+
+  # Preview a change without applying it:
+  plan = sb.modify(cpus: 2, memory: 1024, dry_run: true)
+  plan.applied?                        # => false
+  plan.changes                         # => [{ kind: "config", field: "cpus", ... }, ...]
+
+  # Live resize — applies to the running VM under the default :no_restart policy:
+  sb.modify(cpus: 2, memory: 1024)
+
+  # Grow the root disk (managed upper or flat, MiB — runtime v0.6.9). Applied
+  # while stopped; growth-only:
+  sb.modify(root_disk_size: 8192, policy: :next_start)
+
+  # env/labels/workdir changes on a *running* sandbox require a restart, so the
+  # default :no_restart policy rejects the whole apply (it raises rather than
+  # partially applying). Persist them for the next start — or restart now —
+  # by saying so explicitly:
+  sb.modify(env: { "TIER" => "prod" }, remove_env: ["DEBUG"],
+    labels: { "role" => "worker" }, policy: :next_start)  # or policy: :restart
+
+  # Rotating/removing an *existing* secret (or updating its allowed hosts) is
+  # live; *adding* a new secret is restart-required, like env. Specs are keyed
+  # by name; env:/store:/value: are mutually exclusive:
+  sb.modify(
+    secrets: { "API_KEY" => { env: "HOST_API_KEY", allowed_hosts: ["api.example.com"] } },
+    remove_secrets: ["OLD_TOKEN"],
+  )
+end
+```
+
+The apply is **all-or-nothing**: under a given `policy:` every planned change
+must be applicable, or the whole `modify` raises — nothing is partially
+applied. Use `dry_run: true` to inspect each change's `disposition` (`"live"`,
+`"next start"`, `"requires restart"`) before committing.
+
+`SandboxHandle` (from `Sandbox.get`/`list`) carries the same `#ping`/`#touch`/
+`#modify`; on a stopped sandbox `#ping`/`#touch` raise `SandboxNotRunningError`.

data/docs/releasing.md

@@ -0,0 +1,66 @@
+# Releasing
+
+Releases are automated by `.github/workflows/release.yml` via RubyGems
+**Trusted Publishing** (OIDC) — there is no API key to store as a secret. The
+trusted publisher is already configured for this gem, so no per-release secret
+or credential setup is needed.
+
+## Each release
+
+1. Bump the gem's **own** version — `Microsandbox::VERSION` and the matching
+   `[package] version` in `ext/microsandbox/Cargo.toml` (they must stay equal) —
+   on its independent semver track (see the
+   [Versioning](../README.md#versioning) section of the README); **don't** pick
+   the number to mirror the upstream tag. If the release also adopts a new
+   upstream runtime, bump the `tag = "vX.Y.Z"` on **all three** upstream git
+   deps (`microsandbox`, `microsandbox-network`, `microsandbox-runtime`), update
+   `Microsandbox::RUNTIME_VERSION` to match, commit the release's
+   `checksums.sha256` as `binaries/checksums/<tag>.sha256`, and add a row to the
+   Versioning table. Also bump `Microsandbox::Binaries::VERSION` (and, on a
+   runtime adoption, `::RUNTIME_VERSION`) in
+   `binaries/lib/microsandbox/binaries.rb` — the companion gem ships in
+   lockstep and the specs assert both. Update `CHANGELOG.md`.
+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 — then creates the GitHub Release.
+
+## Precompiled per-platform gems
+
+Precompiled *extension* 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 **not** in it — that comes from the companion `microsandbox-rb-binaries`
+gem, or, when that isn't installed, 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`).
+
+## Runtime binaries gems
+
+`microsandbox-rb-binaries` (source in `binaries/`) is a *separate* artifact from
+the precompiled extension gems above: it carries no Ruby extension, only the
+upstream `msb` + `libkrunfw` for one platform, verified against the release's
+published `checksums.sha256` when vendored. CI's `binaries` job vendors and
+builds all three (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`) on
+every run and smoke-tests the host one; `release.yml`'s `binaries-gems` job
+does the same on a tag and a separate `publish-binaries` job pushes them after
+the SDK gem is live (a companion failure is its own red job and never blocks
+the SDK release). They use their own RubyGems trusted-publisher entry (same
+repo + workflow, gem name `microsandbox-rb-binaries`). To build them by hand:
+
+```bash
+rake -C binaries vendor[arm64-darwin]   # download + sha256-verify into binaries/vendor
+rake -C binaries build[arm64-darwin]    # package into binaries/pkg/*.gem
+rake -C binaries verify                 # host-only: run the vendored `msb --version`
+```
+
+`binaries/vendor` and `binaries/pkg` are gitignored — binaries are never
+committed; CI rebuilds them from the upstream release.

data/docs/runtime.md

@@ -0,0 +1,152 @@
+# Runtime binaries, resolution, and backends
+
+## The runtime binaries
+
+`microsandbox-rb` is **SDK-only** — it wraps the microVM runtime, it doesn't
+carry it. The host-side `msb` runtime and the `libkrunfw` firmware come from an
+optional companion gem, **`microsandbox-rb-binaries`**, published as one gem per
+platform (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`) and
+versioned in lockstep with this gem:
+
+```ruby
+# Gemfile — install both gems at the same version
+gem "microsandbox-rb", require: "microsandbox"
+gem "microsandbox-rb-binaries"
+```
+
+That's all the wiring there is: `require "microsandbox"` finds the companion
+gem, checks it is the same version and built for the same upstream runtime, and
+points the resolver at its vendored `msb` — so your bundle carries the runtime
+and nothing is downloaded at install time or on first call. **Recommended
+whenever you boot local microVMs.** Cloud-only users (`MSB_BACKEND=cloud`)
+should skip it: it is a separate, optional gem precisely so nobody has to fetch
+~50 MB of binaries they won't run. Neither gem depends on the other.
+
+> **Availability.** The binaries gems are published on every release tag
+> alongside `microsandbox-rb` since `0.14.0`. On an older SDK version, or a
+> platform without a bundle, use the fallback below (or build them yourself
+> from `binaries/` — see [binaries/README.md](https://github.com/ya-luotao/microsandbox-rb/blob/main/binaries/README.md)).
+
+### Fallback — first-use download
+
+Without the companion gem, 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). None of this
+applies when the companion gem supplies the runtime: its binaries are already
+the matching version, so `ensure_runtime!` skips the installer entirely and
+nothing is written to `~/.microsandbox`. `Microsandbox.setup` customizes the
+provisioning step itself.
+
+## Runtime path resolution
+
+The `msb` runtime path is resolved in this order: the `MSB_PATH` environment
+variable → the `microsandbox-rb-binaries` gem (or another SDK-set override) →
+the config file → `~/.microsandbox/bin/msb` → `msb` on `PATH`.
+`Microsandbox.runtime_path` reports the winner.
+
+```ruby
+Microsandbox.installed?            # => true/false
+Microsandbox.install               # download + install the runtime (idempotent)
+Microsandbox.runtime_path          # => "/Users/you/.microsandbox/bin/msb"
+Microsandbox.runtime_path = "/opt/microsandbox/bin/msb"  # override (set-once)
+Microsandbox.libkrunfw_path = "/opt/microsandbox/lib/libkrunfw.dylib"  # override (set-once)
+```
+
+When `microsandbox-rb-binaries` is installed, `require "microsandbox"` claims
+that SDK-set slot with the gem's vendored `msb` (the firmware is found alongside
+it), and `runtime_path` points into the gem. The two gems are versioned in
+lockstep and the companion gem must be the same version **and** built for the
+same upstream runtime — a mismatch of either is reported with a warning and
+skipped, and the SDK falls back to `~/.microsandbox` rather than driving a
+runtime it doesn't match. Because the slot is **set-once**,
+`Microsandbox.runtime_path=` is then a no-op: use the `MSB_PATH` environment
+variable, which outranks it, to point at a different runtime.
+
+## Backend routing
+
+Every operation runs through a backend. The default is the local libkrun
+backend; without any configuration nothing changes. A backend can be selected
+programmatically or via the environment:
+
+```ruby
+Microsandbox.default_backend_kind          # => :local (or :cloud)
+Microsandbox.default_backend_info          # => Microsandbox::BackendInfo
+Microsandbox.set_default_backend(:cloud, url: "https://api.example.com", api_key: ENV["MSB_API_KEY"])
+# or a named profile from ~/.microsandbox/config.json:
+Microsandbox.set_default_backend(:cloud, profile: "prod")
+
+# Scoped override (restored afterward, even on error):
+Microsandbox.with_backend(:local) { Microsandbox::Sandbox.create("box", image: "alpine") { |sb| ... } }
+```
+
+Resolution order when no backend is set programmatically: `MSB_BACKEND`
+(`local`/`cloud`) → `MSB_PROFILE` → the `active_profile` in
+`~/.microsandbox/config.json` (path overridable via `MSB_CONFIG_PATH`) →
+local. **Cloud intent must be explicit** (since runtime `v0.6.9`): a bare
+`MSB_API_KEY` is treated as credential material, not backend intent, and no
+longer selects the cloud on its own — pair it with `MSB_BACKEND=cloud` (which
+reads `MSB_API_URL`/`MSB_API_KEY`), or select a cloud profile. Invalid cloud
+configuration (e.g. `MSB_BACKEND=cloud` without a usable API key or cloud
+profile) fails closed with `Microsandbox::InvalidConfigError` instead of
+silently running locally. The cloud backend currently supports a subset of
+operations (create/start/stop/remove/get/list, one-shot exec, follow log
+streaming); unsupported operations raise `Microsandbox::UnsupportedError`
+(with `#operation` and `#hint`).
+
+## One runtime line per home
+
+The runtime home (`MSB_HOME`, default `~/.microsandbox`) belongs to one
+runtime line at a time. This gem embeds runtime `v0.6.18` and, on first use,
+installs that version of `msb` into the home — replacing a different version
+that is already there, including a newer `msb` installed by the official CLI.
+In the other direction, a `0.7.x` `msb` migrates the catalog to a newer schema
+the first time it opens it, after which every local call from this gem fails
+with `database schema is newer than this msb binary`. The migration is one-way.
+
+If the official CLI (or another SDK) on a different runtime line shares the
+machine, give this gem its own home:
+
+```sh
+export MSB_HOME="$HOME/.microsandbox-rb"
+```
+
+## Known issues at the pinned runtime
+
+These are fixed upstream in runtime releases this gem has not adopted yet. See
+[SECURITY.md](../SECURITY.md) for the security advisories.
+
+- **macOS hosts: guest `fallocate` can truncate a file on a bind mount or a
+  directory-backed named volume.** Preallocating a range that ends inside an
+  existing file shrinks the file to the end of that range, and the call
+  reports success. Fixed upstream in `v0.7.0`. Until then, keep data that
+  guest programs preallocate (databases, download tools) on the guest's OCI
+  root disk or a `disk:` volume, not on a host directory.
+- **`modify(secrets:)` adding the first secret** to a sandbox created without
+  any does not turn on TLS interception, so the value is not substituted.
+  Create the sandbox with at least one secret.
+- **`patches:`** resets the owner and mode of parent directories that already
+  exist in the image to `root:root 0755`. Write after boot with `sb.fs`, or
+  restore ownership yourself.
+
+## Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `MSB_PATH` | Path to the `msb` runtime binary; outranks every other source, including the binaries gem |
+| `MSB_LIBKRUNFW_PATH` | Path to the `libkrunfw` shared library; outranks `Microsandbox.libkrunfw_path=` |
+| `MSB_HOME` | Runtime home: the catalog, image cache, sandboxes, volumes, snapshots, and the first-use runtime install. Default `~/.microsandbox` |
+| `MSB_BACKEND` | `local` or `cloud`; cloud additionally reads `MSB_API_URL` / `MSB_API_KEY` |
+| `MSB_PROFILE` | Select a named profile from the config file |
+| `MSB_CONFIG_PATH` | Override the `~/.microsandbox/config.json` location |
+| `MICROSANDBOX_NO_AUTO_INSTALL` | Disable the first-use runtime download |
+| `MICROSANDBOX_INTEGRATION` | Set to `1` to run the integration specs (development only) |
+| `MICROSANDBOX_TEST_IMAGE` | Override the integration-spec image (development only) |

data/docs/surface.md

@@ -0,0 +1,70 @@
+# Supported surface
+
+The binding covers the official-SDK surface of the upstream Rust core. This
+page is the authoritative scope statement; `sig/microsandbox.rbs` is the typed
+counterpart, and [DESIGN.md](../DESIGN.md) explains how the layers fit.
+
+## Implemented
+
+- **Sandbox lifecycle** — the live `Sandbox` (`stop`/`stop_and_wait`/`kill`/
+  `drain`/`wait`/`status`/`detach`/`owns_lifecycle?`), the `SandboxHandle`
+  controls from `Sandbox.get` (`stop_with_timeout`/`request_stop`/
+  `request_kill`/`request_drain`/`wait_until_stopped`/`config`/`config_json`/
+  `snapshot`), the cursor-paginated `list`/`list_with` with label filters, and
+  the convergent lifecycle (`connect_or_create`, `#id`, `wait_for_status`,
+  `restart`, `destroy`, `SandboxHandle#connect_or_start`,
+  `SandboxReplacedError`).
+- **Backend routing** — `set_default_backend`/`with_backend`/
+  `default_backend_kind`/`default_backend_info`.
+- **Execution** — `exec`/`shell` (collected and streaming), the default
+  workload (`exec_default`/`exec_default_stream`/`attach_default`, `cmd:`),
+  interactive `attach`/`attach_shell`, per-call `rlimits`.
+- **Guest filesystem** — the full API including streaming `read_stream`/
+  `write_stream`.
+- **Observability** — per-sandbox `metrics`, `Microsandbox.all_sandbox_metrics`,
+  streaming `metrics_stream`/`log_stream`, `logs`, `ping`/`touch`.
+- **Live modification** — `modify` with `dry_run:`, `policy:`, CPU/memory
+  resize, root-disk growth, env/labels/workdir, secret rotation.
+- **OCI image cache** — `Image.get`/`list`/`inspect`/`remove`/`prune`, image
+  archives (`Image.load`/`Image.save`), streaming pull progress
+  (`Sandbox.create_with_progress` → `PullSession`).
+- **Named volumes** — `Volume.create`/`get`/`list`/`remove`/`get_default`, plus
+  host-side `Volume.fs`/`VolumeInfo#fs` read/write.
+- **Snapshots** — create/open/list/list_dir/reindex/verify/save/load, boot from
+  snapshot, opt-in `record_integrity:`.
+- **Rootfs patches** — `Microsandbox::Patch` (text/file/append/copy_file/
+  copy_dir/symlink/mkdir/remove) via `create(patches:)`.
+- **Root disk** — structured `root_disk:` (managed / tmpfs / disk / flat via
+  `Microsandbox::RootDisk`), `follow_root_symlinks:`.
+- **Network configuration** — composable profiles, custom per-rule
+  `Microsandbox::NetworkPolicy`/`Rule`/`Destination`, DNS, TLS interception,
+  IPv4/IPv6 pools, `max_connections`, `trust_host_cas`, `strict` hostname mode,
+  outbound SOCKS4/SOCKS5 `proxy:` (`OutboundProxy`/`SecretSource`),
+  `rate_limiter:`, `vsock:`.
+- **Secrets** — multi-host / wildcard allow-lists, injection toggles,
+  per-secret and sandbox-level violation policy.
+- **SSH** — `Sandbox#ssh` → `SshClient`/`SftpClient`/`SshServer`, with
+  `inactivity_timeout:`.
+- **Raw agent client** — `Microsandbox::AgentClient` → `AgentStream`/
+  `AgentFrame`.
+- **Runtime provisioning** — `install`/`installed?`/`ensure_runtime!`/
+  `runtime_path`/`libkrunfw_path`, customizable via `Microsandbox.setup`; the
+  companion `microsandbox-rb-binaries` gem.
+- **Registries** — `registry_auth`/`registry_insecure`/`registry_ca_certs` on
+  `create`.
+- **Errors** — the typed hierarchy in [errors.md](errors.md).
+
+Create options span resources (`cpus`/`memory`/`max_cpus`/`max_memory`),
+`env`/`workdir`/`labels`/`user`/`hostname`/`shell`, `init`/`ephemeral`,
+disk-image `fstype`, `ports`/`ports_udp`, network policy + config,
+`log_level`/`security`/`rlimits`/`pull_policy`/`secrets`/`patches`/`volumes`
+(bind/named/tmpfs/disk with mount policies, `uid`/`gid`, `quota_mib`),
+`idle_timeout`/`max_duration`, `from_snapshot`, `detached`, and
+`replace`/`replace_with_timeout`.
+
+## Not yet exposed
+
+A few secondary upstream knobs are not yet exposed: per-published-port host
+bind address (ports always bind loopback), network interface overrides, and
+inline named-volume create-mode (pre-create the volume with `Volume.create`,
+then mount it with `{ named: "…" }`).

data/ext/microsandbox/Cargo.toml

@@ -7,7 +7,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # 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.6.16).
-version = "0.17.0"
+version = "0.17.1"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"

data/ext/microsandbox/src/host_path.rs

@@ -0,0 +1,108 @@
+//! Pin caller-supplied host paths when a sandbox is created (GHSA-mcw9-9rf6-p4rm).
+//!
+//! The pinned core stores a relative host path exactly as written and resolves
+//! it against the working directory of whichever process later starts the
+//! sandbox, so restarting from another directory mounts a different host
+//! directory than the one the caller meant. Upstream fixed that in v0.7.6 by
+//! resolving host paths once, at the local-backend boundary, before the
+//! configuration is persisted. This module applies the same resolution in the
+//! binding so it also holds on the runtime this gem pins.
+//!
+//! Rules, matching upstream's `resolve_host_paths`:
+//!
+//! - Local backend only: on a cloud backend the paths belong to the remote
+//!   host and are forwarded untouched.
+//! - `std::path::absolute`, never `canonicalize`: anchoring must not follow
+//!   symlinks (that would defeat the default refusal to follow a symlinked
+//!   bind-mount root) and must not require the target to exist.
+//! - Only create-time input is resolved. A sandbox that was already persisted
+//!   with a relative path keeps it; nothing here rewrites saved state.
+//!
+//! A vsock `host_socket` is deliberately not routed through here: the core
+//! refuses a relative one outright ("vsock host path must be absolute") before
+//! anything is persisted, so there is no stored relative path to pin.
+
+use std::path::PathBuf;
+
+use magnus::Error;
+use microsandbox::sandbox::{IntoImage, RootfsSource};
+use microsandbox::{BackendKind, MicrosandboxError};
+
+use crate::error;
+
+/// How the `image:` text should be handed to the builder.
+pub enum Image {
+    /// An OCI reference, an already-absolute path, or text the core rejects —
+    /// passed through unchanged so the core classifies (or reports) it.
+    Text(String),
+    /// A relative local rootfs path, anchored to the current directory.
+    Path(PathBuf),
+}
+
+/// Resolves host paths for one create call.
+#[derive(Clone, Copy)]
+pub struct HostPaths {
+    local: bool,
+}
+
+impl HostPaths {
+    /// Capture which backend the create call is about to dispatch to.
+    pub fn for_default_backend() -> Self {
+        Self {
+            local: matches!(microsandbox::default_backend().kind(), BackendKind::Local),
+        }
+    }
+
+    /// Anchor a relative host path to the current directory. Absolute paths
+    /// and the empty string (left for the core to reject) pass through.
+    pub fn pin(self, raw: String, label: &str) -> Result<PathBuf, Error> {
+        let path = PathBuf::from(raw);
+        if !self.local || path.as_os_str().is_empty() || path.is_absolute() {
+            return Ok(path);
+        }
+        std::path::absolute(&path).map_err(|e| {
+            error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+                "cannot resolve {label} {}: {e}",
+                path.display()
+            )))
+        })
+    }
+
+    /// Classify `image:` text the way the core does and pin it when it names a
+    /// relative local path (a directory rootfs or a disk image).
+    pub fn pin_image(self, text: String) -> Result<Image, Error> {
+        if !self.local {
+            return Ok(Image::Text(text));
+        }
+        let relative_local = matches!(
+            text.as_str().into_rootfs_source(),
+            Ok(RootfsSource::Bind { ref path, .. } | RootfsSource::DiskImage { ref path, .. })
+                if path.is_relative()
+        );
+        if relative_local {
+            self.pin(text, "rootfs path").map(Image::Path)
+        } else {
+            Ok(Image::Text(text))
+        }
+    }
+
+    /// Pin a `from_snapshot:` value when it is a path rather than a snapshot
+    /// name or digest. Uses the core's own name-vs-path split: a value that
+    /// contains `/` or starts with `.` or `~` is a path. (The core does not
+    /// expand `~`; like any other relative path it is anchored as written.)
+    pub fn pin_snapshot(self, raw: String) -> Result<String, Error> {
+        let path_like = raw.contains('/') || raw.starts_with('.') || raw.starts_with('~');
+        if !self.local || !path_like {
+            return Ok(raw);
+        }
+        self.pin(raw, "snapshot path")?
+            .into_os_string()
+            .into_string()
+            .map_err(|path| {
+                error::to_ruby(MicrosandboxError::InvalidConfig(format!(
+                    "cannot resolve snapshot path {}: the current directory is not valid UTF-8",
+                    PathBuf::from(path).display()
+                )))
+            })
+    }
+}

data/ext/microsandbox/src/lib.rs

@@ -14,6 +14,7 @@ mod conv;
 mod error;
 mod exec;
 mod fs_stream;
+mod host_path;
 mod image;
 mod runtime;
 mod sandbox;