hermetic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e50e07dce0f7e63f6ea83d61587f840678ef14edd404baae27dcff3ce3d17ec0
+  data.tar.gz: 29864ba40a25577dfd78cddc63390f11cc1cee694670b77462f1b965ba0ec12f
+SHA512:
+  metadata.gz: 88608057e05e00f071b205e8862f082c41f0488caf06888cba205d296c2764e8e5230d0db04f5b5fcaeb03cc61b4fc1c74e8a4b512bfbfc8573685afb45edf74
+  data.tar.gz: 9468982803c9caba9bb3ca00c605ca99d68b5b150fa4434fb167602ad04809edece8bdf750e9003fa5a36ebc06811f34966b3a23bf54bbf434bca579b91bff70

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.1.0] — 2026-07-16
+
+- Core seam: `Hermetic::Request` normalization (shell vs argv, traversal-safe
+  `files:`, clean default-deny env, host-enforced timeout, idempotency key),
+  `Result` (Silas-duck-compatible superset), `Limits`, `NetworkPolicy`,
+  `Credentials` (`:env` mode; `:proxy` deferred to v1.1)
+- Transports: `Subprocess` (host-timeout reaper, exit 124) and `Http`
+  (request-spec hash -> response), both with injectable fakes for tests
+- Backends: `Base` (shared Result assembly + timeout mapping), `Null`
+  (disabled, fails loud), hardened `Docker` (pure argv incl. in-argv `files:`
+  bootstrap, `--interactive` stdin, timeout reap), `Gvisor` (`--runtime runsc`),
+  `Firecracker` (pure machine-config + jailer argv builders; boot smoke-gated
+  behind an injected runner), `Hosted::E2B` (`:vendor`, best-effort wire shape
+  pending `:hosted` smoke pinning; Daytona/Modal named but deferred)
+- `Remote` executor client (`:remote`, off-host) with deterministic
+  idempotency keys and explicit in-doubt `TransportError`s; `EXECUTOR.md`
+  documents the server side of the wire contract
+- Facade constructors: `.null` / `.docker` / `.gvisor` / `.firecracker` /
+  `.hosted` / `.wrap`; any local constructor + `executor:`/`token:` reroutes
+  to a `Remote` client for that isolation kind
+- Optional Silas shim (`require "hermetic/silas"`): refuses a sandbox exec
+  inside a ledger transaction
+- Smoke layer (`:smoke`, opt-in via `HERMETIC_SMOKE`): docker/gvisor/hosted

data/EXECUTOR.md

@@ -0,0 +1,123 @@
+# EXECUTOR — the off-host sandbox executor server
+
+The server side of `Hermetic::Remote` (spec §3, §7 risk 2). A small HTTP
+daemon on a **dedicated sandbox host** that runs guests through a local
+backend (gVisor / Firecracker / hardened Docker) and holds **none of the
+app's secrets** — no database creds, no `RAILS_MASTER_KEY`, no ledger. The
+app talks to it over authenticated HTTPS; a guest escape's blast radius is
+this host, which holds nothing.
+
+v1 scope: a reference contract, not a production daemon (that's deferred,
+spec §6). Anything that speaks this contract works with `Hermetic::Remote`.
+
+## Auth
+
+- Every request carries `Authorization: Bearer <token>`. Static tokens,
+  compared in constant time. Missing/wrong token → `401`. No other auth.
+- TLS required in any real deployment. The token is the only secret either
+  side holds.
+
+## Endpoints
+
+### `POST /run` — execute one sandboxed run, synchronously
+
+Request body (exactly what `Hermetic::Remote#run_spec` sends):
+
+```json
+{
+  "v": 1,
+  "backend": "gvisor",                  // "docker" | "gvisor" | "firecracker"
+  "backend_options": { "image": "ruby:3.3-slim" },
+  "argv": ["/bin/sh", "-c", "echo hi"], // full exec argv; shell already resolved client-side
+  "stdin": null,
+  "files": { "main.rb": "puts 6*7" },   // workdir-relative; client rejects traversal, server MUST re-reject
+  "env": { "GITHUB_TOKEN": "..." },     // the guest's ENTIRE environment (default-deny; credentials pre-resolved)
+  "network": { "egress": [] },          // empty = no network; entries are "host:port" allowlist
+  "timeout": 30,                        // wall-clock seconds, EXECUTOR-enforced — never trust the guest
+  "limits": { "memory": "512m", "cpus": "1", "pids": 256 }
+}
+```
+
+Headers: `Idempotency-Key: <32 hex chars>` (required — see Dedup),
+`Content-Type: application/json`.
+
+Response `200` (always `200` when the run *completed*, including guest
+failure and timeout — a non-zero exit is data, not an error):
+
+```json
+{ "stdout": "hi\n", "stderr": "", "exit_status": 0, "timed_out": false }
+```
+
+Semantics:
+
+- Timeout expiry → kill the guest, respond `exit_status: 124`,
+  `timed_out: true` (coreutils convention; the client re-maps to 124 anyway).
+- The env in the payload is the guest's whole environment. Never merge the
+  executor host's env in.
+- Unsupported `backend` for this host → `422` (run not started).
+
+### `GET /runs/:idempotency_key` — reconcile an in-doubt run
+
+- `200` + the stored `/run` response body: the run completed; here is its
+  result. This is how a client resolves `TransportError(in_doubt: true)`
+  without re-executing.
+- `404`: this key never started a run — retrying is safe.
+- `409`: the run is still executing.
+
+### `GET /healthz`
+
+`200` + `{ "ok": true, "backends": ["gvisor"] }`. Unauthenticated allowed.
+
+## Dedup by idempotency key (the in-doubt contract)
+
+A sandbox run is a non-replayable external effect. The wire can fail after
+the guest ran (response lost) — the client cannot distinguish "never ran"
+from "ran, reply lost", so it raises `Hermetic::TransportError` with
+`in_doubt: true`. The executor makes retries safe:
+
+1. On `POST /run`, atomically record the `Idempotency-Key` as *running*
+   **before** exec. Duplicate key while running → `409`.
+2. On completion, store the result under the key.
+3. A replayed `POST /run` with a completed key returns the **stored** result
+   (`200`, plus `Idempotent-Replay: true`) — the guest does not run again.
+4. Retain results for a documented TTL (`>= 24h` recommended). After the
+   TTL, a replay re-executes.
+
+Caveat: the key is derived deterministically from the request content
+(credential *values* excluded, so token rotation between retries still
+dedups). Two *intentionally identical* runs inside the TTL therefore
+collapse into one. Callers that need genuine re-execution must vary the
+request — e.g. `env: { "HERMETIC_RUN_NONCE" => SecureRandom.hex }`.
+
+## Status-code contract
+
+| Code | Meaning | Run started? | Client behavior |
+|---|---|---|---|
+| 200 | completed (or deduped replay) | yes | `Hermetic::Result` |
+| 400 | malformed payload | **no** | `TransportError(in_doubt: false)` |
+| 401/403 | auth failure | **no** | `TransportError(in_doubt: false)` |
+| 409 | duplicate key still running | yes (in flight) | in doubt; poll `GET /runs/:key` |
+| 422 | backend unsupported here | **no** | `TransportError(in_doubt: false)` |
+| 5xx | executor broke mid-flight | unknown | `TransportError(in_doubt: true)` |
+
+The load-bearing rule: **a 4xx MUST mean the run was never started.** Any
+failure after exec begins must be a `5xx` (or a stored result), or the
+in-doubt contract breaks. (Exception: `409` — started by an earlier request,
+not this one.)
+
+Wire failure (no HTTP status at all) is always in doubt; the client raises
+`TransportError(in_doubt: true)` with the idempotency key in the message.
+v1 default is **no automatic retry** — surface in-doubt to a human or replay
+the same key deliberately.
+
+## Security posture (deployment checklist)
+
+- The executor host holds no app secrets and cannot reach the app's
+  database. Its only inbound is the app over TLS; its only standing secret
+  is the bearer token.
+- Guest network is default-deny; an `egress` allowlist is enforced by the
+  backend (gVisor/Docker network config, Firecracker tap + nftables).
+- `files` paths are re-validated server-side (workdir-relative, no `..`,
+  no absolute) even though the client already rejects traversal.
+- Response bodies are the guest's stdout/stderr verbatim — treat as
+  untrusted data, never interpolate into shell or HTML.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel St Paul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# hermetic
+
+> **hermetic** — the missing Ruby sandbox. Pick your isolation strength (gVisor, a
+> Firecracker microVM, a hosted sandbox, or hardened Docker) behind one `run` call,
+> and run it off your app host so an escape can't reach your database or secrets.
+
+Ruby today has exactly one honest option for running untrusted or model-generated
+code: a locked-down `docker run`. `$SAFE` was removed in Ruby 3.0; there is no Ruby
+client for E2B/Daytona/Modal and no Ruby wrapper for Firecracker or gVisor.
+`hermetic` fills that whitespace as an ecosystem building block: one interface,
+swappable isolation backends, zero runtime dependencies (stdlib only).
+
+## Install
+
+```ruby
+gem "hermetic"
+```
+
+## Usage
+
+```ruby
+box = Hermetic.hosted(:e2b, api_key: ENV["E2B_API_KEY"])
+
+result = box.run("python -c 'print(2+2)'",
+                 files:   { "data.txt" => "..." },   # materialized in the workdir
+                 stdin:   nil,
+                 env:     { "MODE" => "batch" },      # guest env is default-deny otherwise
+                 network: :none,                      # default deny; opt-in egress allowlist
+                 timeout: 10,                         # host-enforced wall clock
+                 limits:  { memory: "512m", cpus: "1", pids: 256 })
+
+result.stdout       # => "4\n"
+result.success?     # => true
+result.timed_out?   # => false (a timeout maps to exit_status 124)
+result.trust        # => :vendor
+```
+
+A `String` command runs via `/bin/sh -c`; an `Array` argv execs directly — no shell,
+no injection surface.
+
+## Backend matrix
+
+| Backend | Constructor | Isolation | Trust | Off-host? |
+|---|---|---|---|---|
+| **Hosted** (E2B) | `Hermetic.hosted(:e2b, api_key:)` | vendor microVM, in the vendor's cloud | `:vendor` | **yes**, by construction |
+| **Remote** | `Hermetic.wrap(executor:, token:)` or any local constructor + `executor:` | whatever the executor runs (gVisor/Firecracker/Docker) | `:remote` | **yes** — dedicated sandbox host |
+| **Firecracker** | `Hermetic.firecracker(kernel:, rootfs:)` | own guest kernel via KVM | `:vm` | no (pair with `executor:`) |
+| **gVisor** | `Hermetic.gvisor(image:)` | user-space kernel (`runsc`), real syscall boundary | `:host` | no (pair with `executor:`) |
+| **Docker** (hardened) | `Hermetic.docker(image:)` | container namespaces + caps/seccomp | `:host` | no — dev default |
+| **Null** | `Hermetic.null` | none — disabled, fails loud on `run` | `:none` | no |
+
+## Isolation is not the same thing as a trust boundary
+
+Two independent axes, never conflated:
+
+1. **Isolation strength** — namespaces < gVisor < microVM. (Which backend.)
+2. **Trust domain** — does the guest run *next to* your `RAILS_MASTER_KEY`, database,
+   and job queue, or in a separate security context?
+
+A container escape on your app host lands next to everything you care about, however
+strong the container was. So every box (and every `Result`) carries the posture:
+
+```ruby
+box.trust      # => :vendor | :remote | :vm | :host | :none
+box.off_host?  # => true only for :vendor and :remote
+```
+
+And the one-line guard that keeps it honest:
+
+```ruby
+raise "untrusted code requires an off-host sandbox" unless box.off_host?
+```
+
+Getting off-host is either free (hosted vendors) or one keyword: any local
+constructor takes `executor:` + `token:` and becomes a client for a dedicated
+sandbox host that holds no app secrets (see `EXECUTOR.md` for the server contract):
+
+```ruby
+box = Hermetic.gvisor(image: "ruby:3.3-slim",
+                      executor: "https://sbx.internal:8443", token: ENV["SBX_TOKEN"])
+box.off_host?  # => true — same isolation tech, different blast radius
+```
+
+## Credentials: the model never sees raw tokens
+
+```ruby
+box = Hermetic.hosted(:e2b, api_key: ENV["E2B_API_KEY"],
+  credentials: { "GITHUB_TOKEN" => -> { CredentialVault.fetch(:github) } })
+```
+
+Credentials are callables resolved lazily per run and injected into the guest's
+environment at exec time — never printed into the model-visible command, never
+cached on the box, never part of the idempotency key.
+
+## Silas drop-in
+
+`Hermetic::Result` is a superset of `Silas::Sandbox::Result` (`stdout` / `stderr` /
+`exit_status` / `success?`), and every box implements the `run` / `enabled?` duck
+type Silas's `config.sandbox` already accepts — zero Silas changes:
+
+```ruby
+Silas.configure do |c|
+  c.sandbox = Hermetic.gvisor(image: "ruby:3.3-slim",
+                              executor: "https://sbx.internal:8443",
+                              token: ENV["SBX_TOKEN"])
+end
+```
+
+Running Silas? Also `require "hermetic/silas"` — an optional shim that refuses to
+execute a sandbox run inside a ledger transaction (a sandbox exec is a
+non-replayable external effect; `run_code` stays `at_most_once!`).
+
+## In-doubt runs (remote/hosted)
+
+If the wire fails after a request may have executed guest-side, `hermetic` raises
+`Hermetic::TransportError` with `in_doubt?: true` rather than silently retrying.
+Every run carries a deterministic `Idempotency-Key`, so a deliberate retry of the
+same logical run can be deduplicated executor-side. v1 never retries automatically.
+
+## Honest v1 scope
+
+Shipped: Null, hardened Docker, gVisor, Hosted::E2B, Firecracker (pure
+config/jailer builders + injectable single-shot cold boot), Remote executor client
+with `EXECUTOR.md`, full `run` contract (`files:`/`stdin:`/`env:`/`network:`/
+`timeout:`/`limits:`), `:env` credentials, `trust`/`off_host?`, the Silas shim.
+
+Deferred (v1.1+):
+
+- `:proxy` credential mode (guest gets no token at all; egress proxy attaches auth)
+- Firecracker orchestration: warm pools/snapshots, vsock I/O, tap+nftables egress,
+  rootfs builder — v1's default Firecracker runner refuses to boot; inject your own
+- Hosted Daytona/Modal (constructors name them and fail with the roadmap)
+- The executor server daemon itself (the client + wire contract ship now)
+- Persistent sandboxes, streaming stdout, artifact read-back
+
+Known caveat: `Hosted::E2B`'s endpoint/body shapes are a best-effort design-time
+approximation, to be pinned against the live API via the `:hosted` smoke layer
+before first real use.
+
+## Testing
+
+The default suite is hermetic (the name is a promise): pure argv/VM-config/HTTP-spec
+builders plus injected fake runners and transports — no Docker, no network, no KVM.
+
+```
+bundle exec rspec                              # unit layer only, runs anywhere
+HERMETIC_SMOKE=docker  bundle exec rspec       # + real `docker run` round-trips
+HERMETIC_SMOKE=gvisor  bundle exec rspec       # + proves runsc boots (needs runsc runtime)
+HERMETIC_SMOKE=hosted  bundle exec rspec       # + E2B round-trip (needs E2B_API_KEY)
+```
+
+Smoke specs are tagged `:smoke`, excluded unless `HERMETIC_SMOKE` is set, and skip
+themselves when their infrastructure is absent.
+
+## License
+
+MIT.

data/lib/hermetic/backends/base.rb

@@ -0,0 +1,52 @@
+module Hermetic
+  module Backends
+    # Shared plumbing for every backend: normalize the run kwargs into a
+    # Request, delegate to the subclass's #execute (-> [stdout, stderr,
+    # exit_status, timed_out]), assemble the Result. Timeout always maps to
+    # exit 124 here so no backend can disagree about the convention.
+    class Base
+      TIMEOUT_EXIT = 124 # coreutils convention, matches Silas
+
+      OFF_HOST_TRUST = %i[vendor remote].freeze
+
+      attr_reader :trust, :limits
+
+      def initialize(trust:, limits: nil, credentials: nil, credential_mode: :env, env_allowlist: [])
+        @trust = trust
+        @limits = Limits.build(limits)
+        @credentials = Credentials.build(credentials, mode: credential_mode)
+        @env_allowlist = Array(env_allowlist).map(&:to_s)
+      end
+
+      def enabled? = true
+
+      # Off-host = a guest escape cannot reach the app's secrets (spec §3).
+      # Co-location is a visible, refusable property — guard with:
+      #   raise "untrusted code requires an off-host sandbox" unless box.off_host?
+      def off_host? = OFF_HOST_TRUST.include?(trust)
+
+      def run(command, files: {}, stdin: nil, env: {}, network: :none, timeout: 30, limits: nil)
+        request = Request.build(command, files: files, stdin: stdin, env: env,
+                                network: network, timeout: timeout, limits: limits,
+                                default_limits: @limits, credentials: @credentials,
+                                env_allowlist: @env_allowlist)
+        started = clock_ms
+        stdout, stderr, exit_status, timed_out = execute(request)
+        exit_status = TIMEOUT_EXIT if timed_out
+        Result.new(stdout: stdout, stderr: stderr, exit_status: exit_status,
+                   timed_out: !!timed_out, duration_ms: clock_ms - started,
+                   backend: backend_name, trust: trust)
+      end
+
+      def backend_name = self.class.name.split("::").last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+
+      private
+
+      def execute(request)
+        raise NotImplementedError, "#{self.class}#execute"
+      end
+
+      def clock_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+  end
+end

data/lib/hermetic/backends/docker.rb

@@ -0,0 +1,104 @@
+require "securerandom"
+require "shellwords"
+
+module Hermetic
+  module Backends
+    # Hardened `docker run` — Silas's interim adapter ported onto the Request
+    # contract and extended with what it lacked (files:, stdin:, clean env,
+    # per-run limits). Container namespaces are weaker than a microVM and the
+    # daemon this adapter shells to lives on the app host, so this is
+    # trust :host — dev-only for untrusted code (spec §3).
+    #
+    # The argv is a pure function of the Request — files: included — so the
+    # whole wire form is unit-testable without Docker present; the runner is
+    # injectable and a real run is a single `docker run` leg.
+    class Docker < Base
+      attr_reader :image, :workdir
+
+      def initialize(image:, workdir: "/workspace", docker_bin: "docker", runner: nil, **base_opts)
+        raise ConfigError, "image: is required" if image.to_s.strip.empty?
+
+        super(trust: :host, **base_opts)
+        @image = image
+        @workdir = workdir
+        @docker_bin = docker_bin
+        @runner = runner || method(:shell_run)
+      end
+
+      # Pure: Request -> locked-down `docker run` argv. The command rides as
+      # argv elements, never interpolated into a shell string — no injection
+      # surface. Docker passes no host vars unless named in --env, so the
+      # guest env is exactly Request#clean_env by construction. The rootfs is
+      # read-only; the workdir is a tmpfs — the guest's only writable scratch,
+      # which is also where the files: bootstrap lands.
+      def container_argv(request, name:)
+        [ @docker_bin, "run", "--rm", "--name", name, *runtime_flags,
+          *stdin_flags(request),
+          "--network", request.network.docker_flag,
+          "--memory", request.limits.memory, "--cpus", request.limits.cpus,
+          "--pids-limit", request.limits.pids.to_s,
+          "--read-only", "--tmpfs", @workdir, "--workdir", @workdir,
+          "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
+          *env_flags(request),
+          @image, *guest_argv(request) ]
+      end
+
+      # Pure: the files: delivery. `docker cp` can't reach a read-only rootfs
+      # and a workdir tmpfs only exists once the container starts (the smoke
+      # layer proved both), so files are written by the guest itself at exec
+      # time: each one a base64 blob decoded into the workdir tmpfs, then
+      # `exec "$@"` hands off to the real command. User data enters only as
+      # base64 ([A-Za-z0-9+/=], inert in single quotes) and escaped paths;
+      # the command stays positional-args — still no injection surface.
+      # Needs /bin/sh and base64 in the image (any debian/alpine/busybox).
+      def bootstrap_script(request)
+        writes = request.files.map do |path, content|
+          dir = File.dirname(path)
+          write = "printf '%s' '#{[ content ].pack("m0")}' | base64 -d > #{Shellwords.escape(path)}"
+          dir == "." ? write : "mkdir -p #{Shellwords.escape(dir)} && #{write}"
+        end
+        (writes + [ 'exec "$@"' ]).join(" && ")
+      end
+
+      private
+
+      def runtime_flags = [] # Gvisor overrides with --runtime runsc
+
+      # stdin only attaches when there is something to pipe; otherwise the
+      # guest sees a closed stdin immediately.
+      def stdin_flags(request) = request.stdin ? [ "--interactive" ] : []
+
+      def guest_argv(request)
+        return request.exec_argv if request.files.empty?
+
+        [ "/bin/sh", "-c", bootstrap_script(request), "hermetic", *request.exec_argv ]
+      end
+
+      def env_flags(request)
+        request.clean_env.flat_map { |key, value| [ "--env", "#{key}=#{value}" ] }
+      end
+
+      def execute(request)
+        name = "hermetic-#{SecureRandom.hex(6)}"
+        @runner.call(container_argv(request, name: name),
+                     stdin: request.stdin, timeout: request.timeout, name: name)
+      end
+
+      # The real runner (exercised only by the :smoke layer — unit specs
+      # inject a fake). On timeout the container is reaped by name, because
+      # killing the docker CLI leaves the daemon-side container alive
+      # (Silas's reaper lesson).
+      def shell_run(argv, stdin:, timeout:, name:)
+        tuple = transport.call(argv, stdin: stdin, timeout: timeout)
+        reap(name) if tuple[3]
+        tuple
+      end
+
+      def reap(name)
+        system(@docker_bin, "rm", "-f", name, out: File::NULL, err: File::NULL)
+      end
+
+      def transport = @transport ||= Transport::Subprocess.new
+    end
+  end
+end

data/lib/hermetic/backends/firecracker.rb

@@ -0,0 +1,114 @@
+require "securerandom"
+
+module Hermetic
+  module Backends
+    # Strongest self-host option: each run cold-boots a Firecracker microVM —
+    # its own guest kernel behind KVM (~125 ms boot). v1 ships the pure half
+    # (machine_config hash + jailer argv, unit-tested with zero infra) and a
+    # single-shot cold-boot path behind an injectable runner; real
+    # orchestration (jail materialization, vsock I/O, tap+nftables egress,
+    # warm pools) is deferred per spec §7, so the default runner refuses —
+    # actually booting is smoke-gated on a KVM host. trust :vm but
+    # co-located: off_host? is false. Pair with Hermetic::Remote to put the
+    # KVM host outside the app's trust domain.
+    class Firecracker < Base
+      BOOT_ARGS = "console=ttyS0 reboot=k panic=1 pci=off"
+      CONFIG_FILE = "vm-config.json" # jail-relative; jailer chroots firecracker
+
+      attr_reader :kernel, :rootfs
+
+      def initialize(kernel:, rootfs:, boot_args: BOOT_ARGS,
+                     firecracker_bin: "firecracker", jailer_bin: "jailer",
+                     uid: 65_534, gid: 65_534, chroot_base: "/srv/jailer",
+                     runner: nil, **opts)
+        raise ConfigError, "kernel: (vmlinux path) is required for firecracker" if kernel.to_s.strip.empty?
+        raise ConfigError, "rootfs: (ext4 image path) is required for firecracker" if rootfs.to_s.strip.empty?
+
+        super(trust: :vm, **opts)
+        @kernel = kernel
+        @rootfs = rootfs
+        @boot_args = boot_args
+        @firecracker_bin = firecracker_bin
+        @jailer_bin = jailer_bin
+        @uid = uid
+        @gid = gid
+        @chroot_base = chroot_base
+        @runner = runner
+      end
+
+      # Pure: the firecracker --config-file hash for one run. Rootfs is
+      # attached read-only (writable scratch is guest-init's job — same
+      # posture as docker --read-only + tmpfs); default-deny network attaches
+      # no NIC at all. pids has no seat in the VM config — it's enforced by
+      # guest init, deferred with the rest of orchestration.
+      def machine_config(request)
+        {
+          "boot-source" => {
+            "kernel_image_path" => @kernel,
+            "boot_args" => @boot_args
+          },
+          "drives" => [ {
+            "drive_id" => "rootfs",
+            "path_on_host" => @rootfs,
+            "is_root_device" => true,
+            "is_read_only" => true
+          } ],
+          "machine-config" => {
+            "vcpu_count" => vcpu_count(request.limits.cpus),
+            "mem_size_mib" => mem_size_mib(request.limits.memory),
+            "smt" => false
+          },
+          "network-interfaces" => request.network.firecracker_ifaces
+        }
+      end
+
+      # Pure: jailer chroots + re-namespaces firecracker and drops to an
+      # unprivileged uid/gid before the VMM runs. Everything after "--" goes
+      # to firecracker itself; the config path is relative to the jail root.
+      def jailer_argv(id:)
+        [ @jailer_bin,
+          "--id", id,
+          "--exec-file", @firecracker_bin,
+          "--uid", @uid.to_s,
+          "--gid", @gid.to_s,
+          "--chroot-base-dir", @chroot_base,
+          "--",
+          "--no-api",
+          "--config-file", CONFIG_FILE ]
+      end
+
+      private
+
+      # Single-shot cold boot: a fresh VM id per run, never reused. The
+      # runner owns everything host-side — materializing the config and
+      # files: into the jail, booting, guest I/O, and the wall clock — and
+      # returns [stdout, stderr, exit_status, timed_out].
+      def execute(request)
+        raise ConfigError, "firecracker execution requires a KVM host (smoke-gated)" unless @runner
+
+        id = "hermetic-fc-#{SecureRandom.hex(6)}"
+        @runner.call(jailer_argv(id: id), config: machine_config(request), request: request, id: id)
+      end
+
+      def vcpu_count(cpus)
+        count = Float(cpus).ceil
+        raise ConfigError, "cpus must be positive, got #{cpus.inspect}" unless count.positive?
+
+        count
+      rescue ArgumentError, TypeError
+        raise ConfigError, "cpus must be numeric for firecracker vcpu_count, got #{cpus.inspect}"
+      end
+
+      def mem_size_mib(memory)
+        case memory.to_s
+        when /\A(\d+)m\z/i then Regexp.last_match(1).to_i
+        when /\A(\d+)g\z/i then Regexp.last_match(1).to_i * 1024
+        when /\A\d+\z/ then memory.to_i
+        else
+          raise ConfigError,
+                %(memory must be "<n>m"/"<n>g" to map to firecracker mem_size_mib, got #{memory.inspect})
+        end
+      end
+    end
+  end
+end

data/lib/hermetic/backends/gvisor.rb

@@ -0,0 +1,23 @@
+require "hermetic/backends/docker"
+
+module Hermetic
+  module Backends
+    # gVisor: Docker's hardened front-end, but the container runs under the
+    # runsc user-space kernel — a real syscall boundary instead of shared
+    # host-kernel namespaces. Still trust :host: the isolation is stronger,
+    # but the daemon this adapter shells to lives on the app host — isolation
+    # strength and trust domain are independent axes (spec §3).
+    class Gvisor < Docker
+      RUNSC = "runsc"
+
+      def initialize(image:, runtime: RUNSC, **opts)
+        super(image: image, **opts)
+        @runtime = runtime
+      end
+
+      private
+
+      def runtime_flags = [ "--runtime", @runtime ]
+    end
+  end
+end