microsandbox-rb 0.16.0 → 0.17.1

data/SECURITY.md

@@ -0,0 +1,65 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security problems **privately**, not in a public issue:
+
+- GitHub: <https://github.com/ya-luotao/microsandbox-rb/security/advisories/new>
+  ("Report a vulnerability" on the repository's Security tab).
+
+Include the gem version (`Microsandbox::VERSION`), the embedded runtime
+(`Microsandbox.runtime_version`), the host OS, and the smallest reproduction you
+have. You should get a first reply within a few days.
+
+If the problem is in the microsandbox runtime itself (the `msb` binary, the
+guest agent, the network engine) rather than in this Ruby binding, report it
+upstream at <https://github.com/superradcompany/microsandbox/security> — and
+feel free to tell us too, so the fix can be tracked for this gem.
+
+## Supported versions
+
+Only the latest released version receives fixes. The gem embeds a specific
+upstream runtime; the README's Versioning table maps every gem version to its
+runtime tag.
+
+## Upstream advisories and this gem
+
+Upstream advisories name the upstream packages (the Rust crate, the CLI, and
+the official SDKs). **They do not list `microsandbox-rb`**, so `bundler-audit`
+and Dependabot will not flag this gem for them. The `rubygems:microsandbox`
+entry in some of them refers to the upstream project's own Ruby gem, not to
+`microsandbox-rb`. This table is the mapping.
+
+| Advisory | Severity | Affected `microsandbox-rb` | Status |
+|---|---|---|---|
+| [GHSA-mcw9-9rf6-p4rm](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-mcw9-9rf6-p4rm) — relative bind-mount paths re-resolved against the working directory on restart | High | `<= 0.17.0` | Fixed in `0.17.1` for sandboxes created through this gem (paths are pinned at create time in the binding). Sandboxes created earlier with a relative path keep it: recreate them. The `msb` CLI this gem installs is still runtime `v0.6.18`, so a sandbox created with `msb` directly is not covered: use absolute paths there. |
+| [GHSA-cg9x-2vfm-3j58](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-cg9x-2vfm-3j58) — NAT64 addresses can bypass destination-group network policy | High | all versions (runtime `< v0.7.5`) | **Not fixed in this gem yet**; needs the runtime fix. Only exploitable where the host network routes a NAT64 prefix. Mitigate by denying the prefix explicitly (see below) or blocking it at the host. |
+| [GHSA-3mpp-52gc-935r](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-3mpp-52gc-935r) — hostname allowlist bypass via mismatched HTTP `Host` / `:authority` | High | `<= 0.16.0` | Runtime fix included from `0.17.0`. If you rely on a hostname allowlist for HTTPS without TLS interception, also pass `strict: true` (off by default in this gem). |
+| [GHSA-gj24-29j2-3x78](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-gj24-29j2-3x78) — egress allowlist bypass on malformed HTTP/1 request lines | Medium | `<= 0.12.0` | Runtime fix included from `0.13.0`. |
+| [GHSA-4vq3-cjpp-v7fg](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-4vq3-cjpp-v7fg) — guest-controlled symlinks in `msb copy` | High | `<= 0.10.0` (the bundled `msb` CLI) | Runtime fix included from `0.11.0`. |
+| [GHSA-m8f5-rh7h-vgg3](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-m8f5-rh7h-vgg3) — secret values in world-readable process arguments | Medium | `<= 0.7.0` | Runtime fix included from `0.8.0`. |
+
+### Mitigating GHSA-cg9x-2vfm-3j58 before the runtime fix
+
+On a host whose network provides NAT64 (typically IPv6-only networks), deny the
+well-known prefix explicitly. Rules you pass are evaluated before the rules a
+profile expands to, so this keeps the default public-internet profile and puts
+the deny ahead of it:
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  network: {
+    profiles: [:public],
+    rules: [Microsandbox::Rule.deny(destination: "64:ff9b::/96")]
+  })
+```
+
+If your network uses a different NAT64 prefix, deny that one as well, or block
+the prefix at the host or network boundary. Hosts without NAT64 routing are not
+expected to be exploitable through this vector.
+
+The deny rule is this gem's suggestion, relying on the policy engine matching
+rules in order; it has not been exercised on a NAT64 network. The upstream
+advisory's own workarounds are to disable sandbox networking for untrusted
+workloads (`network: :none`) or to block NAT64 prefixes at the host or network
+boundary.

data/docs/configuration.md

@@ -0,0 +1,154 @@
+# Sandbox configuration
+
+All create-time options are keyword arguments to `Sandbox.create`,
+`Sandbox.connect_or_create`, and `Sandbox.create_with_progress`.
+
+## Resources, environment, ports, network
+
+```ruby
+Microsandbox::Sandbox.create(
+  "configured",
+  image:    "public.ecr.aws/docker/library/python:3-slim",
+  cpus:     2,
+  memory:   1024,                      # MiB
+  env:      { "API_BASE" => "https://example.com" },
+  workdir:  "/app",
+  labels:   { "team" => "research" },
+  ports:    { 8080 => 80 },            # host => guest (TCP)
+  network:  [:public],                 # composable profiles; :none for airgapped
+  replace:  true                       # replace an existing sandbox of the same name
+) do |sb|
+  # ...
+end
+```
+
+To leave headroom for a live CPU/memory resize later, reserve a ceiling with
+`max_cpus:`/`max_memory:` (see [observability.md](observability.md#live-modification-and-health)).
+
+The full option list — `init`/`ephemeral`, disk-image `fstype`, `log_level`,
+`security`, `rlimits`, `pull_policy`, `secrets`, `patches`
+(`Microsandbox::Patch`), the structured `root_disk:` (`Microsandbox::RootDisk`),
+`from_snapshot:`, `cmd:`, `detached:`, `idle_timeout`/`max_duration`, and more —
+is documented in [surface.md](surface.md) and typed in
+[`sig/microsandbox.rbs`](../sig/microsandbox.rbs).
+
+## Network policy
+
+`network:` takes composable profiles (`:public`, `:private`, `:host`, `:none`)
+or a custom `Microsandbox::NetworkPolicy` with per-rule CIDR/IP/domain/suffix/
+group allow-deny rules, per-direction defaults, DNS and TLS-interception
+settings, IPv4/IPv6 pools, `max_connections`, and `trust_host_cas`.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  network: Microsandbox::NetworkPolicy.custom(default_egress: :deny,
+    rules: [{ action: :allow, direction: :egress, protocol: :tcp, port: 443,
+              destination: Microsandbox::Destination.domain("api.example.com") }]))
+```
+
+### Strict hostname policy
+
+`strict: true` (runtime `v0.6.18`) makes a hostname-rule allow fail closed
+unless the runtime can actually see the request authority (plain-HTTP `Host`,
+or SNI/`:authority` under TLS interception); a bypassed or non-intercepted
+HTTPS flow allowed only by a hostname rule is then denied before the upstream
+dial. Default `false`; create-only. Independently of `strict:`, any policy with
+domain rules checks plain-HTTP `Host` headers against it.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  network: Microsandbox::NetworkPolicy.custom(default_egress: :deny,
+    rules: [{ action: :allow, direction: :egress, protocol: :tcp, port: 443,
+              destination: Microsandbox::Destination.domain("api.example.com") }]),
+  strict: true)
+```
+
+## Outbound proxy
+
+Route the sandbox's egress through a SOCKS4 (TCP) or SOCKS5 (TCP + non-DNS UDP)
+proxy with `proxy:` (runtime `v0.6.17`). The proxy is dialed by the runtime's
+host-side network stack, so its address is resolved from the host (`127.0.0.1`
+is the host's loopback), and the egress policy (`network:`) still governs which
+destinations may be reached. A SOCKS5 password comes from a host environment
+variable via `SecretSource.env` — only the variable's *name* is handed to the
+runtime. Local backend only.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks5("127.0.0.1:1080"))
+
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks5("10.0.0.5:1080")
+    .credentials("sandbox", Microsandbox::SecretSource.env("PROXY_PASSWORD")))
+
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: Microsandbox::OutboundProxy.socks4("127.0.0.1:1080", user_id: "ci"))
+
+# The equivalent plain Hash works too:
+Microsandbox::Sandbox.create("worker", image: "python",
+  proxy: { protocol: :socks5, address: "10.0.0.5:1080",
+           credentials: { username: "sandbox", password: { env: "PROXY_PASSWORD" } } })
+```
+
+## Secrets
+
+`secrets:` gives the guest a placeholder and substitutes the real value only in
+requests to the hosts you allow, with multi-host / wildcard allow-lists,
+injection toggles, and a per-secret or sandbox-level violation policy. At
+create time it is an **Array of specs**: `env:` is the variable the guest sees
+(holding the placeholder), `value:` is the real secret, and `host:` / `hosts:` /
+`host_patterns:` is the allow-list.
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "python",
+  secrets: [{ env: "API_KEY", value: ENV.fetch("HOST_API_KEY"), host: "api.example.com" }])
+# inside the guest: $API_KEY is "$MSB_API_KEY"; the proxy swaps in the real
+# value for requests to api.example.com only
+```
+
+An inline `value:` is part of the sandbox's saved configuration: it is stored
+in cleartext in the local catalog under the runtime home (`~/.microsandbox` by
+default) until the sandbox is removed, and `SandboxHandle#config` returns it.
+Stopping a sandbox does not remove it. Use `ephemeral: true` for short-lived
+work, remove sandboxes you no longer need, and do not log `#config`.
+
+Rotating an existing secret on a running sandbox is a live `modify`, which
+takes a **different shape** — a Hash keyed by name, where `env:` names a *host*
+environment variable to read the new value from. See
+[observability.md](observability.md#live-modification-and-health).
+
+## Volumes and mounts
+
+Persistent storage that outlives individual sandboxes:
+
+```ruby
+Microsandbox::Volume.create("cache", kind: "disk", size_mib: 512)
+Microsandbox::Volume.list           # => [Microsandbox::VolumeInfo, ...]
+
+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
+
+Microsandbox::Volume.remove("cache")
+```
+
+`volumes:` accepts a host path String (bind mount) or `{ bind: "/host" }` /
+`{ named: "volume-name" }` per guest path (tmpfs and disk mounts, mount
+policies, and a per-bind-mount `quota_mib:` are supported too). A bind or
+named mount may pin the fallback guest owner for host files with `uid:`/`gid:`
+(both required together, runtime `v0.6.15`). Named volumes can also be read and
+written from the host without booting a sandbox via `Volume.fs` /
+`VolumeInfo#fs`.
+
+A relative host path (`volumes: { "/data" => "./data" }`, `image: "./rootfs"`,
+a `root_disk:` image, a `Patch.copy_file` source, a `tls:` certificate, a
+path-form `from_snapshot:`) is resolved **once, when the sandbox is created**,
+against the creating process's working directory, and stored as an absolute
+path. Starting the sandbox later from another directory mounts the same host
+directory. Resolution does not follow symlinks. Sandboxes created by gem
+versions before `0.17.1` kept the relative path and resolved it again on every
+start ([GHSA-mcw9-9rf6-p4rm](https://github.com/superradcompany/microsandbox/security/advisories/GHSA-mcw9-9rf6-p4rm));
+recreate those. On a cloud backend, host paths are sent as written.
+
+Boot from a snapshot with `Sandbox.create(name, from_snapshot: "snap-name-or-path")`.

data/docs/errors.md

@@ -0,0 +1,74 @@
+# Error handling
+
+All errors descend from `Microsandbox::Error` (itself a `StandardError`) and
+carry a stable, machine-readable `#code`. The native layer raises the matching
+subclass for each core error variant; unmapped variants surface as the base
+`Error`. The hierarchy is flat, mirroring the Python SDK.
+
+```ruby
+begin
+  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
+  warn "microsandbox failed: #{e.message}"
+end
+```
+
+`Microsandbox::SomeError.code` returns the code for a class without an instance.
+Ruby-side keyword validation (a malformed `secrets:` spec, mutually exclusive
+options) raises a plain `ArgumentError` before the native layer is reached.
+
+## Classes and codes
+
+| Class | `#code` | Raised when |
+|-------|---------|-------------|
+| `Error` | `microsandbox-error` | Base class; unmapped core errors |
+| `InvalidConfigError` | `invalid-config` | Bad create options, invalid backend/cloud configuration |
+| `SandboxNotFoundError` | `sandbox-not-found` | No sandbox with that name |
+| `SandboxNotRunningError` | `sandbox-not-running` | Operation needs a running guest (`ping`/`touch`/`exec` on a stopped sandbox) |
+| `SandboxAlreadyExistsError` | `sandbox-already-exists` | Name clash on `create` without `replace:` |
+| `SandboxStillRunningError` | `sandbox-still-running` | `remove` on a running sandbox |
+| `SandboxReplacedError` | `sandbox-replaced` | The identity a handle was bound to no longer owns the name (see [lifecycle.md](lifecycle.md#convergent-lifecycle)) |
+| `ExecTimeoutError` | `exec-timeout` | `exec(timeout:)` / `shell(timeout:)` deadline hit |
+| `ExecFailedError` | `exec-failed` | Spawn-time failure (e.g. command not found) — a non-zero exit is **not** an error |
+| `NoDefaultCommandError` | `no-default-command` | `exec_default` / `attach_default` on an image with no runnable `ENTRYPOINT`+`CMD` |
+| `FilesystemError` | `filesystem-error` | Guest filesystem I/O failure |
+| `PathNotFoundError` | `path-not-found` | Reserved for parity; the native layer currently reports missing guest paths as `FilesystemError` |
+| `VolumeNotFoundError` | `volume-not-found` | No named volume with that name |
+| `VolumeAlreadyExistsError` | `volume-already-exists` | `Volume.create` name clash |
+| `ImageNotFoundError` | `image-not-found` | Image absent from the cache / registry |
+| `ImageInUseError` | `image-in-use` | `Image.remove` on an image a sandbox still references |
+| `ImagePullFailedError` | `image-pull-failed` | Reserved for parity; not raised by the current native mapping |
+| `SnapshotNotFoundError` | `snapshot-not-found` | No snapshot with that name |
+| `SnapshotAlreadyExistsError` | `snapshot-already-exists` | Snapshot name clash |
+| `SnapshotSandboxRunningError` | `snapshot-sandbox-running` | Snapshot requested from a running source sandbox |
+| `SnapshotImageMissingError` | `snapshot-image-missing` | Restore needs an image that is not cached |
+| `SnapshotIntegrityError` | `snapshot-integrity` | Snapshot payload failed verification |
+| `SnapshotMigrationError` | `snapshot-migration` | Automatic snapshot-descriptor migration was blocked and needs repair |
+| `NetworkPolicyError` | `network-policy-error` | Invalid network policy or `NetworkBuilder` validation failure (an invalid `proxy:` is `InvalidConfigError`) |
+| `SecretViolationError` | `secret-violation` | Reserved for parity; not raised by the current native mapping |
+| `TlsError` | `tls-error` | Reserved for parity; not raised by the current native mapping |
+| `IoError` | `io-error` | Host-side I/O failure |
+| `MetricsDisabledError` | `metrics-disabled` | Metrics turned off for this sandbox |
+| `MetricsUnavailableError` | `metrics-unavailable` | Reserved for parity; not raised at the pinned runtime. The transient "no live metrics slot" window right after boot raises the base `Microsandbox::Error` — match on the message |
+| `UnsupportedOperationError` | `unsupported-operation` | The runtime version does not support the operation |
+| `CloudHttpError` | `cloud-http` | Cloud backend HTTP failure |
+| `UnsupportedError` | `unsupported` | The selected backend does not implement the operation; carries `#operation` (e.g. `"sandbox.kill"`) and `#hint` |
+
+The snapshot classes go beyond the Python SDK (which collapses them into its
+base error) and match the Go SDK's per-variant coverage, so callers can rescue
+a missing / duplicate / running-source / missing-image / corrupt snapshot
+specifically.
+
+The authoritative list is `lib/microsandbox/errors.rb`; the core-variant to
+class mapping lives in `ext/microsandbox/src/error.rs`, and every class is
+declared in [`sig/microsandbox.rbs`](../sig/microsandbox.rbs). Classes marked
+"reserved" exist so callers can rescue them today without a code change once
+the native layer maps a core variant to them.
+
+## Secrets are redacted
+
+The native layer redacts secret values from error messages (since `0.8.2`),
+and a rejected proxy credential is reported by kind only, never by value.

data/docs/execution.md

@@ -0,0 +1,101 @@
+# Executing commands
+
+## `exec` and `shell`
+
+```ruby
+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
+  out.success?    # => true
+  out.stdout      # => "..." (UTF-8)
+  out.stderr_bytes # => raw ASCII-8BIT bytes
+
+  # Shell script (pipes, redirects, &&)
+  sb.shell("cat /etc/os-release | grep VERSION").stdout
+
+  # Environment, stdin, working directory
+  sb.exec("cat", [], stdin: "piped data")
+  sb.exec("sh", ["-c", "echo $GREETING"], env: { "GREETING" => "hi" })
+end
+```
+
+A non-zero exit is **not** an error — inspect `exit_code`/`success?`. Spawn-time
+failures (e.g. command not found) and timeouts raise typed errors
+([errors.md](errors.md)). `exec`/`shell` also take per-call `rlimits`.
+
+## Default workload
+
+`create` is strictly boot-only (runtime `v0.6.9`): it never runs the image's
+`ENTRYPOINT`/`CMD`. Execute the image's own command explicitly:
+
+```ruby
+Microsandbox::Sandbox.create("worker", image: "example/worker:latest",
+  cmd: ["worker.py", "--once"]) do |sb|   # cmd: overrides the durable image CMD
+  out = sb.exec_default(timeout: 300)     # buffered; exec-style options
+  handle = sb.exec_default_stream         # or streaming (returns an ExecHandle)
+  sb.attach_default                       # or interactive (host TTY)
+end
+```
+
+An image whose entrypoint and CMD resolve to no executable command raises
+`Microsandbox::NoDefaultCommandError`.
+
+## Streaming output
+
+For long-running commands, stream events as they arrive instead of waiting:
+
+```ruby
+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?
+  end
+  # or: out = handle.collect  → ExecOutput  (drain to the end)
+  # interactive stdin — create the stream with stdin: :pipe to get a writable sink:
+  #   h = sb.exec_stream("cat", [], stdin: :pipe)
+  #   sink = h.stdin; sink.write("data\n"); sink.close  # close sends EOF
+  # control: handle.signal(15), handle.kill, handle.resize(rows, cols)
+end
+```
+
+`shell_stream` is the shell-script counterpart. For a host-TTY-coupled
+interactive session (raw mode + SIGWINCH), use `attach`/`attach_shell`.
+
+### Streams are single-pass
+
+`ExecHandle`, `LogStream`, `MetricsStream`, `FsReadStream`, `PullSession`, and
+`AgentStream` are `Enumerable`, but `each` drains a one-shot native channel —
+they are forward-only, not rewindable, and meant for a single consumer. Iterate
+(or `collect`/`read`) exactly once: a second `each`, or a combinator after a
+partial drain (`count` then `each`, `to_a` twice), silently yields nothing.
+Don't share one handle across threads.
+
+## Threads, the GVL, and timeouts
+
+The GVL is released during sandbox calls, so *other* Ruby threads keep
+running. The *calling* thread blocks uninterruptibly until the call returns:
+`Timeout::timeout`, `Thread#kill`, and Ctrl-C cannot interrupt a blocked native
+call. Bound long-running work with a real deadline where one exists:
+
+- `exec(timeout:)` / `shell(timeout:)` kill the guest command after N seconds.
+- `AgentClient.connect_sandbox` / `connect_path` take a `timeout:` that bounds
+  only the connect handshake.
+- The streaming paths and `AgentClient#request`/`#stream` have no timeout knob
+  and can block indefinitely if the guest wedges.
+
+See [DESIGN.md](../DESIGN.md#sync-not-async) for the sync-over-async bridge
+behind this.
+
+## SSH and SFTP
+
+`Sandbox#ssh` opens an in-process SSH client to the guest (`SshClient`, with an
+`SftpClient` for file transfer) or prepares an `SshServer`. `open_client` /
+`prepare_server` accept `inactivity_timeout:` in seconds (`0` disables, `nil`
+inherits the 600s global default).
+
+## Raw agent client
+
+`Microsandbox::AgentClient` gives byte-level access to the guest `agentd`
+protocol (`AgentStream`/`AgentFrame`) for protocol-level work the higher-level
+API doesn't cover.

data/docs/filesystem.md

@@ -0,0 +1,45 @@
+# Guest filesystem
+
+`Sandbox#fs` is a `Microsandbox::FS` bound to the running guest.
+
+```ruby
+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)
+  sb.fs.exists?("/tmp/data.txt")       # => true
+
+  sb.fs.mkdir("/tmp/sub")
+  sb.fs.copy("/tmp/data.txt", "/tmp/sub/copy.txt")
+  sb.fs.rename("/tmp/sub/copy.txt", "/tmp/sub/renamed.txt")
+  sb.fs.list("/tmp/sub")               # => [Microsandbox::FsEntry, ...]
+  sb.fs.stat("/tmp/data.txt")          # => Microsandbox::FsMetadata
+
+  # Host <-> guest copies
+  sb.fs.copy_from_host("./local.txt", "/tmp/local.txt")
+  sb.fs.copy_to_host("/tmp/out.txt", "./out.txt")
+end
+```
+
+## Streaming reads and writes
+
+Large files stream instead of buffering: `fs.read_stream(path)` returns a
+single-pass `FsReadStream` (see
+[execution.md](execution.md#streams-are-single-pass)), and
+`fs.write_stream(path)` returns an `FsWriteSink` to write into and close.
+
+## Errors
+
+Guest filesystem failures, including missing paths, raise
+`Microsandbox::FilesystemError` (`#code` `filesystem-error`); the message
+carries the guest-side detail. See [errors.md](errors.md).
+
+## Host-side volume access
+
+Named volumes can be read and written from the host without a running sandbox
+through `Microsandbox::Volume.fs(name)` / `VolumeInfo#fs` (a `VolumeFs`). See
+[configuration.md](configuration.md#volumes-and-mounts).
+
+Paths are relative to the volume root; a leading `/` is the volume root, not the
+host root. A path containing a `..` segment is refused with `FilesystemError` in
+every operation.

data/docs/images.md

@@ -0,0 +1,65 @@
+# Images, registries, and snapshots
+
+## The local image cache
+
+Images are pulled automatically on `create` (governed by `pull_policy:`). The
+cache itself is managed through `Microsandbox::Image`:
+
+```ruby
+Microsandbox::Image.list           # => [Microsandbox::ImageInfo, ...]
+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
+```
+
+`Image.save`/`Image.load` move images through OCI archives, and
+`Sandbox.create_with_progress` returns a `PullSession` that streams pull
+progress before yielding the booted sandbox.
+
+## Why the examples use `public.ecr.aws/docker/library/...`
+
+Anonymous **Docker Hub** pulls are rate-limited and often fail with
+`registry error: Not authorized`. The examples pull from AWS's public mirror of
+the Docker Library instead. Plain short names like `image: "python"` work too if
+you aren't rate-limited; for authenticated Docker Hub, pass `registry_auth:`.
+
+## Private & authenticated registries
+
+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.
+
+## Snapshots
+
+`Microsandbox::Snapshot` covers create / open / get / list / list_dir / reindex /
+remove / verify / save / load, and `Sandbox.create(name, from_snapshot: ...)` boots
+from one. Snapshot failures raise the typed `Snapshot*Error` classes listed in
+[errors.md](errors.md). Payload integrity is opt-in (`record_integrity:`), and
+`verify` can report `:not_recorded` for snapshots taken without it.

data/docs/lifecycle.md

@@ -0,0 +1,108 @@
+# Sandbox lifecycle
+
+`Sandbox.create` boots a microVM and returns a live `Microsandbox::Sandbox`.
+`Sandbox.get`/`Sandbox.list` return a controllable `Microsandbox::SandboxHandle`
+for sandboxes that already exist. The live object owns the coarse controls
+(`stop`/`kill`/`drain`/`wait`); the handle owns the fine-grained ones
+(`stop_with_timeout`, `request_*`, `wait_until_stopped`, `config`, `snapshot`).
+
+## Create, stop, inspect
+
+Stopping is not removing. The block form **stops** the sandbox when the block
+returns; the stopped sandbox keeps its name, its saved configuration and its
+disk state in the catalog until you remove it, and creating another sandbox
+with the same name raises `SandboxAlreadyExistsError`. Three ways to finish:
+
+- `ephemeral: true` at create — removed as soon as it stops; right for one-off
+  work and for code that runs repeatedly under a fixed name.
+- `sb.destroy` (or `Sandbox.remove(name)` once stopped) — remove explicitly.
+- Leave it stopped and bring it back later with `Sandbox.start(name)`.
+
+Block forms used in a loop without one of the first two accumulate stopped
+sandboxes (and their disk usage) indefinitely.
+
+```ruby
+# Block form — recommended; stops the sandbox automatically (even on error)
+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: "public.ecr.aws/docker/library/alpine:latest")
+begin
+  # ...
+ensure
+  sb.stop          # graceful (SIGTERM→SIGKILL escalation, 10s default)
+  # sb.stop_and_wait # graceful, then wait → ExitStatus(#exit_code, #success?)
+  # sb.kill          # force (SIGKILL); sb.drain for a graceful drain
+end
+
+# Inspect / manage existing sandboxes. `list` returns a cursor-paginated,
+# Enumerable SandboxPage of handles.
+Microsandbox::Sandbox.list            # => Microsandbox::SandboxPage (first page)
+Microsandbox::Sandbox.list.map(&:name)  # enumerate the page's handles
+# next page: Sandbox.list_with(cursor: page.next_cursor, limit: 50)
+h = Microsandbox::Sandbox.get("box")  # => Microsandbox::SandboxHandle
+h.status                              # :running, :stopped, :created, ...
+h.stop_with_timeout(5)                # custom escalation timeout
+h.request_stop                        # fire-and-return; pair with #wait_until_stopped
+h.request_kill
+h.request_drain
+h.wait_until_stopped                  # => Microsandbox::SandboxStopResult
+Microsandbox::Sandbox.start("box")    # restart a stopped sandbox
+Microsandbox::Sandbox.remove("box")   # remove a stopped sandbox
+```
+
+`Sandbox.create` is strictly boot-only: it never runs the image's
+`ENTRYPOINT`/`CMD`. See [execution.md](execution.md#default-workload) for
+`exec_default`.
+
+## Convergent lifecycle
+
+Idempotent operations that take a name to the state you want, whatever state
+it is in now (runtime `v0.6.16`):
+
+```ruby
+# Create it, or connect to (and start) the one that is already there. The
+# keyword options are `create`'s and apply only when a create actually happens.
+sb = Microsandbox::Sandbox.connect_or_create("box", image: "public.ecr.aws/docker/library/alpine:latest")
+
+sb.id                     # opaque identity of the *persisted* sandbox — unlike
+                          # the reusable name, it changes on remove+recreate
+sb.wait_for_status(:running)  # => SandboxHandle (no built-in timeout)
+sb = sb.restart               # stop + start; => a new live Sandbox
+sb.destroy                    # stop + remove, in one step
+
+h = Microsandbox::Sandbox.get("box")
+h.connect_or_start        # connect if running, start if not => Sandbox
+h.restart(force: true, timeout: 5)
+h.destroy
+```
+
+Everything that acts on an *existing* receiver — `wait_for_status`, `restart`,
+`destroy`, `connect_or_start` — compares the identity it was bound to against
+the name's current owner first, raising `Microsandbox::SandboxReplacedError`
+rather than touching a sandbox someone else recreated under the same name.
+(`connect_or_create` is the entry point, so it has no prior identity to check:
+it simply converges on whichever sandbox now owns the name.)
+
+`connect_or_create`'s block form stops the sandbox only when the call owns its
+lifecycle — i.e. when it created it attached. A sandbox it merely connected to,
+or started with `detached: true`, is left running. And the stop it does issue is
+scoped to that sandbox's `id`, so a name removed and recreated while the block
+ran cannot be taken down by the teardown either. `Sandbox#owns_lifecycle?`
+reports which case you are in; `Sandbox#detach` hands the VM off so it
+outlives the block.
+
+## The live `Sandbox` / `SandboxHandle` split
+
+Upstream `v0.5.8` split the lifecycle into the live `Sandbox` and a
+controllable `SandboxHandle`, and the gem mirrors it. The live
+`Sandbox#stop`/`#kill` do not take a `timeout:`; `#request_stop`/
+`#request_kill`/`#request_drain`/`#wait_until_stopped` and a custom stop timeout
+live on the `SandboxHandle` from `Sandbox.get`. `Sandbox.get`/`.list` return a
+`SandboxHandle` (formerly a read-only `SandboxInfo`, kept as a deprecated
+alias).
+
+`SandboxHandle` also carries `#ping`/`#touch`/`#modify` — see
+[observability.md](observability.md).