sysprog21 · Max042004 · May 23, 2026 · May 23, 2026 · May 23, 2026 · May 23, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,12 @@
 build/
 archive/
-externals/
+# externals/ holds downloaded fixtures (kernel, rootfs, packages) that are
+# fetched on demand; tracking them in git would balloon the repo. The
+# vendored cJSON and zstd trees are exceptions: they ship with the source
+# so the OCI parser and layer unpacker build out of the box.
+externals/*
+!externals/cjson/
+!externals/zstd/
 lib/modules/
 *.o
 *.bin
diff --git a/Makefile b/Makefile
diff --git a/docs/usage.md b/docs/usage.md
@@ -99,6 +99,179 @@ and memory access, and per-thread inspection. Implementation details, including
 the snapshot protocol used to keep Hypervisor.framework register access on the
 owning thread, are documented in [internals.md](internals.md).
 
+## Running OCI Images (`elfuse oci run`)
+
+Phase 3 adds a direct-execution path for pulled OCI images:
+
+```sh
+elfuse oci run [OPTIONS] IMAGE [ARG...]
+```
+
+The subcommand reads the image's runtime block (Entrypoint, Cmd, Env,
+WorkingDir, User) and folds in any CLI overrides, then unpacks the image
+into the local APFS sysroot volume, clones a per-run rootfs via APFS
+`clonefile(2)`, resolves argv[0] against PATH inside the rootfs, and
+hands off to the same VM bring-up the legacy positional-ELF `elfuse`
+entry uses.
+
+The image must already be pulled. `oci run` does not auto-pull on miss.
+The usual workflow is:
+
+```sh
+elfuse oci pull alpine:3
+elfuse oci run  alpine:3 /bin/sh -c 'echo hello from inside'
+```
+
+### Options
+
+| Option | Meaning |
+|--------|---------|
+| `--store DIR` | Override the local store root |
+| `--volume DIR` | Override the APFS sysroot volume mount point |
+| `--entrypoint PROG` | Replace the image Entrypoint with `PROG` |
+| `-e KEY=VAL`, `--env KEY=VAL` | Set or replace one env var (repeatable) |
+| `-e KEY`, `--env KEY` | Import `KEY` from the host environ (repeatable) |
+| `-w DIR`, `--workdir DIR` | Override image WorkingDir |
+| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (numeric only) |
-| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (numeric only) |
+| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (supports numeric UID[:GID] or symbolic name[:group]) |
-| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (numeric only) |
+| `-u UID[:GID]`, `--user UID[:GID]` | Override image User (supports numeric UID[:GID] or symbolic name[:group]) |
+| `--keep` | Keep the per-run cloned rootfs after exit |
+| `--name NAME` | Reserved: deterministic clone-dir suffix (ignored today) |
+
+### Argv override matrix
+
+| Image Entrypoint | Image Cmd | CLI ARGV | `--entrypoint` | Result argv |
+|--|--|--|--|--|
+| set | set | none | none | Entrypoint ++ Cmd |
+| set | set | provided | none | Entrypoint ++ CLI ARGV (Cmd dropped) |
+| set | none | provided | none | Entrypoint ++ CLI ARGV |
+| none | set | none | none | Cmd |
+| none | set | provided | none | CLI ARGV (Cmd dropped) |
+| set | set | optional | provided | [`--entrypoint`] ++ CLI ARGV |
+| none | none | provided | none | CLI ARGV |
+| none | none | none | none | `EINVAL` "image has no entrypoint or cmd; pass one on the CLI" |
+
+### Env merge policy
+
+The merged guest env is built in this order:
+
+1. Image `Env` (verbatim, in spec order)
+2. Each CLI `-e KEY=VAL` set-or-replaces by key
+3. Each CLI `-e KEY` (no `=`) imports the host's value when present, otherwise drops silently
+4. `TERM` auto-imported from the host iff the merged env has no `TERM`
+5. `PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` injected iff the merged env has no `PATH`
+6. `container=elfuse` injected unconditionally so systemd-style sandbox detection works
+
+CLI `-e DYLD_*=...` overrides are hard-rejected with `EINVAL`: `DYLD_*` is a
+macOS-only loader contract with no meaning inside an aarch64-linux guest.
+Image-provided `DYLD_*` entries pass through (the guest ignores them).
+
+### User and WorkingDir
+
+`User` accepts seven shapes: the empty string (no override), a numeric
+`UID`, `UID:GID`, a symbolic `name`, `name:group`, `uid:group`, or
+`name:gid`. Symbolic forms read `/etc/passwd` and `/etc/group` from
+the cloned rootfs. A token made entirely of ASCII digits is always
+parsed numerically, even when a same-named account ships in the image
+(this matches runc semantics, so an image that happens to carry a
+`1234` account does not capture `--user 1234`). When the symbolic
+form names an account the unpacked layers do not actually carry,
+lookup fails closed; `elfuse` never silently falls back to root.
+`--user UID` alone defaults GID to the same value.
+
+`WorkingDir` must be absolute and free of `..` segments. If neither the
+image nor the CLI sets it, the guest starts in `/`. The directory is
+materialized under the cloned rootfs (`mkdir -p`, mode 0755, best-
+effort chown to the resolved uid:gid when `--user` or image User
+selects credentials).
+
+### Scope guardrails
+
+- Auto-pull on `run` miss -> never; `elfuse oci pull` must run first
+- Network policy, `docker run -p`-style port mapping -> later phases
+- Live `docker exec`-style attach -> never
+
+### Runtime host-truth surface
+
+`elfuse oci run` runs the guest against a freshly cloned per-run
+rootfs and a small set of synthesized host-truth files. The rootfs
+is produced by APFS `clonefile(2)` against the unpacked image
+layers, so the first guest write to any path triggers copy-on-write
+in APFS without touching the original image. The clone is removed at
+guest exit unless `--keep` is set; nothing is ever pushed back to
+the on-disk image, and concurrent `oci run` invocations against the
+same image are isolated.
+
+Three `/etc` files are overwritten in the clone before the guest
+starts. Any pre-existing symlink (the common case is
+`/etc/resolv.conf -> /run/systemd/resolve/stub-resolv.conf`) is
+unlinked first so it does not dangle inside the guest:
+
+| File | Source |
+|--|--|
+| `/etc/resolv.conf` | `nameserver` lines harvested from `scutil --dns`; falls back to `8.8.8.8` and `1.1.1.1` on any scutil failure |
+| `/etc/hosts` | fixed 5-line block: `localhost`, the ip6-loopback aliases, ip6 link-local multicast, and `127.0.0.1 host.elfuse.internal` |
+| `/etc/hostname` | literal string `elfuse` |
+
+The following pseudo-filesystem paths are synthesized by the host-side
+openat interceptor and do not need to exist inside the rootfs:
+
+| Path | Behavior |
+|--|--|
+| `/dev/null`, `/dev/zero`, `/dev/random`, `/dev/urandom`, `/dev/tty` | redirected to the host device of the same name |
+| `/dev/full` | reads zero-fill, writes of any non-zero length return `ENOSPC` |
+| `/dev/console` | mirrored from the controlling tty when present (macOS reserves the real `/dev/console` for the kernel) |
+| other `/dev/*` | `ENOENT` |
+| `/proc/cpuinfo`, `/proc/meminfo`, `/proc/version` | derived from host sysctl |
+| `/proc/self/{maps,exe,status,stat,comm,statm,cgroup}` | synthesized; `cgroup` reports the canonical `0::/` (elfuse runs outside any cgroup hierarchy) |
+| `/proc/sys/kernel/{ostype,osrelease,hostname}` | tracks the cached `uname` fields (`Linux`, `6.17.0-20-generic`, `elfuse`) |
+
+### Libc-adjacent compatibility
+
+`elfuse` does not patch libc-adjacent payload (NSS modules, time-zone
+data, locale data, character-set converters, dynamic-linker cache)
+inside the guest. Each item below names the contract `elfuse` honors
+and the failure mode an image hits when it does not ship the
+matching files.
+
+- **`/etc/nsswitch.conf`** is read by the guest's libc, not by
+  `elfuse`. Only the `files` and `dns` backends actually function:
+  `files` resolves through `/etc/{passwd,group,hosts}` in the cloned
+  rootfs, and `dns` resolves through host `getaddrinfo` via the
+  synthesized `/etc/resolv.conf`. Backends such as `systemd`, `sss`,
+  or `ldap` need their NSS shared object plus a matching daemon,
+  neither of which `elfuse` provides.
+- **NSS shared objects** (`libnss_systemd.so`, `libnss_sss.so`,
+  `libnss_ldap.so`, ...) are `dlopen`'d by guest libc against its own
+  loader. `elfuse` never injects NSS modules: they are aarch64-linux
+  ELF objects against guest libc, so the macOS host has no way to
+  load them, and the guest can only `dlopen` the modules its image
+  already carries.
+- **tzdata** (`/usr/share/zoneinfo`, `/etc/localtime`, `/etc/timezone`)
+  ships with the image. `elfuse` does not transcode macOS
+  `/var/db/timezone/zoneinfo` into the tzdata format; if the image is
+  missing the needed zone, glibc / musl fall back to UTC. The `TZ`
+  environment variable is honored as-is and is not rewritten by the
+  Env merge policy.
+- **`/usr/lib/locale/locale-archive`** is not regenerated. glibc
+  images without a built archive (or the matching `<lang>.UTF-8/`
+  directory) fall back to the `C` locale; locale-aware sort / printf
+  / strcoll outputs ASCII order. musl images do not use the archive
+  and are unaffected.
+- **`/usr/lib/<triple>/gconv/`** modules and the `gconv-modules`
+  index ship with the image. Missing modules surface as `EILSEQ` from
+  `iconv` / glibc's character-set conversion; this most often shows
+  up when an image ships a stripped glibc layer.
+- **`ld.so.cache`** is not rebuilt. The guest dynamic linker reads
+  whatever cache the image carries; missing entries fall through to
+  the linker's library-path search, which is the normal slow path.
+
+Common workloads and the symptom-to-workaround mapping:
+
+| Symptom | Trigger | Workaround |
+|--|--|--|
+| `getaddrinfo` returns `EAI_AGAIN` or an empty result | `/etc/nsswitch.conf` lists a backend (`systemd`, `sss`, ...) that needs a daemon | use a distro whose `nsswitch.conf` is `files dns` (alpine ships this by default; debian needs the file edited) |
+| `date`, `strftime` show UTC instead of the expected zone | the image does not contain `/usr/share/zoneinfo/<Zone>` | install tzdata in the image (`apk add tzdata` / `apt install tzdata`), or pass `-e TZ=UTC` to acknowledge UTC |
+| `sort`, `printf`, `strcoll` collate in ASCII order | the image is missing `/usr/lib/locale/locale-archive` or the matching `<lang>.UTF-8/` directory | accept the C-locale fallback, run `locale-gen` during the image build, or use a musl-based image (alpine), which does not depend on the archive |
+
 ## Guest Compatibility Model
 
 `elfuse` is designed for Linux user-space workloads, not for booting a Linux

diff --git a/externals/cjson/LICENSE b/externals/cjson/LICENSE
@@ -0,0 +1,20 @@
+Copyright (c) 2009-2017 Dave Gamble and cJSON contributors
+
+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.
+
diff --git a/externals/cjson/VENDORING.md b/externals/cjson/VENDORING.md
@@ -0,0 +1,35 @@
+# Vendored cJSON
+
+This directory contains a vendored copy of [cJSON](https://github.com/DaveGamble/cJSON),
+the ultralightweight JSON parser written in ANSI C. cJSON ships as a single
+`.c` / `.h` pair and is dual-licensed under the MIT license (see `LICENSE`).
+
+## Why vendored
+
+`oci-roadmap.md` Q9 commits Phase 1 to hand-rolled C alongside the existing
+elfuse codebase: no Go, no Rust, no `cargo` / `go` in the build matrix. cJSON
+is the smallest credible JSON dependency that fits that contract; it is
+self-contained, has no external dependencies, and compiles cleanly with
+`clang` and `gcc` on macOS and Linux.
+
+## Version
+
+Pinned to upstream tag `v1.7.18` (2024-07-30). Fetched with:
+
+```
+curl -fsSL -o cJSON.h https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/cJSON.h
+curl -fsSL -o cJSON.c https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/cJSON.c
+curl -fsSL -o LICENSE https://raw.githubusercontent.com/DaveGamble/cJSON/v1.7.18/LICENSE
+```
+
+## Local modifications
+
+None. The files are byte-identical to the upstream tag so future security
+updates can be applied by re-running the curl commands above.
+
+## Build integration
+
+The Makefile compiles `cJSON.c` with project warning flags relaxed: cJSON is
+third-party code and its style does not match elfuse's `-Wpedantic
+-Wmissing-prototypes -Wshadow` posture. Only `src/oci/` translation units
+include `externals/cjson/cJSON.h`; the rest of the codebase never sees it.