diff --git a/.env.example b/.env.example index 18d8ae4..7d79c86 100644 --- a/.env.example +++ b/.env.example @@ -4,7 +4,17 @@ # Code signing team ID (find yours: `security find-identity -v -p codesigning`) DEVELOPMENT_TEAM= -# Notarization credentials for `make dist` +# Preferred local notarization setup. Create it once with: +# xcrun notarytool store-credentials ghostfile-notary \ +# --apple-id you@example.com --team-id YOUR_TEAM_ID +NOTARY_KEYCHAIN_PROFILE= + +# CI alternative: App Store Connect API key credentials. +NOTARY_KEY_FILE= +NOTARY_KEY_ID= +NOTARY_ISSUER_ID= + +# Legacy notarization credentials for `make dist` and GhostFile releases. NOTARY_APPLE_ID= NOTARY_TEAM_ID= NOTARY_PASSWORD= diff --git a/CONTAINER_RUNTIME_PROTOCOL.md b/CONTAINER_RUNTIME_PROTOCOL.md new file mode 100644 index 0000000..1c8562c --- /dev/null +++ b/CONTAINER_RUNTIME_PROTOCOL.md @@ -0,0 +1,143 @@ +# GhostVM Container Runtime Protocol + +The GhostVM container boundary is a backend-neutral runtime API. Docker is a +frontend implemented inside GhostTools; it is not the protocol spoken to the +outer host. + +```text +docker CLI / compose / another client + | + v + guest frontend adapter + | + v + GhostVM runtime protocol over vsock + | + v + host runtime backend + | + v + Apple Containerization or another engine +``` + +## Design rules + +1. Methods model runtime resources and lifecycle operations, not Docker HTTP + routes or Swift implementation types. +2. The guest owns frontend compatibility. For example, the Docker adapter maps + Docker Engine API requests to one or more runtime methods. +3. The host owns container objects and their lifetimes. A frontend refers to + images, filesystems, containers, and processes by stable IDs. +4. Every request carries a protocol major/minor version and request ID. A major + mismatch is incompatible; minor versions are additive. +5. Frontends call `system.capabilities` and must not infer behavior from the + host implementation or operating-system version. +6. Errors use stable machine-readable codes. Backend error strings are only + diagnostics and never control frontend behavior. +7. Large and interactive data uses bounded binary stream frames associated + with a request. JSON metadata must never contain whole build contexts, + filesystem archives, or unbounded process output. +8. Guest-backed `ReaderStream`, `Writer`, and `Terminal` resources carry process + I/O independently from container and process lifecycle calls. + +## Runtime surface + +| Resource | Methods | +|---|---| +| System | `system.capabilities` | +| Image | `image.pull`, `image.list`, `image.inspect`, `image.delete`, `image.unpack` | +| Filesystem | `filesystem.create`, `filesystem.delete` | +| Container | `container.create`, `container.start`, `container.stop`, `container.kill`, `container.wait`, `container.resize`, `container.state`, `container.list`, `container.delete` | +| Container I/O | `container.copyIn`, `container.copyOut`, `container.dial` | +| Process | `process.create`, `process.start`, `process.kill`, `process.wait`, `process.resize`, `process.delete` | +| Network | `network.createInterface`, `network.releaseInterface` | +| Build extension | `build.create` | + +`build.create` is a product-level extension because Containerization does not +define Dockerfile semantics. Its input context and output are streams; the host +may implement it with BuildKit or another builder. + +## Framework mapping + +| Runtime method | Containerization operation | +|---|---| +| `container.create` | `LinuxContainer.create()` | +| `container.start` | `LinuxContainer.start()` | +| `container.stop` | `LinuxContainer.stop()` | +| `container.kill` | `LinuxContainer.kill(_:)` | +| `container.wait` | `LinuxContainer.wait(timeoutInSeconds:)` | +| `container.resize` | `LinuxContainer.resize(to:)` | +| `process.create` | `LinuxContainer.exec(_:configuration:)` | +| `process.start` | `LinuxProcess.start()` | +| `process.kill` | `LinuxProcess.kill(_:)` | +| `process.wait` | `LinuxProcess.wait(timeoutInSeconds:)` | +| `process.resize` | `LinuxProcess.resize(to:)` | +| `container.copyIn` | `LinuxContainer.copyIn(...)` | +| `container.copyOut` | `LinuxContainer.copyOut(...)` | +| `container.dial` | `LinuxContainer.dialVsock(port:)` | + +This mapping is semantic rather than source-compatible. Swift actors, closures, +file handles, and concrete framework types are not part of the wire contract. + +### Guest directory mounts + +Frontend adapters translate a guest bind-mount source into a host-owned +filesystem resource before creating the container: + +```text +Docker or container volume syntax + | + v + filesystem.create(guestPath) + | + v + filesystem ID + container.create mount + | + v + host FSKit mount + Containerization.Mount.share +``` + +The `source` of a runtime mount is the filesystem resource ID returned by the +host. It is never an outer-host path supplied by the guest. Runtime mount fields +otherwise follow Containerization's semantic model: `type`, `source`, +`destination`, `options`, and `runtimeOptions`. + +Filesystem I/O is not tunneled through container lifecycle requests. The host +FSKit extension uses a separate bounded filesystem transport to GhostTools for +lookup, attributes, directory enumeration, and range I/O. + +### Persistent named volumes + +The additive `volume.create`, `volume.list`, `volume.inspect`, `volume.mount`, +and `volume.delete` methods manage sparse ext4 images in trusted per-VM storage. +`volume.mount` translates a named volume internally to +`Containerization.Mount.block`; guests exchange only `@volume/NAME` and +`@mount/NAME` references, never outer-host paths. Volumes survive container and +VM restarts and cannot be deleted while a mount reference reserves them. + +## Docker mapping + +Docker Compose is client-side orchestration. GhostTools can parse Compose files +and translate their core operations directly without requiring a Docker Engine +daemon or socket: + +| Docker operation | Runtime sequence | +|---|---| +| Pull image | `image.pull` | +| Bind guest directory | `filesystem.create`, then a `container.create` mount | +| Create container | `image.unpack`, `container.create` | +| Start container | `container.start` | +| Wait or inspect | `container.wait`, `container.state` | +| Exec | `process.create`, `process.start`, `process.wait`, `process.delete` | +| Stop or remove | `container.stop`, `container.delete` | +| Build Dockerfile | `build.create` with a streamed build context | + +Compose networks and restart policies are orchestration features. They are +exposed as additive capabilities rather than leaking Docker +request structures into the base container lifecycle API. Guest-side frontends +implement published-port listeners using the container address returned by the +host. + +There is no one-shot `run` request, Docker-shaped host request, compatibility +handshake, or fallback route. Frontends must use the resource methods above. +Methods that have not been implemented fail with `unsupported`. diff --git a/GHOSTBOX_CLI_COMMANDS.json b/GHOSTBOX_CLI_COMMANDS.json new file mode 100644 index 0000000..51cd2be --- /dev/null +++ b/GHOSTBOX_CLI_COMMANDS.json @@ -0,0 +1,11839 @@ +{ + "schemaVersion": 2, + "sources": [ + "GHOSTBOX_CLI_TEMPLATE.md", + "GHOSTBOX_CR_CLI_TEMPLATE.md" + ], + "namespaces": { + "cn": { + "name": "containerization", + "aliases": [ + "containerization" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "repository": "https://github.com/apple/containerization", + "version": "0.40.1", + "revision": "7800b4642171561c95b5f55500b19e5dce5acd45" + }, + "cr": { + "name": "container", + "aliases": [ + "container" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "repository": "https://github.com/apple/container", + "version": "1.2.0", + "revision": "6e65319fe476ffe8db8ddaf828a537ed36fe2859" + } + }, + "entryCount": 282, + "resourceCount": 39, + "resources": [ + "authentication", + "boot-log", + "capabilities", + "container", + "container-config", + "content", + "content-store", + "dns", + "hosts", + "hosts-entry", + "image", + "image-description", + "image-store", + "init-image", + "interface", + "kernel", + "kernel-command-line", + "kernel-image", + "manager", + "memory-size", + "mount", + "network", + "parser", + "pod", + "pod-config", + "pod-container-config", + "pod-volume", + "process", + "process-config", + "progress-handler", + "resource-labels", + "rlimit", + "rlimit-kind", + "socket", + "standard-vm-config", + "vm-config", + "vm-instance", + "vmm", + "volume" + ], + "sharedOptionGroups": { + "containerConfigOverride": [ + { + "names": [ + "--process" + ], + "type": "reference:process-config", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpus" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hostname" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sysctl" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--interfaces" + ], + "type": "reference:interface", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sockets" + ], + "type": "reference:socket", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--mounts" + ], + "type": "reference:mount", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--masked-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--readonly-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--dns" + ], + "type": "reference:dns", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hosts" + ], + "type": "reference:hosts", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--boot-log" + ], + "type": "reference:boot-log", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--oci-runtime-path" + ], + "type": "container-path", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--use-init" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpu-overhead" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory-overhead" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + } + ] + }, + "commands": [ + { + "commandID": "cn:image-store:create", + "methodID": "imageStore.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:create" + ], + "resource": "image-store", + "operation": "create", + "commandStart": "cn:image-store:create", + "commandShape": "create", + "positionals": [ + { + "name": "image-store", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--path" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--content-store" + ], + "type": "reference:content-store", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:image-store", + "minimalArgv": [ + "cn:image-store:create", + "example", + "--path", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 58 + }, + { + "commandID": "cn:image-store:default", + "methodID": "imageStore.default", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:default" + ], + "resource": "image-store", + "operation": "default", + "commandStart": "cn:image-store:default", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "reference:image-store", + "minimalArgv": [ + "cn:image-store:default" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 63 + }, + { + "commandID": "cn:image-store:path", + "methodID": "imageStore.path", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:path" + ], + "resource": "image-store", + "operation": "path", + "commandStart": "cn:image-store:path", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "host-url", + "minimalArgv": [ + "cn:image-store:path", + "@image-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 64 + }, + { + "commandID": "cn:image-store:get", + "methodID": "imageStore.get", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:get" + ], + "resource": "image-store", + "operation": "get", + "commandStart": "cn:image-store:get", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--pull" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:image", + "minimalArgv": [ + "cn:image-store:get", + "@image-store/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 66 + }, + { + "commandID": "cn:image-store:list", + "methodID": "imageStore.list", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:list" + ], + "resource": "image-store", + "operation": "list", + "commandStart": "cn:image-store:list", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:image[]", + "minimalArgv": [ + "cn:image-store:list", + "@image-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 71 + }, + { + "commandID": "cn:image-store:create-image", + "methodID": "imageStore.createImage", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:create-image" + ], + "resource": "image-store", + "operation": "create-image", + "commandStart": "cn:image-store:create-image", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "image-description", + "type": "reference:image-description", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:image", + "minimalArgv": [ + "cn:image-store:create-image", + "@image-store/example", + "@image-description/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 73 + }, + { + "commandID": "cn:image-store:delete", + "methodID": "imageStore.delete", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:delete" + ], + "resource": "image-store", + "operation": "delete", + "commandStart": "cn:image-store:delete", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--perform-cleanup" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "void", + "minimalArgv": [ + "cn:image-store:delete", + "@image-store/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 77 + }, + { + "commandID": "cn:image-store:clean-up-orphaned-blobs", + "methodID": "imageStore.cleanUpOrphanedBlobs", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:clean-up-orphaned-blobs" + ], + "resource": "image-store", + "operation": "clean-up-orphaned-blobs", + "commandStart": "cn:image-store:clean-up-orphaned-blobs", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "deleted-digests-and-freed-bytes", + "minimalArgv": [ + "cn:image-store:clean-up-orphaned-blobs", + "@image-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 81 + }, + { + "commandID": "cn:image-store:calculate-orphaned-blobs-size", + "methodID": "imageStore.calculateOrphanedBlobsSize", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:calculate-orphaned-blobs-size" + ], + "resource": "image-store", + "operation": "calculate-orphaned-blobs-size", + "commandStart": "cn:image-store:calculate-orphaned-blobs-size", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cn:image-store:calculate-orphaned-blobs-size", + "@image-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 84 + }, + { + "commandID": "cn:image-store:tag", + "methodID": "imageStore.tag", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:tag" + ], + "resource": "image-store", + "operation": "tag", + "commandStart": "cn:image-store:tag", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "existing-reference", + "type": "string", + "required": true, + "repeatable": false + }, + { + "name": "new-reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:image", + "minimalArgv": [ + "cn:image-store:tag", + "@image-store/example", + "example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 87 + }, + { + "commandID": "cn:image-store:pull", + "methodID": "imageStore.pull", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:pull" + ], + "resource": "image-store", + "operation": "pull", + "commandStart": "cn:image-store:pull", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--platform" + ], + "type": "oci-platform", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--insecure" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--authentication" + ], + "type": "reference:authentication", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--max-concurrent-downloads" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 3 + } + ], + "resultType": "reference:image", + "minimalArgv": [ + "cn:image-store:pull", + "@image-store/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 92 + }, + { + "commandID": "cn:image-store:push", + "methodID": "imageStore.push", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:push" + ], + "resource": "image-store", + "operation": "push", + "commandStart": "cn:image-store:push", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--platform" + ], + "type": "oci-platform", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--insecure" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--authentication" + ], + "type": "reference:authentication", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "void", + "minimalArgv": [ + "cn:image-store:push", + "@image-store/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 101 + }, + { + "commandID": "cn:image-store:push-many", + "methodID": "imageStore.pushMany", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:push-many" + ], + "resource": "image-store", + "operation": "push-many", + "commandStart": "cn:image-store:push-many", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": true + } + ], + "options": [ + { + "names": [ + "--platform" + ], + "type": "oci-platform", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--insecure" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--authentication" + ], + "type": "reference:authentication", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--max-concurrent-uploads" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 3 + }, + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "void", + "minimalArgv": [ + "cn:image-store:push-many", + "@image-store/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 108 + }, + { + "commandID": "cn:image-store:save", + "methodID": "imageStore.save", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:save" + ], + "resource": "image-store", + "operation": "save", + "commandStart": "cn:image-store:save", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": true + } + ], + "options": [ + { + "names": [ + "--out" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--platform" + ], + "type": "oci-platform", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "void", + "minimalArgv": [ + "cn:image-store:save", + "@image-store/example", + "example", + "--out", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 116 + }, + { + "commandID": "cn:image-store:load", + "methodID": "imageStore.load", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:load" + ], + "resource": "image-store", + "operation": "load", + "commandStart": "cn:image-store:load", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "directory", + "type": "host-url", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:image[]", + "minimalArgv": [ + "cn:image-store:load", + "@image-store/example", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 121 + }, + { + "commandID": "cn:image-store:get-init-image", + "methodID": "imageStore.getInitImage", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-store:get-init-image" + ], + "resource": "image-store", + "operation": "get-init-image", + "commandStart": "cn:image-store:get-init-image", + "commandShape": "reference", + "positionals": [ + { + "name": "image-store", + "type": "reference:image-store", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--authentication" + ], + "type": "reference:authentication", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:init-image", + "minimalArgv": [ + "cn:image-store:get-init-image", + "@image-store/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 126 + }, + { + "commandID": "cn:image-description:create", + "methodID": "imageDescription.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-description:create" + ], + "resource": "image-description", + "operation": "create", + "commandStart": "cn:image-description:create", + "commandShape": "create", + "positionals": [ + { + "name": "image-description", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + }, + { + "name": "descriptor", + "type": "oci-descriptor-json", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:image-description", + "minimalArgv": [ + "cn:image-description:create", + "example", + "example", + "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:0000000000000000000000000000000000000000000000000000000000000000\",\"size\":0}" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 140 + }, + { + "commandID": "cn:image-description:reference", + "methodID": "imageDescription.reference", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-description:reference" + ], + "resource": "image-description", + "operation": "reference", + "commandStart": "cn:image-description:reference", + "commandShape": "reference", + "positionals": [ + { + "name": "image-description", + "type": "reference:image-description", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:image-description:reference", + "@image-description/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 145 + }, + { + "commandID": "cn:image-description:descriptor", + "methodID": "imageDescription.descriptor", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-description:descriptor" + ], + "resource": "image-description", + "operation": "descriptor", + "commandStart": "cn:image-description:descriptor", + "commandShape": "reference", + "positionals": [ + { + "name": "image-description", + "type": "reference:image-description", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-descriptor", + "minimalArgv": [ + "cn:image-description:descriptor", + "@image-description/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 146 + }, + { + "commandID": "cn:image-description:digest", + "methodID": "imageDescription.digest", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-description:digest" + ], + "resource": "image-description", + "operation": "digest", + "commandStart": "cn:image-description:digest", + "commandShape": "reference", + "positionals": [ + { + "name": "image-description", + "type": "reference:image-description", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:image-description:digest", + "@image-description/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 147 + }, + { + "commandID": "cn:image-description:media-type", + "methodID": "imageDescription.mediaType", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image-description:media-type" + ], + "resource": "image-description", + "operation": "media-type", + "commandStart": "cn:image-description:media-type", + "commandShape": "reference", + "positionals": [ + { + "name": "image-description", + "type": "reference:image-description", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:image-description:media-type", + "@image-description/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 148 + }, + { + "commandID": "cn:image:create", + "methodID": "image.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:create" + ], + "resource": "image", + "operation": "create", + "commandStart": "cn:image:create", + "commandShape": "create", + "positionals": [ + { + "name": "image", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "image-description", + "type": "reference:image-description", + "required": true, + "repeatable": false + }, + { + "name": "content-store", + "type": "reference:content-store", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:image", + "minimalArgv": [ + "cn:image:create", + "example", + "@image-description/example", + "@content-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 150 + }, + { + "commandID": "cn:image:description", + "methodID": "image.description", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:description" + ], + "resource": "image", + "operation": "description", + "commandStart": "cn:image:description", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "image-description", + "minimalArgv": [ + "cn:image:description", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 155 + }, + { + "commandID": "cn:image:descriptor", + "methodID": "image.descriptor", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:descriptor" + ], + "resource": "image", + "operation": "descriptor", + "commandStart": "cn:image:descriptor", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-descriptor", + "minimalArgv": [ + "cn:image:descriptor", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 156 + }, + { + "commandID": "cn:image:digest", + "methodID": "image.digest", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:digest" + ], + "resource": "image", + "operation": "digest", + "commandStart": "cn:image:digest", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:image:digest", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 157 + }, + { + "commandID": "cn:image:media-type", + "methodID": "image.mediaType", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:media-type" + ], + "resource": "image", + "operation": "media-type", + "commandStart": "cn:image:media-type", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:image:media-type", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 158 + }, + { + "commandID": "cn:image:reference", + "methodID": "image.reference", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:reference" + ], + "resource": "image", + "operation": "reference", + "commandStart": "cn:image:reference", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:image:reference", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 159 + }, + { + "commandID": "cn:image:index", + "methodID": "image.index", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:index" + ], + "resource": "image", + "operation": "index", + "commandStart": "cn:image:index", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-index", + "minimalArgv": [ + "cn:image:index", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 160 + }, + { + "commandID": "cn:image:manifest", + "methodID": "image.manifest", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:manifest" + ], + "resource": "image", + "operation": "manifest", + "commandStart": "cn:image:manifest", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + }, + { + "name": "platform", + "type": "oci-platform", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-manifest", + "minimalArgv": [ + "cn:image:manifest", + "@image/example", + "linux/arm64" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 162 + }, + { + "commandID": "cn:image:descriptor-for", + "methodID": "image.descriptorFor", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:descriptor-for" + ], + "resource": "image", + "operation": "descriptor-for", + "commandStart": "cn:image:descriptor-for", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + }, + { + "name": "platform", + "type": "oci-platform", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-descriptor", + "minimalArgv": [ + "cn:image:descriptor-for", + "@image/example", + "linux/arm64" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 166 + }, + { + "commandID": "cn:image:config", + "methodID": "image.config", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:config" + ], + "resource": "image", + "operation": "config", + "commandStart": "cn:image:config", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + }, + { + "name": "platform", + "type": "oci-platform", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-image", + "minimalArgv": [ + "cn:image:config", + "@image/example", + "linux/arm64" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 170 + }, + { + "commandID": "cn:image:referenced-digests", + "methodID": "image.referencedDigests", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:referenced-digests" + ], + "resource": "image", + "operation": "referenced-digests", + "commandStart": "cn:image:referenced-digests", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:image:referenced-digests", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 174 + }, + { + "commandID": "cn:image:get-content", + "methodID": "image.getContent", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:image:get-content" + ], + "resource": "image", + "operation": "get-content", + "commandStart": "cn:image:get-content", + "commandShape": "reference", + "positionals": [ + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + }, + { + "name": "digest", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:content", + "minimalArgv": [ + "cn:image:get-content", + "@image/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 176 + }, + { + "commandID": "cn:content:path", + "methodID": "content.path", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:content:path" + ], + "resource": "content", + "operation": "path", + "commandStart": "cn:content:path", + "commandShape": "reference", + "positionals": [ + { + "name": "content", + "type": "reference:content", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "host-url", + "minimalArgv": [ + "cn:content:path", + "@content/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 180 + }, + { + "commandID": "cn:content:digest", + "methodID": "content.digest", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:content:digest" + ], + "resource": "content", + "operation": "digest", + "commandStart": "cn:content:digest", + "commandShape": "reference", + "positionals": [ + { + "name": "content", + "type": "reference:content", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "sha256-digest", + "minimalArgv": [ + "cn:content:digest", + "@content/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 181 + }, + { + "commandID": "cn:content:size", + "methodID": "content.size", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:content:size" + ], + "resource": "content", + "operation": "size", + "commandStart": "cn:content:size", + "commandShape": "reference", + "positionals": [ + { + "name": "content", + "type": "reference:content", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cn:content:size", + "@content/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 182 + }, + { + "commandID": "cn:content:data", + "methodID": "content.data", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:content:data" + ], + "resource": "content", + "operation": "data", + "commandStart": "cn:content:data", + "commandShape": "reference", + "positionals": [ + { + "name": "content", + "type": "reference:content", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "byte-stream", + "minimalArgv": [ + "cn:content:data", + "@content/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 183 + }, + { + "commandID": "cn:content:data-range", + "methodID": "content.dataRange", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:content:data-range" + ], + "resource": "content", + "operation": "data-range", + "commandStart": "cn:content:data-range", + "commandShape": "reference", + "positionals": [ + { + "name": "content", + "type": "reference:content", + "required": true, + "repeatable": false + }, + { + "name": "offset", + "type": "uint64", + "required": true, + "repeatable": false + }, + { + "name": "length", + "type": "int", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "byte-stream?", + "minimalArgv": [ + "cn:content:data-range", + "@content/example", + "1", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 184 + }, + { + "commandID": "cn:kernel-command-line:create", + "methodID": "kernelCommandLine.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:create" + ], + "resource": "kernel-command-line", + "operation": "create", + "commandStart": "cn:kernel-command-line:create", + "commandShape": "create", + "positionals": [ + { + "name": "command-line", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel-argument" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--init-argument" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:kernel-command-line", + "minimalArgv": [ + "cn:kernel-command-line:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 193 + }, + { + "commandID": "cn:kernel-command-line:create-debug", + "methodID": "kernelCommandLine.createDebug", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:create-debug" + ], + "resource": "kernel-command-line", + "operation": "create-debug", + "commandStart": "cn:kernel-command-line:create-debug", + "commandShape": "create", + "positionals": [ + { + "name": "command-line", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "debug", + "type": "bool", + "required": true, + "repeatable": false + }, + { + "name": "panic", + "type": "int", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--init-argument" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:kernel-command-line", + "minimalArgv": [ + "cn:kernel-command-line:create-debug", + "example", + "true", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 198 + }, + { + "commandID": "cn:kernel-command-line:add-debug", + "methodID": "kernelCommandLine.addDebug", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:add-debug" + ], + "resource": "kernel-command-line", + "operation": "add-debug", + "commandStart": "cn:kernel-command-line:add-debug", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-command-line", + "type": "reference:kernel-command-line", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:kernel-command-line:add-debug", + "@kernel-command-line/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 204 + }, + { + "commandID": "cn:kernel-command-line:add-panic", + "methodID": "kernelCommandLine.addPanic", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:add-panic" + ], + "resource": "kernel-command-line", + "operation": "add-panic", + "commandStart": "cn:kernel-command-line:add-panic", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-command-line", + "type": "reference:kernel-command-line", + "required": true, + "repeatable": false + }, + { + "name": "level", + "type": "int", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:kernel-command-line:add-panic", + "@kernel-command-line/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 205 + }, + { + "commandID": "cn:kernel-command-line:set-agent-log-level", + "methodID": "kernelCommandLine.setAgentLogLevel", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:set-agent-log-level" + ], + "resource": "kernel-command-line", + "operation": "set-agent-log-level", + "commandStart": "cn:kernel-command-line:set-agent-log-level", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-command-line", + "type": "reference:kernel-command-line", + "required": true, + "repeatable": false + }, + { + "name": "level", + "type": "logger-level", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:kernel-command-line:set-agent-log-level", + "@kernel-command-line/example", + "info" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 206 + }, + { + "commandID": "cn:kernel-command-line:kernel-arguments", + "methodID": "kernelCommandLine.kernelArguments", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:kernel-arguments" + ], + "resource": "kernel-command-line", + "operation": "kernel-arguments", + "commandStart": "cn:kernel-command-line:kernel-arguments", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-command-line", + "type": "reference:kernel-command-line", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:kernel-command-line:kernel-arguments", + "@kernel-command-line/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 207 + }, + { + "commandID": "cn:kernel-command-line:init-arguments", + "methodID": "kernelCommandLine.initArguments", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-command-line:init-arguments" + ], + "resource": "kernel-command-line", + "operation": "init-arguments", + "commandStart": "cn:kernel-command-line:init-arguments", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-command-line", + "type": "reference:kernel-command-line", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:kernel-command-line:init-arguments", + "@kernel-command-line/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 208 + }, + { + "commandID": "cn:kernel:create", + "methodID": "kernel.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel:create" + ], + "resource": "kernel", + "operation": "create", + "commandStart": "cn:kernel:create", + "commandShape": "create", + "positionals": [ + { + "name": "kernel", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--path" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--platform" + ], + "type": "system-platform", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--command-line" + ], + "type": "reference:kernel-command-line", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:kernel", + "minimalArgv": [ + "cn:kernel:create", + "example", + "--path", + "/tmp/example", + "--platform", + "linux/arm64" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 210 + }, + { + "commandID": "cn:kernel:path", + "methodID": "kernel.path", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel:path" + ], + "resource": "kernel", + "operation": "path", + "commandStart": "cn:kernel:path", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel", + "type": "reference:kernel", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "host-url", + "minimalArgv": [ + "cn:kernel:path", + "@kernel/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 216 + }, + { + "commandID": "cn:kernel:platform", + "methodID": "kernel.platform", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel:platform" + ], + "resource": "kernel", + "operation": "platform", + "commandStart": "cn:kernel:platform", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel", + "type": "reference:kernel", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "system-platform", + "minimalArgv": [ + "cn:kernel:platform", + "@kernel/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 217 + }, + { + "commandID": "cn:kernel:kernel-arguments", + "methodID": "kernel.kernelArguments", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel:kernel-arguments" + ], + "resource": "kernel", + "operation": "kernel-arguments", + "commandStart": "cn:kernel:kernel-arguments", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel", + "type": "reference:kernel", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:kernel:kernel-arguments", + "@kernel/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 218 + }, + { + "commandID": "cn:kernel:init-arguments", + "methodID": "kernel.initArguments", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel:init-arguments" + ], + "resource": "kernel", + "operation": "init-arguments", + "commandStart": "cn:kernel:init-arguments", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel", + "type": "reference:kernel", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:kernel:init-arguments", + "@kernel/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 219 + }, + { + "commandID": "cn:kernel-image:from-image", + "methodID": "kernelImage.fromImage", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-image:from-image" + ], + "resource": "kernel-image", + "operation": "from-image", + "commandStart": "cn:kernel-image:from-image", + "commandShape": "create", + "positionals": [ + { + "name": "kernel-image", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:kernel-image", + "minimalArgv": [ + "cn:kernel-image:from-image", + "example", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 221 + }, + { + "commandID": "cn:kernel-image:create", + "methodID": "kernelImage.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-image:create" + ], + "resource": "kernel-image", + "operation": "create", + "commandStart": "cn:kernel-image:create", + "commandShape": "create", + "positionals": [ + { + "name": "kernel-image", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel" + ], + "type": "reference:kernel", + "required": true, + "repeatable": true, + "default": null + }, + { + "names": [ + "--label" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--image-store" + ], + "type": "reference:image-store", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--content-store" + ], + "type": "reference:content-store", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:kernel-image", + "minimalArgv": [ + "cn:kernel-image:create", + "example", + "example", + "--kernel", + "@kernel/example", + "--image-store", + "@image-store/example", + "--content-store", + "@content-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 225 + }, + { + "commandID": "cn:kernel-image:kernel", + "methodID": "kernelImage.kernel", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-image:kernel" + ], + "resource": "kernel-image", + "operation": "kernel", + "commandStart": "cn:kernel-image:kernel", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-image", + "type": "reference:kernel-image", + "required": true, + "repeatable": false + }, + { + "name": "platform", + "type": "system-platform", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:kernel", + "minimalArgv": [ + "cn:kernel-image:kernel", + "@kernel-image/example", + "linux/arm64" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 233 + }, + { + "commandID": "cn:kernel-image:name", + "methodID": "kernelImage.name", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-image:name" + ], + "resource": "kernel-image", + "operation": "name", + "commandStart": "cn:kernel-image:name", + "commandShape": "reference", + "positionals": [ + { + "name": "kernel-image", + "type": "reference:kernel-image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:kernel-image:name", + "@kernel-image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 237 + }, + { + "commandID": "cn:kernel-image:media-type", + "methodID": "kernelImage.mediaType", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:kernel-image:media-type" + ], + "resource": "kernel-image", + "operation": "media-type", + "commandStart": "cn:kernel-image:media-type", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:kernel-image:media-type" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 238 + }, + { + "commandID": "cn:init-image:from-image", + "methodID": "initImage.fromImage", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:init-image:from-image" + ], + "resource": "init-image", + "operation": "from-image", + "commandStart": "cn:init-image:from-image", + "commandShape": "create", + "positionals": [ + { + "name": "init-image", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "image", + "type": "reference:image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:init-image", + "minimalArgv": [ + "cn:init-image:from-image", + "example", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 240 + }, + { + "commandID": "cn:init-image:create", + "methodID": "initImage.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:init-image:create" + ], + "resource": "init-image", + "operation": "create", + "commandStart": "cn:init-image:create", + "commandShape": "create", + "positionals": [ + { + "name": "init-image", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "reference", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--rootfs" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--platform" + ], + "type": "oci-platform", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--label" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--image-store" + ], + "type": "reference:image-store", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--content-store" + ], + "type": "reference:content-store", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:init-image", + "minimalArgv": [ + "cn:init-image:create", + "example", + "example", + "--rootfs", + "/tmp/example", + "--platform", + "linux/arm64", + "--image-store", + "@image-store/example", + "--content-store", + "@content-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 244 + }, + { + "commandID": "cn:init-image:init-block", + "methodID": "initImage.initBlock", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:init-image:init-block" + ], + "resource": "init-image", + "operation": "init-block", + "commandStart": "cn:init-image:init-block", + "commandShape": "reference", + "positionals": [ + { + "name": "init-image", + "type": "reference:init-image", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--at" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--platform" + ], + "type": "system-platform", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:init-image:init-block", + "@init-image/example", + "--at", + "/tmp/example", + "--platform", + "linux/arm64" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 253 + }, + { + "commandID": "cn:init-image:name", + "methodID": "initImage.name", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:init-image:name" + ], + "resource": "init-image", + "operation": "name", + "commandStart": "cn:init-image:name", + "commandShape": "reference", + "positionals": [ + { + "name": "init-image", + "type": "reference:init-image", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:init-image:name", + "@init-image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 258 + }, + { + "commandID": "cn:mount:create", + "methodID": "mount.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:create" + ], + "resource": "mount", + "operation": "create", + "commandStart": "cn:mount:create", + "commandShape": "create", + "positionals": [ + { + "name": "mount", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--type" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--source" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--destination" + ], + "type": "container-path", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--option" + ], + "type": "string", + "required": true, + "repeatable": true, + "default": null + }, + { + "names": [ + "--runtime-options" + ], + "type": "mount-runtime-options", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:mount:create", + "example", + "--type", + "example", + "--source", + "example", + "--destination", + "/example", + "--option", + "example", + "--runtime-options", + "{}" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 264 + }, + { + "commandID": "cn:mount:block", + "methodID": "mount.block", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:block" + ], + "resource": "mount", + "operation": "block", + "commandStart": "cn:mount:block", + "commandShape": "create", + "positionals": [ + { + "name": "mount", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--format" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--source" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--destination" + ], + "type": "container-path", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--runtime-option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:mount:block", + "example", + "--format", + "example", + "--source", + "example", + "--destination", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 272 + }, + { + "commandID": "cn:mount:share", + "methodID": "mount.share", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:share" + ], + "resource": "mount", + "operation": "share", + "commandStart": "cn:mount:share", + "commandShape": "create", + "positionals": [ + { + "name": "mount", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--source" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--destination" + ], + "type": "container-path", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--runtime-option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:mount:share", + "example", + "--source", + "example", + "--destination", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 280 + }, + { + "commandID": "cn:mount:any", + "methodID": "mount.any", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:any" + ], + "resource": "mount", + "operation": "any", + "commandStart": "cn:mount:any", + "commandShape": "create", + "positionals": [ + { + "name": "mount", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--type" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--source" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--destination" + ], + "type": "container-path", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--runtime-option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:mount:any", + "example", + "--type", + "example", + "--source", + "example", + "--destination", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 287 + }, + { + "commandID": "cn:mount:shared-mount", + "methodID": "mount.sharedMount", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:shared-mount" + ], + "resource": "mount", + "operation": "shared-mount", + "commandStart": "cn:mount:shared-mount", + "commandShape": "create", + "positionals": [ + { + "name": "mount", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--name" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--destination" + ], + "type": "container-path", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:mount:shared-mount", + "example", + "--name", + "example", + "--destination", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 295 + }, + { + "commandID": "cn:mount:clone", + "methodID": "mount.clone", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:clone" + ], + "resource": "mount", + "operation": "clone", + "commandStart": "cn:mount:clone", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--to" + ], + "type": "host-path", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:mount:clone", + "@mount/example", + "--to", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 301 + }, + { + "commandID": "cn:mount:is-block", + "methodID": "mount.isBlock", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:is-block" + ], + "resource": "mount", + "operation": "is-block", + "commandStart": "cn:mount:is-block", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "bool", + "minimalArgv": [ + "cn:mount:is-block", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 305 + }, + { + "commandID": "cn:mount:type", + "methodID": "mount.type", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:type" + ], + "resource": "mount", + "operation": "type", + "commandStart": "cn:mount:type", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:mount:type", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 306 + }, + { + "commandID": "cn:mount:source", + "methodID": "mount.source", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:source" + ], + "resource": "mount", + "operation": "source", + "commandStart": "cn:mount:source", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:mount:source", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 307 + }, + { + "commandID": "cn:mount:destination", + "methodID": "mount.destination", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:destination" + ], + "resource": "mount", + "operation": "destination", + "commandStart": "cn:mount:destination", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:mount:destination", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 308 + }, + { + "commandID": "cn:mount:options", + "methodID": "mount.options", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:options" + ], + "resource": "mount", + "operation": "options", + "commandStart": "cn:mount:options", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:mount:options", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 309 + }, + { + "commandID": "cn:mount:runtime-options", + "methodID": "mount.runtimeOptions", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:mount:runtime-options" + ], + "resource": "mount", + "operation": "runtime-options", + "commandStart": "cn:mount:runtime-options", + "commandShape": "reference", + "positionals": [ + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "mount-runtime-options", + "minimalArgv": [ + "cn:mount:runtime-options", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 310 + }, + { + "commandID": "cn:dns:create", + "methodID": "dns.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:create" + ], + "resource": "dns", + "operation": "create", + "commandStart": "cn:dns:create", + "commandShape": "create", + "positionals": [ + { + "name": "dns", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--nameserver" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--domain" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--search-domain" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--option" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:dns", + "minimalArgv": [ + "cn:dns:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 316 + }, + { + "commandID": "cn:dns:default-nameservers", + "methodID": "dns.defaultNameservers", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:default-nameservers" + ], + "resource": "dns", + "operation": "default-nameservers", + "commandStart": "cn:dns:default-nameservers", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:dns:default-nameservers" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 323 + }, + { + "commandID": "cn:dns:validate", + "methodID": "dns.validate", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:validate" + ], + "resource": "dns", + "operation": "validate", + "commandStart": "cn:dns:validate", + "commandShape": "reference", + "positionals": [ + { + "name": "dns", + "type": "reference:dns", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:dns:validate", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 324 + }, + { + "commandID": "cn:dns:resolv-conf", + "methodID": "dns.resolvConf", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:resolv-conf" + ], + "resource": "dns", + "operation": "resolv-conf", + "commandStart": "cn:dns:resolv-conf", + "commandShape": "reference", + "positionals": [ + { + "name": "dns", + "type": "reference:dns", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:dns:resolv-conf", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 325 + }, + { + "commandID": "cn:dns:nameservers", + "methodID": "dns.nameservers", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:nameservers" + ], + "resource": "dns", + "operation": "nameservers", + "commandStart": "cn:dns:nameservers", + "commandShape": "reference", + "positionals": [ + { + "name": "dns", + "type": "reference:dns", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:dns:nameservers", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 326 + }, + { + "commandID": "cn:dns:domain", + "methodID": "dns.domain", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:domain" + ], + "resource": "dns", + "operation": "domain", + "commandStart": "cn:dns:domain", + "commandShape": "reference", + "positionals": [ + { + "name": "dns", + "type": "reference:dns", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string?", + "minimalArgv": [ + "cn:dns:domain", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 327 + }, + { + "commandID": "cn:dns:search-domains", + "methodID": "dns.searchDomains", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:search-domains" + ], + "resource": "dns", + "operation": "search-domains", + "commandStart": "cn:dns:search-domains", + "commandShape": "reference", + "positionals": [ + { + "name": "dns", + "type": "reference:dns", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:dns:search-domains", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 328 + }, + { + "commandID": "cn:dns:options", + "methodID": "dns.options", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:dns:options" + ], + "resource": "dns", + "operation": "options", + "commandStart": "cn:dns:options", + "commandShape": "reference", + "positionals": [ + { + "name": "dns", + "type": "reference:dns", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:dns:options", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 329 + }, + { + "commandID": "cn:hosts-entry:create", + "methodID": "hostsEntry.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:create" + ], + "resource": "hosts-entry", + "operation": "create", + "commandStart": "cn:hosts-entry:create", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "ip-address", + "type": "string", + "required": true, + "repeatable": false + }, + { + "name": "hostname", + "type": "string", + "required": true, + "repeatable": true + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:create", + "example", + "example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 331 + }, + { + "commandID": "cn:hosts-entry:localhost-ipv4", + "methodID": "hostsEntry.localhostIpv4", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:localhost-ipv4" + ], + "resource": "hosts-entry", + "operation": "localhost-ipv4", + "commandStart": "cn:hosts-entry:localhost-ipv4", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:localhost-ipv4", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 337 + }, + { + "commandID": "cn:hosts-entry:localhost-ipv6", + "methodID": "hostsEntry.localhostIpv6", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:localhost-ipv6" + ], + "resource": "hosts-entry", + "operation": "localhost-ipv6", + "commandStart": "cn:hosts-entry:localhost-ipv6", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:localhost-ipv6", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 338 + }, + { + "commandID": "cn:hosts-entry:ipv6-localnet", + "methodID": "hostsEntry.ipv6Localnet", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:ipv6-localnet" + ], + "resource": "hosts-entry", + "operation": "ipv6-localnet", + "commandStart": "cn:hosts-entry:ipv6-localnet", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:ipv6-localnet", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 339 + }, + { + "commandID": "cn:hosts-entry:ipv6-mcastprefix", + "methodID": "hostsEntry.ipv6Mcastprefix", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:ipv6-mcastprefix" + ], + "resource": "hosts-entry", + "operation": "ipv6-mcastprefix", + "commandStart": "cn:hosts-entry:ipv6-mcastprefix", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:ipv6-mcastprefix", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 340 + }, + { + "commandID": "cn:hosts-entry:ipv6-allnodes", + "methodID": "hostsEntry.ipv6Allnodes", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:ipv6-allnodes" + ], + "resource": "hosts-entry", + "operation": "ipv6-allnodes", + "commandStart": "cn:hosts-entry:ipv6-allnodes", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:ipv6-allnodes", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 341 + }, + { + "commandID": "cn:hosts-entry:ipv6-allrouters", + "methodID": "hostsEntry.ipv6Allrouters", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:ipv6-allrouters" + ], + "resource": "hosts-entry", + "operation": "ipv6-allrouters", + "commandStart": "cn:hosts-entry:ipv6-allrouters", + "commandShape": "create", + "positionals": [ + { + "name": "hosts-entry", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts-entry", + "minimalArgv": [ + "cn:hosts-entry:ipv6-allrouters", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 342 + }, + { + "commandID": "cn:hosts-entry:rendered", + "methodID": "hostsEntry.rendered", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:rendered" + ], + "resource": "hosts-entry", + "operation": "rendered", + "commandStart": "cn:hosts-entry:rendered", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts-entry", + "type": "reference:hosts-entry", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:hosts-entry:rendered", + "@hosts-entry/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 343 + }, + { + "commandID": "cn:hosts-entry:ip-address", + "methodID": "hostsEntry.ipAddress", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:ip-address" + ], + "resource": "hosts-entry", + "operation": "ip-address", + "commandStart": "cn:hosts-entry:ip-address", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts-entry", + "type": "reference:hosts-entry", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:hosts-entry:ip-address", + "@hosts-entry/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 344 + }, + { + "commandID": "cn:hosts-entry:hostnames", + "methodID": "hostsEntry.hostnames", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:hostnames" + ], + "resource": "hosts-entry", + "operation": "hostnames", + "commandStart": "cn:hosts-entry:hostnames", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts-entry", + "type": "reference:hosts-entry", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:hosts-entry:hostnames", + "@hosts-entry/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 345 + }, + { + "commandID": "cn:hosts-entry:comment", + "methodID": "hostsEntry.comment", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts-entry:comment" + ], + "resource": "hosts-entry", + "operation": "comment", + "commandStart": "cn:hosts-entry:comment", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts-entry", + "type": "reference:hosts-entry", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string?", + "minimalArgv": [ + "cn:hosts-entry:comment", + "@hosts-entry/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 346 + }, + { + "commandID": "cn:hosts:create", + "methodID": "hosts.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts:create" + ], + "resource": "hosts", + "operation": "create", + "commandStart": "cn:hosts:create", + "commandShape": "create", + "positionals": [ + { + "name": "hosts", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--entry" + ], + "type": "reference:hosts-entry", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--comment" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:hosts", + "minimalArgv": [ + "cn:hosts:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 348 + }, + { + "commandID": "cn:hosts:default", + "methodID": "hosts.default", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts:default" + ], + "resource": "hosts", + "operation": "default", + "commandStart": "cn:hosts:default", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "reference:hosts", + "minimalArgv": [ + "cn:hosts:default" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 353 + }, + { + "commandID": "cn:hosts:hosts-file", + "methodID": "hosts.hostsFile", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts:hosts-file" + ], + "resource": "hosts", + "operation": "hosts-file", + "commandStart": "cn:hosts:hosts-file", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts", + "type": "reference:hosts", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:hosts:hosts-file", + "@hosts/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 354 + }, + { + "commandID": "cn:hosts:entries", + "methodID": "hosts.entries", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts:entries" + ], + "resource": "hosts", + "operation": "entries", + "commandStart": "cn:hosts:entries", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts", + "type": "reference:hosts", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:hosts-entry[]", + "minimalArgv": [ + "cn:hosts:entries", + "@hosts/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 355 + }, + { + "commandID": "cn:hosts:comment", + "methodID": "hosts.comment", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:hosts:comment" + ], + "resource": "hosts", + "operation": "comment", + "commandStart": "cn:hosts:comment", + "commandShape": "reference", + "positionals": [ + { + "name": "hosts", + "type": "reference:hosts", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string?", + "minimalArgv": [ + "cn:hosts:comment", + "@hosts/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 356 + }, + { + "commandID": "cn:socket:create", + "methodID": "socket.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:socket:create" + ], + "resource": "socket", + "operation": "create", + "commandStart": "cn:socket:create", + "commandShape": "create", + "positionals": [ + { + "name": "socket", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--source" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--destination" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--permissions" + ], + "type": "file-permissions", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--direction" + ], + "type": "into|out-of", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:socket", + "minimalArgv": [ + "cn:socket:create", + "example", + "--source", + "/tmp/example", + "--destination", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 362 + }, + { + "commandID": "cn:socket:id", + "methodID": "socket.id", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:socket:id" + ], + "resource": "socket", + "operation": "id", + "commandStart": "cn:socket:id", + "commandShape": "reference", + "positionals": [ + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:socket:id", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 369 + }, + { + "commandID": "cn:socket:source", + "methodID": "socket.source", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:socket:source" + ], + "resource": "socket", + "operation": "source", + "commandStart": "cn:socket:source", + "commandShape": "reference", + "positionals": [ + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "host-url", + "minimalArgv": [ + "cn:socket:source", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 370 + }, + { + "commandID": "cn:socket:destination", + "methodID": "socket.destination", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:socket:destination" + ], + "resource": "socket", + "operation": "destination", + "commandStart": "cn:socket:destination", + "commandShape": "reference", + "positionals": [ + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "host-url", + "minimalArgv": [ + "cn:socket:destination", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 371 + }, + { + "commandID": "cn:socket:permissions", + "methodID": "socket.permissions", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:socket:permissions" + ], + "resource": "socket", + "operation": "permissions", + "commandStart": "cn:socket:permissions", + "commandShape": "reference", + "positionals": [ + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "file-permissions?", + "minimalArgv": [ + "cn:socket:permissions", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 372 + }, + { + "commandID": "cn:socket:direction", + "methodID": "socket.direction", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:socket:direction" + ], + "resource": "socket", + "operation": "direction", + "commandStart": "cn:socket:direction", + "commandShape": "reference", + "positionals": [ + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "into|out-of", + "minimalArgv": [ + "cn:socket:direction", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 373 + }, + { + "commandID": "cn:boot-log:file", + "methodID": "bootLog.file", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:boot-log:file" + ], + "resource": "boot-log", + "operation": "file", + "commandStart": "cn:boot-log:file", + "commandShape": "create", + "positionals": [ + { + "name": "boot-log", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--path" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--append" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": true + } + ], + "resultType": "reference:boot-log", + "minimalArgv": [ + "cn:boot-log:file", + "example", + "--path", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 375 + }, + { + "commandID": "cn:network:vmnet-create", + "methodID": "network.vmnetCreate", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:vmnet-create" + ], + "resource": "network", + "operation": "vmnet-create", + "commandStart": "cn:network:vmnet-create", + "commandShape": "create", + "positionals": [ + { + "name": "network", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--mode" + ], + "type": "network-mode", + "required": false, + "repeatable": false, + "default": "shared" + }, + { + "names": [ + "--subnet" + ], + "type": "cidrv4", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--prefix-v6" + ], + "type": "cidrv6", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:network", + "minimalArgv": [ + "cn:network:vmnet-create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 389 + }, + { + "commandID": "cn:network:subnet", + "methodID": "network.subnet", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:subnet" + ], + "resource": "network", + "operation": "subnet", + "commandStart": "cn:network:subnet", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "cidrv4", + "minimalArgv": [ + "cn:network:subnet", + "@network/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 395 + }, + { + "commandID": "cn:network:prefix-v6", + "methodID": "network.prefixV6", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:prefix-v6" + ], + "resource": "network", + "operation": "prefix-v6", + "commandStart": "cn:network:prefix-v6", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "cidrv6?", + "minimalArgv": [ + "cn:network:prefix-v6", + "@network/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 396 + }, + { + "commandID": "cn:network:ipv4-gateway", + "methodID": "network.ipv4Gateway", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:ipv4-gateway" + ], + "resource": "network", + "operation": "ipv4-gateway", + "commandStart": "cn:network:ipv4-gateway", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "ipv4-address", + "minimalArgv": [ + "cn:network:ipv4-gateway", + "@network/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 397 + }, + { + "commandID": "cn:network:ipv6-gateway", + "methodID": "network.ipv6Gateway", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:ipv6-gateway" + ], + "resource": "network", + "operation": "ipv6-gateway", + "commandStart": "cn:network:ipv6-gateway", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "ipv6-address?", + "minimalArgv": [ + "cn:network:ipv6-gateway", + "@network/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 398 + }, + { + "commandID": "cn:network:create-interface", + "methodID": "network.createInterface", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:create-interface" + ], + "resource": "network", + "operation": "create-interface", + "commandStart": "cn:network:create-interface", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + }, + { + "name": "interface", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:interface?", + "minimalArgv": [ + "cn:network:create-interface", + "@network/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 400 + }, + { + "commandID": "cn:network:create-interface-mtu", + "methodID": "network.createInterfaceMtu", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:create-interface-mtu" + ], + "resource": "network", + "operation": "create-interface-mtu", + "commandStart": "cn:network:create-interface-mtu", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + }, + { + "name": "interface", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "mtu", + "type": "uint32", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:interface?", + "minimalArgv": [ + "cn:network:create-interface-mtu", + "@network/example", + "example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 404 + }, + { + "commandID": "cn:network:create-interface-without-gateway", + "methodID": "network.createInterfaceWithoutGateway", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:create-interface-without-gateway" + ], + "resource": "network", + "operation": "create-interface-without-gateway", + "commandStart": "cn:network:create-interface-without-gateway", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + }, + { + "name": "interface", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:interface?", + "minimalArgv": [ + "cn:network:create-interface-without-gateway", + "@network/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 409 + }, + { + "commandID": "cn:network:release-interface", + "methodID": "network.releaseInterface", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:network:release-interface" + ], + "resource": "network", + "operation": "release-interface", + "commandStart": "cn:network:release-interface", + "commandShape": "reference", + "positionals": [ + { + "name": "network", + "type": "reference:network", + "required": true, + "repeatable": false + }, + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:network:release-interface", + "@network/example", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 413 + }, + { + "commandID": "cn:interface:nat-create", + "methodID": "interface.natCreate", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:nat-create" + ], + "resource": "interface", + "operation": "nat-create", + "commandStart": "cn:interface:nat-create", + "commandShape": "create", + "positionals": [ + { + "name": "interface", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--ipv4-address" + ], + "type": "cidrv4", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--ipv4-gateway" + ], + "type": "ipv4-address", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--ipv6-address" + ], + "type": "cidrv6", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--ipv6-gateway" + ], + "type": "ipv6-address", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--mac-address" + ], + "type": "mac-address", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--mtu" + ], + "type": "uint32", + "required": false, + "repeatable": false, + "default": 1500 + } + ], + "resultType": "reference:interface", + "minimalArgv": [ + "cn:interface:nat-create", + "example", + "--ipv4-address", + "192.0.2.2/24" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 416 + }, + { + "commandID": "cn:interface:ipv4-address", + "methodID": "interface.ipv4Address", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:ipv4-address" + ], + "resource": "interface", + "operation": "ipv4-address", + "commandStart": "cn:interface:ipv4-address", + "commandShape": "reference", + "positionals": [ + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "cidrv4", + "minimalArgv": [ + "cn:interface:ipv4-address", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 425 + }, + { + "commandID": "cn:interface:ipv4-gateway", + "methodID": "interface.ipv4Gateway", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:ipv4-gateway" + ], + "resource": "interface", + "operation": "ipv4-gateway", + "commandStart": "cn:interface:ipv4-gateway", + "commandShape": "reference", + "positionals": [ + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "ipv4-address?", + "minimalArgv": [ + "cn:interface:ipv4-gateway", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 426 + }, + { + "commandID": "cn:interface:ipv6-address", + "methodID": "interface.ipv6Address", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:ipv6-address" + ], + "resource": "interface", + "operation": "ipv6-address", + "commandStart": "cn:interface:ipv6-address", + "commandShape": "reference", + "positionals": [ + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "cidrv6?", + "minimalArgv": [ + "cn:interface:ipv6-address", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 427 + }, + { + "commandID": "cn:interface:ipv6-gateway", + "methodID": "interface.ipv6Gateway", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:ipv6-gateway" + ], + "resource": "interface", + "operation": "ipv6-gateway", + "commandStart": "cn:interface:ipv6-gateway", + "commandShape": "reference", + "positionals": [ + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "ipv6-address?", + "minimalArgv": [ + "cn:interface:ipv6-gateway", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 428 + }, + { + "commandID": "cn:interface:mac-address", + "methodID": "interface.macAddress", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:mac-address" + ], + "resource": "interface", + "operation": "mac-address", + "commandStart": "cn:interface:mac-address", + "commandShape": "reference", + "positionals": [ + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "mac-address?", + "minimalArgv": [ + "cn:interface:mac-address", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 429 + }, + { + "commandID": "cn:interface:mtu", + "methodID": "interface.mtu", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:interface:mtu" + ], + "resource": "interface", + "operation": "mtu", + "commandStart": "cn:interface:mtu", + "commandShape": "reference", + "positionals": [ + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint32", + "minimalArgv": [ + "cn:interface:mtu", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 430 + }, + { + "commandID": "cn:vm-config:create", + "methodID": "vmConfig.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-config:create" + ], + "resource": "vm-config", + "operation": "create", + "commandStart": "cn:vm-config:create", + "commandShape": "create", + "positionals": [ + { + "name": "vm-config", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--cpus" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 4 + }, + { + "names": [ + "--memory" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": 1073741824 + }, + { + "names": [ + "--interface" + ], + "type": "reference:interface", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--mount" + ], + "type": "string=reference:mount", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--boot-log" + ], + "type": "reference:boot-log", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--nested-virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:vm-config", + "minimalArgv": [ + "cn:vm-config:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 439 + }, + { + "commandID": "cn:standard-vm-config:create", + "methodID": "standardVmConfig.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:standard-vm-config:create" + ], + "resource": "standard-vm-config", + "operation": "create", + "commandStart": "cn:standard-vm-config:create", + "commandShape": "create", + "positionals": [ + { + "name": "standard-vm-config", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "vm-config", + "type": "reference:vm-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:standard-vm-config", + "minimalArgv": [ + "cn:standard-vm-config:create", + "example", + "@vm-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 448 + }, + { + "commandID": "cn:vmm:create", + "methodID": "vmm.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vmm:create" + ], + "resource": "vmm", + "operation": "create", + "commandStart": "cn:vmm:create", + "commandShape": "create", + "positionals": [ + { + "name": "vmm", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel" + ], + "type": "reference:kernel", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--initial-filesystem" + ], + "type": "reference:mount", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rosetta" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--nested-virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:vmm", + "minimalArgv": [ + "cn:vmm:create", + "example", + "--kernel", + "@kernel/example", + "--initial-filesystem", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 452 + }, + { + "commandID": "cn:vmm:create-instance", + "methodID": "vmm.createInstance", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vmm:create-instance" + ], + "resource": "vmm", + "operation": "create-instance", + "commandStart": "cn:vmm:create-instance", + "commandShape": "reference", + "positionals": [ + { + "name": "vmm", + "type": "reference:vmm", + "required": true, + "repeatable": false + }, + { + "name": "standard-vm-config", + "type": "reference:standard-vm-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:vm-instance", + "minimalArgv": [ + "cn:vmm:create-instance", + "@vmm/example", + "@standard-vm-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 459 + }, + { + "commandID": "cn:vm-instance:state", + "methodID": "vmInstance.state", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:state" + ], + "resource": "vm-instance", + "operation": "state", + "commandStart": "cn:vm-instance:state", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "vm-state", + "minimalArgv": [ + "cn:vm-instance:state", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 463 + }, + { + "commandID": "cn:vm-instance:mounts", + "methodID": "vmInstance.mounts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:mounts" + ], + "resource": "vm-instance", + "operation": "mounts", + "commandStart": "cn:vm-instance:mounts", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "attached-filesystem-map", + "minimalArgv": [ + "cn:vm-instance:mounts", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 464 + }, + { + "commandID": "cn:vm-instance:virtiofs-layout", + "methodID": "vmInstance.virtiofsLayout", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:virtiofs-layout" + ], + "resource": "vm-instance", + "operation": "virtiofs-layout", + "commandStart": "cn:vm-instance:virtiofs-layout", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "virtiofs-layout", + "minimalArgv": [ + "cn:vm-instance:virtiofs-layout", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 465 + }, + { + "commandID": "cn:vm-instance:start", + "methodID": "vmInstance.start", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:start" + ], + "resource": "vm-instance", + "operation": "start", + "commandStart": "cn:vm-instance:start", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:vm-instance:start", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 466 + }, + { + "commandID": "cn:vm-instance:stop", + "methodID": "vmInstance.stop", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:stop" + ], + "resource": "vm-instance", + "operation": "stop", + "commandStart": "cn:vm-instance:stop", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:vm-instance:stop", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 467 + }, + { + "commandID": "cn:vm-instance:pause", + "methodID": "vmInstance.pause", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:pause" + ], + "resource": "vm-instance", + "operation": "pause", + "commandStart": "cn:vm-instance:pause", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:vm-instance:pause", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 468 + }, + { + "commandID": "cn:vm-instance:resume", + "methodID": "vmInstance.resume", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:resume" + ], + "resource": "vm-instance", + "operation": "resume", + "commandStart": "cn:vm-instance:resume", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:vm-instance:resume", + "@vm-instance/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 469 + }, + { + "commandID": "cn:vm-instance:dial", + "methodID": "vmInstance.dial", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:vm-instance:dial" + ], + "resource": "vm-instance", + "operation": "dial", + "commandStart": "cn:vm-instance:dial", + "commandShape": "reference", + "positionals": [ + { + "name": "vm-instance", + "type": "reference:vm-instance", + "required": true, + "repeatable": false + }, + { + "name": "port", + "type": "uint32", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:file-handle", + "minimalArgv": [ + "cn:vm-instance:dial", + "@vm-instance/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 471 + }, + { + "commandID": "cn:rlimit-kind:create", + "methodID": "rlimitKind.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit-kind:create" + ], + "resource": "rlimit-kind", + "operation": "create", + "commandStart": "cn:rlimit-kind:create", + "commandShape": "create", + "positionals": [ + { + "name": "rlimit-kind", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "oci-name", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:rlimit-kind", + "minimalArgv": [ + "cn:rlimit-kind:create", + "example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 484 + }, + { + "commandID": "cn:rlimit:create", + "methodID": "rlimit.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit:create" + ], + "resource": "rlimit", + "operation": "create", + "commandStart": "cn:rlimit:create", + "commandShape": "create", + "positionals": [ + { + "name": "rlimit", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kind" + ], + "type": "reference:rlimit-kind", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--hard" + ], + "type": "uint64", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--soft" + ], + "type": "uint64", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:rlimit", + "minimalArgv": [ + "cn:rlimit:create", + "example", + "--kind", + "@rlimit-kind/example", + "--hard", + "1", + "--soft", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 488 + }, + { + "commandID": "cn:rlimit:create-equal", + "methodID": "rlimit.createEqual", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit:create-equal" + ], + "resource": "rlimit", + "operation": "create-equal", + "commandStart": "cn:rlimit:create-equal", + "commandShape": "create", + "positionals": [ + { + "name": "rlimit", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kind" + ], + "type": "reference:rlimit-kind", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--limit" + ], + "type": "uint64", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:rlimit", + "minimalArgv": [ + "cn:rlimit:create-equal", + "example", + "--kind", + "@rlimit-kind/example", + "--limit", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 494 + }, + { + "commandID": "cn:rlimit:kind", + "methodID": "rlimit.kind", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit:kind" + ], + "resource": "rlimit", + "operation": "kind", + "commandStart": "cn:rlimit:kind", + "commandShape": "reference", + "positionals": [ + { + "name": "rlimit", + "type": "reference:rlimit", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:rlimit-kind", + "minimalArgv": [ + "cn:rlimit:kind", + "@rlimit/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 499 + }, + { + "commandID": "cn:rlimit:hard", + "methodID": "rlimit.hard", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit:hard" + ], + "resource": "rlimit", + "operation": "hard", + "commandStart": "cn:rlimit:hard", + "commandShape": "reference", + "positionals": [ + { + "name": "rlimit", + "type": "reference:rlimit", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cn:rlimit:hard", + "@rlimit/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 500 + }, + { + "commandID": "cn:rlimit:soft", + "methodID": "rlimit.soft", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit:soft" + ], + "resource": "rlimit", + "operation": "soft", + "commandStart": "cn:rlimit:soft", + "commandShape": "reference", + "positionals": [ + { + "name": "rlimit", + "type": "reference:rlimit", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cn:rlimit:soft", + "@rlimit/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 501 + }, + { + "commandID": "cn:rlimit:to-oci", + "methodID": "rlimit.toOCI", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:rlimit:to-oci" + ], + "resource": "rlimit", + "operation": "to-oci", + "commandStart": "cn:rlimit:to-oci", + "commandShape": "reference", + "positionals": [ + { + "name": "rlimit", + "type": "reference:rlimit", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-posix-rlimit", + "minimalArgv": [ + "cn:rlimit:to-oci", + "@rlimit/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 502 + }, + { + "commandID": "cn:capabilities:create", + "methodID": "capabilities.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:create" + ], + "resource": "capabilities", + "operation": "create", + "commandStart": "cn:capabilities:create", + "commandShape": "create", + "positionals": [ + { + "name": "capabilities", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--bounding" + ], + "type": "linux-capability", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--effective" + ], + "type": "linux-capability", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--inheritable" + ], + "type": "linux-capability", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--permitted" + ], + "type": "linux-capability", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--ambient" + ], + "type": "linux-capability", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:capabilities", + "minimalArgv": [ + "cn:capabilities:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 504 + }, + { + "commandID": "cn:capabilities:create-uniform", + "methodID": "capabilities.createUniform", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:create-uniform" + ], + "resource": "capabilities", + "operation": "create-uniform", + "commandStart": "cn:capabilities:create-uniform", + "commandShape": "create", + "positionals": [ + { + "name": "capabilities", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "capability", + "type": "linux-capability", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "reference:capabilities", + "minimalArgv": [ + "cn:capabilities:create-uniform", + "example", + "CAP_CHOWN" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 512 + }, + { + "commandID": "cn:capabilities:all", + "methodID": "capabilities.all", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:all" + ], + "resource": "capabilities", + "operation": "all", + "commandStart": "cn:capabilities:all", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "reference:capabilities", + "minimalArgv": [ + "cn:capabilities:all" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 516 + }, + { + "commandID": "cn:capabilities:default-oci", + "methodID": "capabilities.defaultOCI", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:default-oci" + ], + "resource": "capabilities", + "operation": "default-oci", + "commandStart": "cn:capabilities:default-oci", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "reference:capabilities", + "minimalArgv": [ + "cn:capabilities:default-oci" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 517 + }, + { + "commandID": "cn:capabilities:bounding", + "methodID": "capabilities.bounding", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:bounding" + ], + "resource": "capabilities", + "operation": "bounding", + "commandStart": "cn:capabilities:bounding", + "commandShape": "reference", + "positionals": [ + { + "name": "capabilities", + "type": "reference:capabilities", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "linux-capability[]", + "minimalArgv": [ + "cn:capabilities:bounding", + "@capabilities/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 518 + }, + { + "commandID": "cn:capabilities:effective", + "methodID": "capabilities.effective", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:effective" + ], + "resource": "capabilities", + "operation": "effective", + "commandStart": "cn:capabilities:effective", + "commandShape": "reference", + "positionals": [ + { + "name": "capabilities", + "type": "reference:capabilities", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "linux-capability[]", + "minimalArgv": [ + "cn:capabilities:effective", + "@capabilities/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 519 + }, + { + "commandID": "cn:capabilities:inheritable", + "methodID": "capabilities.inheritable", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:inheritable" + ], + "resource": "capabilities", + "operation": "inheritable", + "commandStart": "cn:capabilities:inheritable", + "commandShape": "reference", + "positionals": [ + { + "name": "capabilities", + "type": "reference:capabilities", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "linux-capability[]", + "minimalArgv": [ + "cn:capabilities:inheritable", + "@capabilities/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 520 + }, + { + "commandID": "cn:capabilities:permitted", + "methodID": "capabilities.permitted", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:permitted" + ], + "resource": "capabilities", + "operation": "permitted", + "commandStart": "cn:capabilities:permitted", + "commandShape": "reference", + "positionals": [ + { + "name": "capabilities", + "type": "reference:capabilities", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "linux-capability[]", + "minimalArgv": [ + "cn:capabilities:permitted", + "@capabilities/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 521 + }, + { + "commandID": "cn:capabilities:ambient", + "methodID": "capabilities.ambient", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:ambient" + ], + "resource": "capabilities", + "operation": "ambient", + "commandStart": "cn:capabilities:ambient", + "commandShape": "reference", + "positionals": [ + { + "name": "capabilities", + "type": "reference:capabilities", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "linux-capability[]", + "minimalArgv": [ + "cn:capabilities:ambient", + "@capabilities/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 522 + }, + { + "commandID": "cn:capabilities:to-oci", + "methodID": "capabilities.toOCI", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:capabilities:to-oci" + ], + "resource": "capabilities", + "operation": "to-oci", + "commandStart": "cn:capabilities:to-oci", + "commandShape": "reference", + "positionals": [ + { + "name": "capabilities", + "type": "reference:capabilities", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-linux-capabilities", + "minimalArgv": [ + "cn:capabilities:to-oci", + "@capabilities/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 523 + }, + { + "commandID": "cn:process-config:default-path", + "methodID": "processConfig.defaultPath", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:default-path" + ], + "resource": "process-config", + "operation": "default-path", + "commandStart": "cn:process-config:default-path", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:process-config:default-path" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 525 + }, + { + "commandID": "cn:process-config:create", + "methodID": "processConfig.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:create" + ], + "resource": "process-config", + "operation": "create", + "commandStart": "cn:process-config:create", + "commandShape": "create", + "positionals": [ + { + "name": "process-config", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "argument", + "type": "string", + "required": true, + "repeatable": true + } + ], + "options": [ + { + "names": [ + "--environment" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--working-directory" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": "/" + }, + { + "names": [ + "--user" + ], + "type": "oci-user", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rlimit" + ], + "type": "reference:rlimit", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--no-new-privileges" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--capabilities" + ], + "type": "reference:capabilities", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--terminal" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--stdin" + ], + "type": "reference:reader-stream", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--stdout" + ], + "type": "reference:writer", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--stderr" + ], + "type": "reference:writer", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:process-config", + "minimalArgv": [ + "cn:process-config:create", + "example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 527 + }, + { + "commandID": "cn:process-config:from-image-config", + "methodID": "processConfig.fromImageConfig", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:from-image-config" + ], + "resource": "process-config", + "operation": "from-image-config", + "commandStart": "cn:process-config:from-image-config", + "commandShape": "create", + "positionals": [ + { + "name": "process-config", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "image-config", + "type": "oci-image-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:process-config", + "minimalArgv": [ + "cn:process-config:from-image-config", + "example", + "{}" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 541 + }, + { + "commandID": "cn:process-config:set-terminal-io", + "methodID": "processConfig.setTerminalIo", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:set-terminal-io" + ], + "resource": "process-config", + "operation": "set-terminal-io", + "commandStart": "cn:process-config:set-terminal-io", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + }, + { + "name": "terminal", + "type": "reference:terminal", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:process-config:set-terminal-io", + "@process-config/example", + "@terminal/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 545 + }, + { + "commandID": "cn:process-config:arguments", + "methodID": "processConfig.arguments", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:arguments" + ], + "resource": "process-config", + "operation": "arguments", + "commandStart": "cn:process-config:arguments", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:process-config:arguments", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 548 + }, + { + "commandID": "cn:process-config:environment-variables", + "methodID": "processConfig.environmentVariables", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:environment-variables" + ], + "resource": "process-config", + "operation": "environment-variables", + "commandStart": "cn:process-config:environment-variables", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string[]", + "minimalArgv": [ + "cn:process-config:environment-variables", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 549 + }, + { + "commandID": "cn:process-config:working-directory", + "methodID": "processConfig.workingDirectory", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:working-directory" + ], + "resource": "process-config", + "operation": "working-directory", + "commandStart": "cn:process-config:working-directory", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:process-config:working-directory", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 550 + }, + { + "commandID": "cn:process-config:user", + "methodID": "processConfig.user", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:user" + ], + "resource": "process-config", + "operation": "user", + "commandStart": "cn:process-config:user", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-user", + "minimalArgv": [ + "cn:process-config:user", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 551 + }, + { + "commandID": "cn:process-config:rlimits", + "methodID": "processConfig.rlimits", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:rlimits" + ], + "resource": "process-config", + "operation": "rlimits", + "commandStart": "cn:process-config:rlimits", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:rlimit[]", + "minimalArgv": [ + "cn:process-config:rlimits", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 552 + }, + { + "commandID": "cn:process-config:no-new-privileges", + "methodID": "processConfig.noNewPrivileges", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:no-new-privileges" + ], + "resource": "process-config", + "operation": "no-new-privileges", + "commandStart": "cn:process-config:no-new-privileges", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "bool", + "minimalArgv": [ + "cn:process-config:no-new-privileges", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 553 + }, + { + "commandID": "cn:process-config:capabilities", + "methodID": "processConfig.capabilities", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:capabilities" + ], + "resource": "process-config", + "operation": "capabilities", + "commandStart": "cn:process-config:capabilities", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:capabilities", + "minimalArgv": [ + "cn:process-config:capabilities", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 554 + }, + { + "commandID": "cn:process-config:terminal", + "methodID": "processConfig.terminal", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:terminal" + ], + "resource": "process-config", + "operation": "terminal", + "commandStart": "cn:process-config:terminal", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "bool", + "minimalArgv": [ + "cn:process-config:terminal", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 555 + }, + { + "commandID": "cn:process-config:stdin", + "methodID": "processConfig.stdin", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:stdin" + ], + "resource": "process-config", + "operation": "stdin", + "commandStart": "cn:process-config:stdin", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:reader-stream?", + "minimalArgv": [ + "cn:process-config:stdin", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 556 + }, + { + "commandID": "cn:process-config:stdout", + "methodID": "processConfig.stdout", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:stdout" + ], + "resource": "process-config", + "operation": "stdout", + "commandStart": "cn:process-config:stdout", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:writer?", + "minimalArgv": [ + "cn:process-config:stdout", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 557 + }, + { + "commandID": "cn:process-config:stderr", + "methodID": "processConfig.stderr", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process-config:stderr" + ], + "resource": "process-config", + "operation": "stderr", + "commandStart": "cn:process-config:stderr", + "commandShape": "reference", + "positionals": [ + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:writer?", + "minimalArgv": [ + "cn:process-config:stderr", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 558 + }, + { + "commandID": "cn:container-config:create-default", + "methodID": "containerConfig.createDefault", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container-config:create-default" + ], + "resource": "container-config", + "operation": "create-default", + "commandStart": "cn:container-config:create-default", + "commandShape": "create", + "positionals": [ + { + "name": "container-config", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:container-config", + "minimalArgv": [ + "cn:container-config:create-default", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 567 + }, + { + "commandID": "cn:container-config:create", + "methodID": "containerConfig.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container-config:create" + ], + "resource": "container-config", + "operation": "create", + "commandStart": "cn:container-config:create", + "commandShape": "create", + "positionals": [ + { + "name": "container-config", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--process" + ], + "type": "reference:process-config", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--cpus" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 4 + }, + { + "names": [ + "--memory" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": 1073741824 + }, + { + "names": [ + "--hostname" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--sysctl" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--interface" + ], + "type": "reference:interface", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--socket" + ], + "type": "reference:socket", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--mount" + ], + "type": "reference:mount", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--masked-path" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--readonly-path" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--dns" + ], + "type": "reference:dns", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--hosts" + ], + "type": "reference:hosts", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--boot-log" + ], + "type": "reference:boot-log", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--oci-runtime-path" + ], + "type": "container-path", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--use-init" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--cpu-overhead" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 1 + }, + { + "names": [ + "--memory-overhead" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": 134217728 + } + ], + "resultType": "reference:container-config", + "minimalArgv": [ + "cn:container-config:create", + "example", + "--process", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 570 + }, + { + "commandID": "cn:container:default-mounts", + "methodID": "container.defaultMounts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:default-mounts" + ], + "resource": "container", + "operation": "default-mounts", + "commandStart": "cn:container:default-mounts", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "reference:mount[]", + "minimalArgv": [ + "cn:container:default-mounts" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 591 + }, + { + "commandID": "cn:container:default-oci-mounts", + "methodID": "container.defaultOCIMounts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:default-oci-mounts" + ], + "resource": "container", + "operation": "default-oci-mounts", + "commandStart": "cn:container:default-oci-mounts", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "oci-mount[]", + "minimalArgv": [ + "cn:container:default-oci-mounts" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 592 + }, + { + "commandID": "cn:container:default-masked-paths", + "methodID": "container.defaultMaskedPaths", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:default-masked-paths" + ], + "resource": "container", + "operation": "default-masked-paths", + "commandStart": "cn:container:default-masked-paths", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "container-path[]", + "minimalArgv": [ + "cn:container:default-masked-paths" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 593 + }, + { + "commandID": "cn:container:default-readonly-paths", + "methodID": "container.defaultReadonlyPaths", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:default-readonly-paths" + ], + "resource": "container", + "operation": "default-readonly-paths", + "commandStart": "cn:container:default-readonly-paths", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "container-path[]", + "minimalArgv": [ + "cn:container:default-readonly-paths" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 594 + }, + { + "commandID": "cn:container:default-copy-chunk-size", + "methodID": "container.defaultCopyChunkSize", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:default-copy-chunk-size" + ], + "resource": "container", + "operation": "default-copy-chunk-size", + "commandStart": "cn:container:default-copy-chunk-size", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "int", + "minimalArgv": [ + "cn:container:default-copy-chunk-size" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 595 + }, + { + "commandID": "cn:container:max-id-length", + "methodID": "container.maxIDLength", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:max-id-length" + ], + "resource": "container", + "operation": "max-id-length", + "commandStart": "cn:container:max-id-length", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "int", + "minimalArgv": [ + "cn:container:max-id-length" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 596 + }, + { + "commandID": "cn:manager:create", + "methodID": "manager.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create" + ], + "resource": "manager", + "operation": "create", + "commandStart": "cn:manager:create", + "commandShape": "create", + "positionals": [ + { + "name": "manager", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel" + ], + "type": "reference:kernel", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--initfs" + ], + "type": "reference:mount", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--image-store" + ], + "type": "reference:image-store", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--network" + ], + "type": "reference:network", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rosetta" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--nested-virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:manager", + "minimalArgv": [ + "cn:manager:create", + "example", + "--kernel", + "@kernel/example", + "--initfs", + "@mount/example", + "--image-store", + "@image-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 605 + }, + { + "commandID": "cn:manager:create-at-root", + "methodID": "manager.createAtRoot", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-at-root" + ], + "resource": "manager", + "operation": "create-at-root", + "commandStart": "cn:manager:create-at-root", + "commandShape": "create", + "positionals": [ + { + "name": "manager", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel" + ], + "type": "reference:kernel", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--initfs" + ], + "type": "reference:mount", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--root" + ], + "type": "host-url", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--network" + ], + "type": "reference:network", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rosetta" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--nested-virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:manager", + "minimalArgv": [ + "cn:manager:create-at-root", + "example", + "--kernel", + "@kernel/example", + "--initfs", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 614 + }, + { + "commandID": "cn:manager:create-from-reference", + "methodID": "manager.createFromReference", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-from-reference" + ], + "resource": "manager", + "operation": "create-from-reference", + "commandStart": "cn:manager:create-from-reference", + "commandShape": "create", + "positionals": [ + { + "name": "manager", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel" + ], + "type": "reference:kernel", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--initfs-reference" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--image-store" + ], + "type": "reference:image-store", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--network" + ], + "type": "reference:network", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rosetta" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--nested-virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:manager", + "minimalArgv": [ + "cn:manager:create-from-reference", + "example", + "--kernel", + "@kernel/example", + "--initfs-reference", + "example", + "--image-store", + "@image-store/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 623 + }, + { + "commandID": "cn:manager:create-from-reference-at-root", + "methodID": "manager.createFromReferenceAtRoot", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-from-reference-at-root" + ], + "resource": "manager", + "operation": "create-from-reference-at-root", + "commandStart": "cn:manager:create-from-reference-at-root", + "commandShape": "create", + "positionals": [ + { + "name": "manager", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--kernel" + ], + "type": "reference:kernel", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--initfs-reference" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--root" + ], + "type": "host-url", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--network" + ], + "type": "reference:network", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rosetta" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--nested-virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:manager", + "minimalArgv": [ + "cn:manager:create-from-reference-at-root", + "example", + "--kernel", + "@kernel/example", + "--initfs-reference", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 632 + }, + { + "commandID": "cn:manager:create-with-vmm", + "methodID": "manager.createWithVMM", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-with-vmm" + ], + "resource": "manager", + "operation": "create-with-vmm", + "commandStart": "cn:manager:create-with-vmm", + "commandShape": "create", + "positionals": [ + { + "name": "manager", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--vmm" + ], + "type": "reference:vmm", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--network" + ], + "type": "reference:network", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:manager", + "minimalArgv": [ + "cn:manager:create-with-vmm", + "example", + "--vmm", + "@vmm/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 641 + }, + { + "commandID": "cn:manager:image-store", + "methodID": "manager.imageStore", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:image-store" + ], + "resource": "manager", + "operation": "image-store", + "commandStart": "cn:manager:image-store", + "commandShape": "reference", + "positionals": [ + { + "name": "manager", + "type": "reference:manager", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:image-store", + "minimalArgv": [ + "cn:manager:image-store", + "@manager/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 646 + }, + { + "commandID": "cn:manager:create-container", + "methodID": "manager.createContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-container" + ], + "resource": "manager", + "operation": "create-container", + "commandStart": "cn:manager:create-container", + "commandShape": "reference", + "positionals": [ + { + "name": "manager", + "type": "reference:manager", + "required": true, + "repeatable": false + }, + { + "name": "container", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--reference" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rootfs-size" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": 8589934592 + }, + { + "names": [ + "--writable-layer-size" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--read-only" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--networking" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": true + }, + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--process" + ], + "type": "reference:process-config", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpus" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hostname" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sysctl" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--interfaces" + ], + "type": "reference:interface", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sockets" + ], + "type": "reference:socket", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--mounts" + ], + "type": "reference:mount", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--masked-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--readonly-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--dns" + ], + "type": "reference:dns", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hosts" + ], + "type": "reference:hosts", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--boot-log" + ], + "type": "reference:boot-log", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--oci-runtime-path" + ], + "type": "container-path", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--use-init" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpu-overhead" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory-overhead" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + } + ], + "resultType": "reference:container", + "minimalArgv": [ + "cn:manager:create-container", + "@manager/example", + "example", + "--reference", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 679, + "optionGroups": [ + "containerConfigOverride" + ] + }, + { + "commandID": "cn:manager:create-container-from-image", + "methodID": "manager.createContainerFromImage", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-container-from-image" + ], + "resource": "manager", + "operation": "create-container-from-image", + "commandStart": "cn:manager:create-container-from-image", + "commandShape": "reference", + "positionals": [ + { + "name": "manager", + "type": "reference:manager", + "required": true, + "repeatable": false + }, + { + "name": "container", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--image" + ], + "type": "reference:image", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rootfs-size" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": 8589934592 + }, + { + "names": [ + "--writable-layer-size" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--read-only" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + }, + { + "names": [ + "--networking" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": true + }, + { + "names": [ + "--progress" + ], + "type": "reference:progress-handler", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--process" + ], + "type": "reference:process-config", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpus" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hostname" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sysctl" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--interfaces" + ], + "type": "reference:interface", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sockets" + ], + "type": "reference:socket", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--mounts" + ], + "type": "reference:mount", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--masked-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--readonly-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--dns" + ], + "type": "reference:dns", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hosts" + ], + "type": "reference:hosts", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--boot-log" + ], + "type": "reference:boot-log", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--oci-runtime-path" + ], + "type": "container-path", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--use-init" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpu-overhead" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory-overhead" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + } + ], + "resultType": "reference:container", + "minimalArgv": [ + "cn:manager:create-container-from-image", + "@manager/example", + "example", + "--image", + "@image/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 690, + "optionGroups": [ + "containerConfigOverride" + ] + }, + { + "commandID": "cn:manager:create-container-from-mounts", + "methodID": "manager.createContainerFromMounts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:create-container-from-mounts" + ], + "resource": "manager", + "operation": "create-container-from-mounts", + "commandStart": "cn:manager:create-container-from-mounts", + "commandShape": "reference", + "positionals": [ + { + "name": "manager", + "type": "reference:manager", + "required": true, + "repeatable": false + }, + { + "name": "container", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--image" + ], + "type": "reference:image", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--rootfs" + ], + "type": "reference:mount", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--writable-layer" + ], + "type": "reference:mount", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--networking" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": true + }, + { + "names": [ + "--process" + ], + "type": "reference:process-config", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpus" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hostname" + ], + "type": "string", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sysctl" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--interfaces" + ], + "type": "reference:interface", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--sockets" + ], + "type": "reference:socket", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--mounts" + ], + "type": "reference:mount", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--masked-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--readonly-paths" + ], + "type": "container-path", + "required": false, + "repeatable": true, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--dns" + ], + "type": "reference:dns", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--hosts" + ], + "type": "reference:hosts", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--virtualization" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--boot-log" + ], + "type": "reference:boot-log", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--oci-runtime-path" + ], + "type": "container-path", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--use-init" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--cpu-overhead" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + }, + { + "names": [ + "--memory-overhead" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": null, + "group": "containerConfigOverride" + } + ], + "resultType": "reference:container", + "minimalArgv": [ + "cn:manager:create-container-from-mounts", + "@manager/example", + "example", + "--image", + "@image/example", + "--rootfs", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 701, + "optionGroups": [ + "containerConfigOverride" + ] + }, + { + "commandID": "cn:manager:release-network", + "methodID": "manager.releaseNetwork", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:release-network" + ], + "resource": "manager", + "operation": "release-network", + "commandStart": "cn:manager:release-network", + "commandShape": "reference", + "positionals": [ + { + "name": "manager", + "type": "reference:manager", + "required": true, + "repeatable": false + }, + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:manager:release-network", + "@manager/example", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 710 + }, + { + "commandID": "cn:manager:delete", + "methodID": "manager.delete", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:manager:delete" + ], + "resource": "manager", + "operation": "delete", + "commandStart": "cn:manager:delete", + "commandShape": "reference", + "positionals": [ + { + "name": "manager", + "type": "reference:manager", + "required": true, + "repeatable": false + }, + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:manager:delete", + "@manager/example", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 711 + }, + { + "commandID": "cn:container:create-direct", + "methodID": "container.createDirect", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:create-direct" + ], + "resource": "container", + "operation": "create-direct", + "commandStart": "cn:container:create-direct", + "commandShape": "create", + "positionals": [ + { + "name": "container", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--rootfs" + ], + "type": "reference:mount", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--writable-layer" + ], + "type": "reference:mount", + "required": false, + "repeatable": false, + "default": null + }, + { + "names": [ + "--vmm" + ], + "type": "reference:vmm", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--configuration" + ], + "type": "reference:container-config", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:container", + "minimalArgv": [ + "cn:container:create-direct", + "example", + "--rootfs", + "@mount/example", + "--vmm", + "@vmm/example", + "--configuration", + "@container-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 717 + }, + { + "commandID": "cn:container:id", + "methodID": "container.id", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:id" + ], + "resource": "container", + "operation": "id", + "commandStart": "cn:container:id", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:container:id", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 724 + }, + { + "commandID": "cn:container:rootfs", + "methodID": "container.rootfs", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:rootfs" + ], + "resource": "container", + "operation": "rootfs", + "commandStart": "cn:container:rootfs", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:mount", + "minimalArgv": [ + "cn:container:rootfs", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 725 + }, + { + "commandID": "cn:container:writable-layer", + "methodID": "container.writableLayer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:writable-layer" + ], + "resource": "container", + "operation": "writable-layer", + "commandStart": "cn:container:writable-layer", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:mount?", + "minimalArgv": [ + "cn:container:writable-layer", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 726 + }, + { + "commandID": "cn:container:config", + "methodID": "container.config", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:config" + ], + "resource": "container", + "operation": "config", + "commandStart": "cn:container:config", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:container-config", + "minimalArgv": [ + "cn:container:config", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 727 + }, + { + "commandID": "cn:container:cpus", + "methodID": "container.cpus", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:cpus" + ], + "resource": "container", + "operation": "cpus", + "commandStart": "cn:container:cpus", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "int", + "minimalArgv": [ + "cn:container:cpus", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 728 + }, + { + "commandID": "cn:container:memory", + "methodID": "container.memory", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:memory" + ], + "resource": "container", + "operation": "memory", + "commandStart": "cn:container:memory", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cn:container:memory", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 729 + }, + { + "commandID": "cn:container:interfaces", + "methodID": "container.interfaces", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:interfaces" + ], + "resource": "container", + "operation": "interfaces", + "commandStart": "cn:container:interfaces", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:interface[]", + "minimalArgv": [ + "cn:container:interfaces", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 730 + }, + { + "commandID": "cn:container:create", + "methodID": "container.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:create" + ], + "resource": "container", + "operation": "create", + "commandStart": "cn:container:create", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:create", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 732 + }, + { + "commandID": "cn:container:start", + "methodID": "container.start", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:start" + ], + "resource": "container", + "operation": "start", + "commandStart": "cn:container:start", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:start", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 733 + }, + { + "commandID": "cn:container:stop", + "methodID": "container.stop", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:stop" + ], + "resource": "container", + "operation": "stop", + "commandStart": "cn:container:stop", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:stop", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 734 + }, + { + "commandID": "cn:container:kill", + "methodID": "container.kill", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:kill" + ], + "resource": "container", + "operation": "kill", + "commandStart": "cn:container:kill", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "signal", + "type": "linux-signal", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:kill", + "@container/example", + "SIGTERM" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 735 + }, + { + "commandID": "cn:container:wait", + "methodID": "container.wait", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:wait" + ], + "resource": "container", + "operation": "wait", + "commandStart": "cn:container:wait", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--timeout-seconds" + ], + "type": "int64", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "exit-status", + "minimalArgv": [ + "cn:container:wait", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 737 + }, + { + "commandID": "cn:container:resize", + "methodID": "container.resize", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:resize" + ], + "resource": "container", + "operation": "resize", + "commandStart": "cn:container:resize", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "width", + "type": "uint16", + "required": true, + "repeatable": false + }, + { + "name": "height", + "type": "uint16", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:resize", + "@container/example", + "1", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 741 + }, + { + "commandID": "cn:container:exec", + "methodID": "container.exec", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:exec" + ], + "resource": "container", + "operation": "exec", + "commandStart": "cn:container:exec", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "process", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--configuration" + ], + "type": "reference:process-config", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:process", + "minimalArgv": [ + "cn:container:exec", + "@container/example", + "example", + "--configuration", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 745 + }, + { + "commandID": "cn:container:dial-vsock", + "methodID": "container.dialVsock", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:dial-vsock" + ], + "resource": "container", + "operation": "dial-vsock", + "commandStart": "cn:container:dial-vsock", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "port", + "type": "uint32", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:file-handle", + "minimalArgv": [ + "cn:container:dial-vsock", + "@container/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 750 + }, + { + "commandID": "cn:container:close-stdin", + "methodID": "container.closeStdin", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:close-stdin" + ], + "resource": "container", + "operation": "close-stdin", + "commandStart": "cn:container:close-stdin", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:close-stdin", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 754 + }, + { + "commandID": "cn:container:statistics", + "methodID": "container.statistics", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:statistics" + ], + "resource": "container", + "operation": "statistics", + "commandStart": "cn:container:statistics", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--category" + ], + "type": "statistics-category", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "container-statistics", + "minimalArgv": [ + "cn:container:statistics", + "@container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 756 + }, + { + "commandID": "cn:container:filesystem-operation", + "methodID": "container.filesystemOperation", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:filesystem-operation" + ], + "resource": "container", + "operation": "filesystem-operation", + "commandStart": "cn:container:filesystem-operation", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "operation", + "type": "freeze|thaw|trim", + "required": true, + "repeatable": false + }, + { + "name": "path", + "type": "container-path", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:container:filesystem-operation", + "@container/example", + "freeze", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 760 + }, + { + "commandID": "cn:container:copy-in", + "methodID": "container.copyIn", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:copy-in" + ], + "resource": "container", + "operation": "copy-in", + "commandStart": "cn:container:copy-in", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "source", + "type": "host-url", + "required": true, + "repeatable": false + }, + { + "name": "destination", + "type": "container-url", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--mode" + ], + "type": "file-permissions", + "required": false, + "repeatable": false, + "default": "0644" + }, + { + "names": [ + "--create-parents" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": true + }, + { + "names": [ + "--chunk-size" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 1048576 + } + ], + "resultType": "void", + "minimalArgv": [ + "cn:container:copy-in", + "@container/example", + "/tmp/example", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 764 + }, + { + "commandID": "cn:container:copy-out", + "methodID": "container.copyOut", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:container:copy-out" + ], + "resource": "container", + "operation": "copy-out", + "commandStart": "cn:container:copy-out", + "commandShape": "reference", + "positionals": [ + { + "name": "container", + "type": "reference:container", + "required": true, + "repeatable": false + }, + { + "name": "source", + "type": "container-url", + "required": true, + "repeatable": false + }, + { + "name": "destination", + "type": "host-url", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--create-parents" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": true + }, + { + "names": [ + "--chunk-size" + ], + "type": "int", + "required": false, + "repeatable": false, + "default": 1048576 + } + ], + "resultType": "void", + "minimalArgv": [ + "cn:container:copy-out", + "@container/example", + "/example", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 771 + }, + { + "commandID": "cn:process:id", + "methodID": "process.id", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:id" + ], + "resource": "process", + "operation": "id", + "commandStart": "cn:process:id", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:process:id", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 790 + }, + { + "commandID": "cn:process:owning-container", + "methodID": "process.owningContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:owning-container" + ], + "resource": "process", + "operation": "owning-container", + "commandStart": "cn:process:owning-container", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string?", + "minimalArgv": [ + "cn:process:owning-container", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 791 + }, + { + "commandID": "cn:process:pid", + "methodID": "process.pid", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:pid" + ], + "resource": "process", + "operation": "pid", + "commandStart": "cn:process:pid", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "int32", + "minimalArgv": [ + "cn:process:pid", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 792 + }, + { + "commandID": "cn:process:start", + "methodID": "process.start", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:start" + ], + "resource": "process", + "operation": "start", + "commandStart": "cn:process:start", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:process:start", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 794 + }, + { + "commandID": "cn:process:kill", + "methodID": "process.kill", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:kill" + ], + "resource": "process", + "operation": "kill", + "commandStart": "cn:process:kill", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + }, + { + "name": "signal", + "type": "linux-signal", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:process:kill", + "@process/example", + "SIGTERM" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 795 + }, + { + "commandID": "cn:process:resize", + "methodID": "process.resize", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:resize" + ], + "resource": "process", + "operation": "resize", + "commandStart": "cn:process:resize", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + }, + { + "name": "width", + "type": "uint16", + "required": true, + "repeatable": false + }, + { + "name": "height", + "type": "uint16", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:process:resize", + "@process/example", + "1", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 797 + }, + { + "commandID": "cn:process:close-stdin", + "methodID": "process.closeStdin", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:close-stdin" + ], + "resource": "process", + "operation": "close-stdin", + "commandStart": "cn:process:close-stdin", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:process:close-stdin", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 801 + }, + { + "commandID": "cn:process:wait", + "methodID": "process.wait", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:wait" + ], + "resource": "process", + "operation": "wait", + "commandStart": "cn:process:wait", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--timeout-seconds" + ], + "type": "int64", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "exit-status", + "minimalArgv": [ + "cn:process:wait", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 803 + }, + { + "commandID": "cn:process:delete", + "methodID": "process.delete", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:process:delete" + ], + "resource": "process", + "operation": "delete", + "commandStart": "cn:process:delete", + "commandShape": "reference", + "positionals": [ + { + "name": "process", + "type": "reference:process", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:process:delete", + "@process/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 807 + }, + { + "commandID": "cn:pod-volume:create", + "methodID": "podVolume.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-volume:create" + ], + "resource": "pod-volume", + "operation": "create", + "commandStart": "cn:pod-volume:create", + "commandShape": "create", + "positionals": [ + { + "name": "pod-volume", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--name" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--source" + ], + "type": "pod-volume-source", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--format" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:pod-volume", + "minimalArgv": [ + "cn:pod-volume:create", + "example", + "--name", + "example", + "--source", + "{}", + "--format", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 818 + }, + { + "commandID": "cn:pod-config:create", + "methodID": "podConfig.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:create" + ], + "resource": "pod-config", + "operation": "create", + "commandStart": "cn:pod-config:create", + "commandShape": "create", + "positionals": [ + { + "name": "pod-config", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:pod-config", + "minimalArgv": [ + "cn:pod-config:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 824 + }, + { + "commandID": "cn:pod-config:set-cpus", + "methodID": "podConfig.setCPUs", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-cpus" + ], + "resource": "pod-config", + "operation": "set-cpus", + "commandStart": "cn:pod-config:set-cpus", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "cpus", + "type": "int", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-cpus", + "@pod-config/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 825 + }, + { + "commandID": "cn:pod-config:set-memory", + "methodID": "podConfig.setMemory", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-memory" + ], + "resource": "pod-config", + "operation": "set-memory", + "commandStart": "cn:pod-config:set-memory", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "bytes", + "type": "uint64", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-memory", + "@pod-config/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 826 + }, + { + "commandID": "cn:pod-config:set-interfaces", + "methodID": "podConfig.setInterfaces", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-interfaces" + ], + "resource": "pod-config", + "operation": "set-interfaces", + "commandStart": "cn:pod-config:set-interfaces", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "interface", + "type": "reference:interface", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-interfaces", + "@pod-config/example", + "@interface/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 827 + }, + { + "commandID": "cn:pod-config:set-virtualization", + "methodID": "podConfig.setVirtualization", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-virtualization" + ], + "resource": "pod-config", + "operation": "set-virtualization", + "commandStart": "cn:pod-config:set-virtualization", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "enabled", + "type": "bool", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-virtualization", + "@pod-config/example", + "true" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 828 + }, + { + "commandID": "cn:pod-config:set-boot-log", + "methodID": "podConfig.setBootLog", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-boot-log" + ], + "resource": "pod-config", + "operation": "set-boot-log", + "commandStart": "cn:pod-config:set-boot-log", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "boot-log", + "type": "reference:boot-log?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-boot-log", + "@pod-config/example", + "@boot-log/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 829 + }, + { + "commandID": "cn:pod-config:set-share-process-namespace", + "methodID": "podConfig.setShareProcessNamespace", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-share-process-namespace" + ], + "resource": "pod-config", + "operation": "set-share-process-namespace", + "commandStart": "cn:pod-config:set-share-process-namespace", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "enabled", + "type": "bool", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-share-process-namespace", + "@pod-config/example", + "true" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 830 + }, + { + "commandID": "cn:pod-config:set-hostname", + "methodID": "podConfig.setHostname", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-hostname" + ], + "resource": "pod-config", + "operation": "set-hostname", + "commandStart": "cn:pod-config:set-hostname", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "hostname", + "type": "string?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-hostname", + "@pod-config/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 831 + }, + { + "commandID": "cn:pod-config:set-dns", + "methodID": "podConfig.setDNS", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-dns" + ], + "resource": "pod-config", + "operation": "set-dns", + "commandStart": "cn:pod-config:set-dns", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "dns", + "type": "reference:dns?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-dns", + "@pod-config/example", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 832 + }, + { + "commandID": "cn:pod-config:set-hosts", + "methodID": "podConfig.setHosts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-hosts" + ], + "resource": "pod-config", + "operation": "set-hosts", + "commandStart": "cn:pod-config:set-hosts", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "hosts", + "type": "reference:hosts?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-hosts", + "@pod-config/example", + "@hosts/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 833 + }, + { + "commandID": "cn:pod-config:set-volumes", + "methodID": "podConfig.setVolumes", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-config:set-volumes" + ], + "resource": "pod-config", + "operation": "set-volumes", + "commandStart": "cn:pod-config:set-volumes", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-config", + "type": "reference:pod-config", + "required": true, + "repeatable": false + }, + { + "name": "pod-volume", + "type": "reference:pod-volume", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-config:set-volumes", + "@pod-config/example", + "@pod-volume/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 834 + }, + { + "commandID": "cn:pod-container-config:create", + "methodID": "podContainerConfig.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:create" + ], + "resource": "pod-container-config", + "operation": "create", + "commandStart": "cn:pod-container-config:create", + "commandShape": "create", + "positionals": [ + { + "name": "pod-container-config", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:pod-container-config", + "minimalArgv": [ + "cn:pod-container-config:create", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 836 + }, + { + "commandID": "cn:pod-container-config:set-process", + "methodID": "podContainerConfig.setProcess", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-process" + ], + "resource": "pod-container-config", + "operation": "set-process", + "commandStart": "cn:pod-container-config:set-process", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "process-config", + "type": "reference:process-config", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-process", + "@pod-container-config/example", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 837 + }, + { + "commandID": "cn:pod-container-config:set-cpus", + "methodID": "podContainerConfig.setCPUs", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-cpus" + ], + "resource": "pod-container-config", + "operation": "set-cpus", + "commandStart": "cn:pod-container-config:set-cpus", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "cpus", + "type": "int?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-cpus", + "@pod-container-config/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 838 + }, + { + "commandID": "cn:pod-container-config:set-memory", + "methodID": "podContainerConfig.setMemory", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-memory" + ], + "resource": "pod-container-config", + "operation": "set-memory", + "commandStart": "cn:pod-container-config:set-memory", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "bytes", + "type": "uint64?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-memory", + "@pod-container-config/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 839 + }, + { + "commandID": "cn:pod-container-config:set-hostname", + "methodID": "podContainerConfig.setHostname", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-hostname" + ], + "resource": "pod-container-config", + "operation": "set-hostname", + "commandStart": "cn:pod-container-config:set-hostname", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "hostname", + "type": "string?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-hostname", + "@pod-container-config/example", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 840 + }, + { + "commandID": "cn:pod-container-config:set-sysctl", + "methodID": "podContainerConfig.setSysctl", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-sysctl" + ], + "resource": "pod-container-config", + "operation": "set-sysctl", + "commandStart": "cn:pod-container-config:set-sysctl", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "key-value", + "type": "string", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-sysctl", + "@pod-container-config/example", + "key=value" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 841 + }, + { + "commandID": "cn:pod-container-config:set-mounts", + "methodID": "podContainerConfig.setMounts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-mounts" + ], + "resource": "pod-container-config", + "operation": "set-mounts", + "commandStart": "cn:pod-container-config:set-mounts", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "mount", + "type": "reference:mount", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-mounts", + "@pod-container-config/example", + "@mount/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 842 + }, + { + "commandID": "cn:pod-container-config:set-masked-paths", + "methodID": "podContainerConfig.setMaskedPaths", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-masked-paths" + ], + "resource": "pod-container-config", + "operation": "set-masked-paths", + "commandStart": "cn:pod-container-config:set-masked-paths", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "path", + "type": "container-path", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-masked-paths", + "@pod-container-config/example", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 843 + }, + { + "commandID": "cn:pod-container-config:set-readonly-paths", + "methodID": "podContainerConfig.setReadonlyPaths", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-readonly-paths" + ], + "resource": "pod-container-config", + "operation": "set-readonly-paths", + "commandStart": "cn:pod-container-config:set-readonly-paths", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "path", + "type": "container-path", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-readonly-paths", + "@pod-container-config/example", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 844 + }, + { + "commandID": "cn:pod-container-config:set-sockets", + "methodID": "podContainerConfig.setSockets", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-sockets" + ], + "resource": "pod-container-config", + "operation": "set-sockets", + "commandStart": "cn:pod-container-config:set-sockets", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-sockets", + "@pod-container-config/example", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 845 + }, + { + "commandID": "cn:pod-container-config:set-dns", + "methodID": "podContainerConfig.setDNS", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-dns" + ], + "resource": "pod-container-config", + "operation": "set-dns", + "commandStart": "cn:pod-container-config:set-dns", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "dns", + "type": "reference:dns?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-dns", + "@pod-container-config/example", + "@dns/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 846 + }, + { + "commandID": "cn:pod-container-config:set-hosts", + "methodID": "podContainerConfig.setHosts", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-hosts" + ], + "resource": "pod-container-config", + "operation": "set-hosts", + "commandStart": "cn:pod-container-config:set-hosts", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "hosts", + "type": "reference:hosts?", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-hosts", + "@pod-container-config/example", + "@hosts/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 847 + }, + { + "commandID": "cn:pod-container-config:set-use-init", + "methodID": "podContainerConfig.setUseInit", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod-container-config:set-use-init" + ], + "resource": "pod-container-config", + "operation": "set-use-init", + "commandStart": "cn:pod-container-config:set-use-init", + "commandShape": "reference", + "positionals": [ + { + "name": "pod-container-config", + "type": "reference:pod-container-config", + "required": true, + "repeatable": false + }, + { + "name": "enabled", + "type": "bool", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod-container-config:set-use-init", + "@pod-container-config/example", + "true" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 848 + }, + { + "commandID": "cn:pod:create-direct", + "methodID": "pod.createDirect", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:create-direct" + ], + "resource": "pod", + "operation": "create-direct", + "commandStart": "cn:pod:create-direct", + "commandShape": "create", + "positionals": [ + { + "name": "pod", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--vmm" + ], + "type": "reference:vmm", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--configuration" + ], + "type": "reference:pod-config", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:pod", + "minimalArgv": [ + "cn:pod:create-direct", + "example", + "--vmm", + "@vmm/example", + "--configuration", + "@pod-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 850 + }, + { + "commandID": "cn:pod:id", + "methodID": "pod.id", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:id" + ], + "resource": "pod", + "operation": "id", + "commandStart": "cn:pod:id", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cn:pod:id", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 855 + }, + { + "commandID": "cn:pod:config", + "methodID": "pod.config", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:config" + ], + "resource": "pod", + "operation": "config", + "commandStart": "cn:pod:config", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:pod-config", + "minimalArgv": [ + "cn:pod:config", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 856 + }, + { + "commandID": "cn:pod:cpus", + "methodID": "pod.cpus", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:cpus" + ], + "resource": "pod", + "operation": "cpus", + "commandStart": "cn:pod:cpus", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "int", + "minimalArgv": [ + "cn:pod:cpus", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 857 + }, + { + "commandID": "cn:pod:memory", + "methodID": "pod.memory", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:memory" + ], + "resource": "pod", + "operation": "memory", + "commandStart": "cn:pod:memory", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cn:pod:memory", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 858 + }, + { + "commandID": "cn:pod:interfaces", + "methodID": "pod.interfaces", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:interfaces" + ], + "resource": "pod", + "operation": "interfaces", + "commandStart": "cn:pod:interfaces", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:interface[]", + "minimalArgv": [ + "cn:pod:interfaces", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 859 + }, + { + "commandID": "cn:pod:add-container", + "methodID": "pod.addContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:add-container" + ], + "resource": "pod", + "operation": "add-container", + "commandStart": "cn:pod:add-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "container", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--rootfs" + ], + "type": "reference:mount", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--configuration" + ], + "type": "reference:pod-container-config", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:pod-container", + "minimalArgv": [ + "cn:pod:add-container", + "@pod/example", + "example", + "--rootfs", + "@mount/example", + "--configuration", + "@pod-container-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 861 + }, + { + "commandID": "cn:pod:create", + "methodID": "pod.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:create" + ], + "resource": "pod", + "operation": "create", + "commandStart": "cn:pod:create", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:create", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 867 + }, + { + "commandID": "cn:pod:start-container", + "methodID": "pod.startContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:start-container" + ], + "resource": "pod", + "operation": "start-container", + "commandStart": "cn:pod:start-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:start-container", + "@pod/example", + "@pod-container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 868 + }, + { + "commandID": "cn:pod:stop-container", + "methodID": "pod.stopContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:stop-container" + ], + "resource": "pod", + "operation": "stop-container", + "commandStart": "cn:pod:stop-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:stop-container", + "@pod/example", + "@pod-container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 869 + }, + { + "commandID": "cn:pod:stop", + "methodID": "pod.stop", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:stop" + ], + "resource": "pod", + "operation": "stop", + "commandStart": "cn:pod:stop", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:stop", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 870 + }, + { + "commandID": "cn:pod:kill-container", + "methodID": "pod.killContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:kill-container" + ], + "resource": "pod", + "operation": "kill-container", + "commandStart": "cn:pod:kill-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + }, + { + "name": "signal", + "type": "linux-signal", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:kill-container", + "@pod/example", + "@pod-container/example", + "SIGTERM" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 871 + }, + { + "commandID": "cn:pod:wait-container", + "methodID": "pod.waitContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:wait-container" + ], + "resource": "pod", + "operation": "wait-container", + "commandStart": "cn:pod:wait-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--timeout-seconds" + ], + "type": "int64", + "required": false, + "repeatable": false, + "default": null + } + ], + "resultType": "exit-status", + "minimalArgv": [ + "cn:pod:wait-container", + "@pod/example", + "@pod-container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 873 + }, + { + "commandID": "cn:pod:resize-container", + "methodID": "pod.resizeContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:resize-container" + ], + "resource": "pod", + "operation": "resize-container", + "commandStart": "cn:pod:resize-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + }, + { + "name": "width", + "type": "uint16", + "required": true, + "repeatable": false + }, + { + "name": "height", + "type": "uint16", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:resize-container", + "@pod/example", + "@pod-container/example", + "1", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 878 + }, + { + "commandID": "cn:pod:exec-in-container", + "methodID": "pod.execInContainer", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:exec-in-container" + ], + "resource": "pod", + "operation": "exec-in-container", + "commandStart": "cn:pod:exec-in-container", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + }, + { + "name": "process", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--configuration" + ], + "type": "reference:process-config", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:process", + "minimalArgv": [ + "cn:pod:exec-in-container", + "@pod/example", + "@pod-container/example", + "example", + "--configuration", + "@process-config/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 883 + }, + { + "commandID": "cn:pod:list-containers", + "methodID": "pod.listContainers", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:list-containers" + ], + "resource": "pod", + "operation": "list-containers", + "commandStart": "cn:pod:list-containers", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:pod-container[]", + "minimalArgv": [ + "cn:pod:list-containers", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 889 + }, + { + "commandID": "cn:pod:statistics", + "methodID": "pod.statistics", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:statistics" + ], + "resource": "pod", + "operation": "statistics", + "commandStart": "cn:pod:statistics", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--container" + ], + "type": "reference:pod-container", + "required": false, + "repeatable": true, + "default": null + }, + { + "names": [ + "--category" + ], + "type": "statistics-category", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "container-statistics[]", + "minimalArgv": [ + "cn:pod:statistics", + "@pod/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 891 + }, + { + "commandID": "cn:pod:dial-vsock", + "methodID": "pod.dialVsock", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:dial-vsock" + ], + "resource": "pod", + "operation": "dial-vsock", + "commandStart": "cn:pod:dial-vsock", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "port", + "type": "uint32", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:file-handle", + "minimalArgv": [ + "cn:pod:dial-vsock", + "@pod/example", + "1" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 896 + }, + { + "commandID": "cn:pod:filesystem-operation", + "methodID": "pod.filesystemOperation", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:filesystem-operation" + ], + "resource": "pod", + "operation": "filesystem-operation", + "commandStart": "cn:pod:filesystem-operation", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + }, + { + "name": "operation", + "type": "freeze|thaw|trim", + "required": true, + "repeatable": false + }, + { + "name": "path", + "type": "container-path", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:filesystem-operation", + "@pod/example", + "@pod-container/example", + "freeze", + "/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 900 + }, + { + "commandID": "cn:pod:close-container-stdin", + "methodID": "pod.closeContainerStdin", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:close-container-stdin" + ], + "resource": "pod", + "operation": "close-container-stdin", + "commandStart": "cn:pod:close-container-stdin", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:close-container-stdin", + "@pod/example", + "@pod-container/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 905 + }, + { + "commandID": "cn:pod:relay-unix-socket", + "methodID": "pod.relayUnixSocket", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:pod:relay-unix-socket" + ], + "resource": "pod", + "operation": "relay-unix-socket", + "commandStart": "cn:pod:relay-unix-socket", + "commandShape": "reference", + "positionals": [ + { + "name": "pod", + "type": "reference:pod", + "required": true, + "repeatable": false + }, + { + "name": "pod-container", + "type": "reference:pod-container", + "required": true, + "repeatable": false + }, + { + "name": "socket", + "type": "reference:socket", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cn:pod:relay-unix-socket", + "@pod/example", + "@pod-container/example", + "@socket/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 907 + }, + { + "commandID": "cn:content-store:create", + "methodID": "contentStore.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:content-store:create" + ], + "resource": "content-store", + "operation": "create", + "commandStart": "cn:content-store:create", + "commandShape": "create", + "positionals": [ + { + "name": "content-store", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--path" + ], + "type": "host-url", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:content-store", + "minimalArgv": [ + "cn:content-store:create", + "example", + "--path", + "/tmp/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 915 + }, + { + "commandID": "cn:authentication:create-basic", + "methodID": "authentication.createBasic", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:authentication:create-basic" + ], + "resource": "authentication", + "operation": "create-basic", + "commandStart": "cn:authentication:create-basic", + "commandShape": "create", + "positionals": [ + { + "name": "authentication", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--username" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--password" + ], + "type": "string", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:authentication", + "minimalArgv": [ + "cn:authentication:create-basic", + "example", + "--username", + "example", + "--password", + "example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 919 + }, + { + "commandID": "cn:progress-handler:create", + "methodID": "progressHandler.create", + "namespace": "cn", + "sourceKind": "direct", + "aliases": [ + "containerization:progress-handler:create" + ], + "resource": "progress-handler", + "operation": "create", + "commandStart": "cn:progress-handler:create", + "commandShape": "create", + "positionals": [ + { + "name": "progress-handler", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--writer" + ], + "type": "reference:writer", + "required": true, + "repeatable": false, + "default": null + } + ], + "resultType": "reference:progress-handler", + "minimalArgv": [ + "cn:progress-handler:create", + "example", + "--writer", + "@writer/example" + ], + "source": "GHOSTBOX_CLI_TEMPLATE.md", + "sourceLine": 924 + }, + { + "commandID": "cr:volume:create", + "methodID": "volume.create", + "namespace": "cr", + "sourceKind": "ghostvm-adapter", + "aliases": [ + "container:volume:create" + ], + "resource": "volume", + "operation": "create", + "commandStart": "cr:volume:create", + "commandShape": "create", + "positionals": [ + { + "name": "volume", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--size" + ], + "type": "uint64", + "required": false, + "repeatable": false, + "default": 8589934592 + } + ], + "resultType": "reference:volume", + "minimalArgv": [ + "cr:volume:create", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 23, + "swiftModule": "GhostVMContainerRuntime", + "swiftSymbol": "GhostboxVolumeStore.create(name:sizeInBytes:)", + "swiftSource": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:32", + "documentationURL": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L32-L85" + }, + { + "commandID": "cr:volume:list", + "methodID": "volume.list", + "namespace": "cr", + "sourceKind": "ghostvm-adapter", + "aliases": [ + "container:volume:list" + ], + "resource": "volume", + "operation": "list", + "commandStart": "cr:volume:list", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "reference:volume[]", + "minimalArgv": [ + "cr:volume:list" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 27, + "swiftModule": "GhostVMContainerRuntime", + "swiftSymbol": "GhostboxVolumeStore.list()", + "swiftSource": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:88", + "documentationURL": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L88-L91" + }, + { + "commandID": "cr:volume:inspect", + "methodID": "volume.inspect", + "namespace": "cr", + "sourceKind": "ghostvm-adapter", + "aliases": [ + "container:volume:inspect" + ], + "resource": "volume", + "operation": "inspect", + "commandStart": "cr:volume:inspect", + "commandShape": "reference", + "positionals": [ + { + "name": "volume", + "type": "reference:volume", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "volume-metadata", + "minimalArgv": [ + "cr:volume:inspect", + "@volume/example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 28, + "swiftModule": "GhostVMContainerRuntime", + "swiftSymbol": "GhostboxVolumeStore.inspect(name:)", + "swiftSource": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:93", + "documentationURL": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L93-L96" + }, + { + "commandID": "cr:volume:mount", + "methodID": "volume.mount", + "namespace": "cr", + "sourceKind": "ghostvm-adapter", + "aliases": [ + "container:volume:mount" + ], + "resource": "volume", + "operation": "mount", + "commandStart": "cr:volume:mount", + "commandShape": "reference", + "positionals": [ + { + "name": "volume", + "type": "reference:volume", + "required": true, + "repeatable": false + }, + { + "name": "mount", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--destination" + ], + "type": "container-path", + "required": true, + "repeatable": false, + "default": null + }, + { + "names": [ + "--read-only" + ], + "type": "bool", + "required": false, + "repeatable": false, + "default": false + } + ], + "resultType": "reference:mount", + "minimalArgv": [ + "cr:volume:mount", + "@volume/example", + "example", + "--destination", + "/example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 30, + "swiftModule": "GhostVMContainerRuntime", + "swiftSymbol": "GhostboxVolumeStore.makeMount(volumeName:mountReference:destination:readOnly:)", + "swiftSource": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:110", + "documentationURL": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L110-L130" + }, + { + "commandID": "cr:volume:delete", + "methodID": "volume.delete", + "namespace": "cr", + "sourceKind": "ghostvm-adapter", + "aliases": [ + "container:volume:delete" + ], + "resource": "volume", + "operation": "delete", + "commandStart": "cr:volume:delete", + "commandShape": "reference", + "positionals": [ + { + "name": "volume", + "type": "reference:volume", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cr:volume:delete", + "@volume/example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 36, + "swiftModule": "GhostVMContainerRuntime", + "swiftSymbol": "GhostboxVolumeStore.delete(name:)", + "swiftSource": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:98", + "documentationURL": "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L98-L108" + }, + { + "commandID": "cr:memory-size:create", + "methodID": "crMemorySize.create", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:memory-size:create" + ], + "resource": "memory-size", + "operation": "create", + "commandStart": "cr:memory-size:create", + "commandShape": "create", + "positionals": [ + { + "name": "memory-size", + "type": "name", + "required": true, + "repeatable": false + }, + { + "name": "value", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "reference:memory-size", + "minimalArgv": [ + "cr:memory-size:create", + "example", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 47, + "swiftModule": "ContainerPersistence", + "swiftSymbol": "MemorySize.init(_:)", + "swiftSource": "Sources/ContainerPersistence/MemorySize.swift:27", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L27-L29" + }, + { + "commandID": "cr:memory-size:formatted", + "methodID": "crMemorySize.formatted", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:memory-size:formatted" + ], + "resource": "memory-size", + "operation": "formatted", + "commandStart": "cr:memory-size:formatted", + "commandShape": "reference", + "positionals": [ + { + "name": "memory-size", + "type": "reference:memory-size", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string", + "minimalArgv": [ + "cr:memory-size:formatted", + "@memory-size/example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 50, + "swiftModule": "ContainerPersistence", + "swiftSymbol": "MemorySize.formatted", + "swiftSource": "Sources/ContainerPersistence/MemorySize.swift:51", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L51-L55" + }, + { + "commandID": "cr:memory-size:to-uint64", + "methodID": "crMemorySize.toUInt64", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:memory-size:to-uint64" + ], + "resource": "memory-size", + "operation": "to-uint64", + "commandStart": "cr:memory-size:to-uint64", + "commandShape": "reference", + "positionals": [ + { + "name": "memory-size", + "type": "reference:memory-size", + "required": true, + "repeatable": false + }, + { + "name": "unit", + "type": "bytes|kibibytes|mebibytes|gibibytes|tebibytes|pebibytes", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cr:memory-size:to-uint64", + "@memory-size/example", + "bytes" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 52, + "swiftModule": "ContainerPersistence", + "swiftSymbol": "MemorySize.toUInt64(unit:)", + "swiftSource": "Sources/ContainerPersistence/MemorySize.swift:59", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L59-L61" + }, + { + "commandID": "cr:resource-labels:create", + "methodID": "crResourceLabels.create", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:create" + ], + "resource": "resource-labels", + "operation": "create", + "commandStart": "cr:resource-labels:create", + "commandShape": "create", + "positionals": [ + { + "name": "resource-labels", + "type": "name", + "required": true, + "repeatable": false + } + ], + "options": [ + { + "names": [ + "--label" + ], + "type": "string", + "required": false, + "repeatable": true, + "default": null + } + ], + "resultType": "reference:resource-labels", + "minimalArgv": [ + "cr:resource-labels:create", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 64, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.init(_:)", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:39", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L39-L44" + }, + { + "commandID": "cr:resource-labels:validate-key", + "methodID": "crResourceLabels.validateKey", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:validate-key" + ], + "resource": "resource-labels", + "operation": "validate-key", + "commandStart": "cr:resource-labels:validate-key", + "commandShape": "static", + "positionals": [ + { + "name": "key", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cr:resource-labels:validate-key", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 68, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.validateLabelKey(_:)", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:46", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L46-L57" + }, + { + "commandID": "cr:resource-labels:validate", + "methodID": "crResourceLabels.validate", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:validate" + ], + "resource": "resource-labels", + "operation": "validate", + "commandStart": "cr:resource-labels:validate", + "commandShape": "static", + "positionals": [ + { + "name": "key", + "type": "string", + "required": true, + "repeatable": false + }, + { + "name": "value", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "void", + "minimalArgv": [ + "cr:resource-labels:validate", + "example", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 69, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.validateLabel(key:value:)", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:59", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L59-L65" + }, + { + "commandID": "cr:resource-labels:dictionary", + "methodID": "crResourceLabels.dictionary", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:dictionary" + ], + "resource": "resource-labels", + "operation": "dictionary", + "commandStart": "cr:resource-labels:dictionary", + "commandShape": "reference", + "positionals": [ + { + "name": "resource-labels", + "type": "reference:resource-labels", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string-map", + "minimalArgv": [ + "cr:resource-labels:dictionary", + "@resource-labels/example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 70, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.dictionary", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:25", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L25" + }, + { + "commandID": "cr:resource-labels:value", + "methodID": "crResourceLabels.value", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:value" + ], + "resource": "resource-labels", + "operation": "value", + "commandStart": "cr:resource-labels:value", + "commandShape": "reference", + "positionals": [ + { + "name": "resource-labels", + "type": "reference:resource-labels", + "required": true, + "repeatable": false + }, + { + "name": "key", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "string?", + "minimalArgv": [ + "cr:resource-labels:value", + "@resource-labels/example", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 72, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.subscript(_:)", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:90", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L89-L92" + }, + { + "commandID": "cr:resource-labels:key-length-max", + "methodID": "crResourceLabels.keyLengthMax", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:key-length-max" + ], + "resource": "resource-labels", + "operation": "key-length-max", + "commandStart": "cr:resource-labels:key-length-max", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "int", + "minimalArgv": [ + "cr:resource-labels:key-length-max" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 76, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.keyLengthMax", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:21", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L21" + }, + { + "commandID": "cr:resource-labels:label-length-max", + "methodID": "crResourceLabels.labelLengthMax", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:resource-labels:label-length-max" + ], + "resource": "resource-labels", + "operation": "label-length-max", + "commandStart": "cr:resource-labels:label-length-max", + "commandShape": "static", + "positionals": [], + "options": [], + "resultType": "int", + "minimalArgv": [ + "cr:resource-labels:label-length-max" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 77, + "swiftModule": "ContainerResource", + "swiftSymbol": "ResourceLabels.labelLengthMax", + "swiftSource": "Sources/ContainerResource/Common/ResourceLabels.swift:23", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L23" + }, + { + "commandID": "cr:parser:memory-as-mib", + "methodID": "crParser.memoryAsMiB", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:memory-as-mib" + ], + "resource": "parser", + "operation": "memory-as-mib", + "commandStart": "cr:parser:memory-as-mib", + "commandShape": "static", + "positionals": [ + { + "name": "memory", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "int64", + "minimalArgv": [ + "cr:parser:memory-as-mib", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 87, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.memoryStringAsMiB(_:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:57", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L57-L61" + }, + { + "commandID": "cr:parser:memory-as-bytes", + "methodID": "crParser.memoryAsBytes", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:memory-as-bytes" + ], + "resource": "parser", + "operation": "memory-as-bytes", + "commandStart": "cr:parser:memory-as-bytes", + "commandShape": "static", + "positionals": [ + { + "name": "memory", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "uint64", + "minimalArgv": [ + "cr:parser:memory-as-bytes", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 88, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.memoryStringAsBytes(_:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:63", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L63-L67" + }, + { + "commandID": "cr:parser:labels", + "methodID": "crParser.labels", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:labels" + ], + "resource": "parser", + "operation": "labels", + "commandStart": "cr:parser:labels", + "commandShape": "static", + "positionals": [ + { + "name": "label", + "type": "string", + "required": true, + "repeatable": true + } + ], + "options": [], + "resultType": "string-map", + "minimalArgv": [ + "cr:parser:labels", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 89, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.labels(_:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:244", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L244-L261" + }, + { + "commandID": "cr:parser:platform", + "methodID": "crParser.platform", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:platform" + ], + "resource": "parser", + "operation": "platform", + "commandStart": "cr:parser:platform", + "commandShape": "static", + "positionals": [ + { + "name": "platform", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "oci-platform", + "minimalArgv": [ + "cr:parser:platform", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 90, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.platform(from:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:101", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L101-L103" + }, + { + "commandID": "cr:parser:is-valid-domain-name", + "methodID": "crParser.isValidDomainName", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:is-valid-domain-name" + ], + "resource": "parser", + "operation": "is-valid-domain-name", + "commandStart": "cr:parser:is-valid-domain-name", + "commandShape": "static", + "positionals": [ + { + "name": "name", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "bool", + "minimalArgv": [ + "cr:parser:is-valid-domain-name", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 91, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.isValidDomainName(_:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:895", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L895-L900" + }, + { + "commandID": "cr:parser:is-valid-domain-name-label", + "methodID": "crParser.isValidDomainNameLabel", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:is-valid-domain-name-label" + ], + "resource": "parser", + "operation": "is-valid-domain-name-label", + "commandStart": "cr:parser:is-valid-domain-name-label", + "commandShape": "static", + "positionals": [ + { + "name": "label", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "bool", + "minimalArgv": [ + "cr:parser:is-valid-domain-name-label", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 92, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.isValidDomainNameLabel(_:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:902", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L902-L908" + }, + { + "commandID": "cr:parser:parse-bool", + "methodID": "crParser.parseBool", + "namespace": "cr", + "sourceKind": "direct", + "aliases": [ + "container:parser:parse-bool" + ], + "resource": "parser", + "operation": "parse-bool", + "commandStart": "cr:parser:parse-bool", + "commandShape": "static", + "positionals": [ + { + "name": "value", + "type": "string", + "required": true, + "repeatable": false + } + ], + "options": [], + "resultType": "bool?", + "minimalArgv": [ + "cr:parser:parse-bool", + "example" + ], + "source": "GHOSTBOX_CR_CLI_TEMPLATE.md", + "sourceLine": 93, + "swiftModule": "ContainerAPIClient", + "swiftSymbol": "Parser.parseBool(string:)", + "swiftSource": "Sources/Services/ContainerAPIService/Client/Parser.swift:1061", + "documentationURL": "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L1061-L1063" + } + ] +} diff --git a/GHOSTBOX_CLI_TEMPLATE.md b/GHOSTBOX_CLI_TEMPLATE.md new file mode 100644 index 0000000..4bd7503 --- /dev/null +++ b/GHOSTBOX_CLI_TEMPLATE.md @@ -0,0 +1,968 @@ +# Ghostbox Direct API CLI Template + +This document defines the proposed direct Ghostbox CLI surface for Apple's +Containerization framework. It is source-audited against Containerization +`0.40.1` at revision `7800b46`. + +This is not the backend-neutral protocol in `CONTAINER_RUNTIME_PROTOCOL.md`. +It is a diagnostic and development CLI whose operations stay as close as +possible to one public Containerization initializer, method, or property +access per command. + +## Conventions + +The `cn` namespace names Apple's Containerization package and has the long +alias `containerization`. Every command uses one qualified command token; +receiver references, when required, follow that token: + +```text +$ ghostbox cn:RESOURCE:OPERATION [@] [arguments] [options] +``` + +```text + New literal value. +@ Existing VMHost-owned object. +[argument] Optional argument. +argument... Repeatable argument. +-> @ Canonical object reference printed on success. +[--argument=default] Optional argument using the shown framework default. +``` + +The outer macOS VMHost owns all live and value objects. Example references: + +```text +@default ContainerManager +@default/web LinuxContainer +@default/web/shell LinuxProcess +@shared VmnetNetwork +@shared/web Interface +``` + +Object creation prints its canonical `@` reference. Property operations print +JSON-compatible values. Methods returning framework objects register and print +new references. + +`ContainerManager`, `VmnetNetwork`, `Kernel.CommandLine`, and +`LinuxProcessConfiguration` are mutable structs. The registry must serialize +mutation and write the modified value back after every mutating call. Passing +a `Network` to `ContainerManager.init` copies it; the manager's private network +and the original registered network are snapshots that can diverge. + +Configuration closure exceptions are called out below. These operations still +make one lifecycle API call, but the host must supply the API-required closure +and assign a stored configuration value inside it. + +## Image Stores + +```text +ghostbox cn:image-store:create + --path + [--content-store @] + -> @ + +ghostbox cn:image-store:default -> @ +ghostbox cn:image-store:path @ -> + +ghostbox cn:image-store:get @ + + [--pull=false] + -> @ + +ghostbox cn:image-store:list @ -> @... + +ghostbox cn:image-store:create-image @ + @ + -> @ + +ghostbox cn:image-store:delete @ + + [--perform-cleanup=false] + +ghostbox cn:image-store:clean-up-orphaned-blobs @ + -> + +ghostbox cn:image-store:calculate-orphaned-blobs-size @ + -> + +ghostbox cn:image-store:tag @ + + + -> @ + +ghostbox cn:image-store:pull @ + + [--platform ] + [--insecure=false] + [--authentication @] + [--progress @] + [--max-concurrent-downloads=3] + -> @ + +ghostbox cn:image-store:push @ + + [--platform ] + [--insecure=false] + [--authentication @] + [--progress @] + +ghostbox cn:image-store:push-many @ + ... + [--platform ] + [--insecure=false] + [--authentication @] + [--max-concurrent-uploads=3] + [--progress @] + +ghostbox cn:image-store:save @ + ... + --out + [--platform ] + +ghostbox cn:image-store:load @ + + [--progress @] + -> @... + +ghostbox cn:image-store:get-init-image @ + + [--authentication @] + [--progress @] + -> @ +``` + +`ContentStore`, `Authentication`, and `ProgressHandler` are protocol or closure +objects. They are VMHost-owned references, not inline CLI values. Omitting them +passes the framework default. + +## Images + +```text +ghostbox cn:image-description:create + + + -> @ + +ghostbox cn:image-description:reference @ -> +ghostbox cn:image-description:descriptor @ -> +ghostbox cn:image-description:digest @ -> +ghostbox cn:image-description:media-type @ -> + +ghostbox cn:image:create + @ + @ + -> @ + +ghostbox cn:image:description @ -> +ghostbox cn:image:descriptor @ -> +ghostbox cn:image:digest @ -> +ghostbox cn:image:media-type @ -> +ghostbox cn:image:reference @ -> +ghostbox cn:image:index @ -> + +ghostbox cn:image:manifest @ + + -> + +ghostbox cn:image:descriptor-for @ + + -> + +ghostbox cn:image:config @ + + -> + +ghostbox cn:image:referenced-digests @ -> ... + +ghostbox cn:image:get-content @ + + -> @ + +ghostbox cn:content:path @ -> +ghostbox cn:content:digest @ -> +ghostbox cn:content:size @ -> +ghostbox cn:content:data @ -> +ghostbox cn:content:data-range @ + + + -> |null +``` + +## Kernels And Boot Images + +```text +ghostbox cn:kernel-command-line:create + [--kernel-argument ]... + [--init-argument ]... + -> @ + +ghostbox cn:kernel-command-line:create-debug + + + [--init-argument ]... + -> @ + +ghostbox cn:kernel-command-line:add-debug @ +ghostbox cn:kernel-command-line:add-panic @ +ghostbox cn:kernel-command-line:set-agent-log-level @ +ghostbox cn:kernel-command-line:kernel-arguments @ -> ... +ghostbox cn:kernel-command-line:init-arguments @ -> ... + +ghostbox cn:kernel:create + --path + --platform + [--command-line @] + -> @ + +ghostbox cn:kernel:path @ -> +ghostbox cn:kernel:platform @ -> +ghostbox cn:kernel:kernel-arguments @ -> ... +ghostbox cn:kernel:init-arguments @ -> ... + +ghostbox cn:kernel-image:from-image + @ + -> @ + +ghostbox cn:kernel-image:create + + --kernel @... + [--label ]... + --image-store @ + --content-store @ + -> @ + +ghostbox cn:kernel-image:kernel @ + + -> @ + +ghostbox cn:kernel-image:name @ -> +ghostbox cn:kernel-image:media-type -> + +ghostbox cn:init-image:from-image + @ + -> @ + +ghostbox cn:init-image:create + + --rootfs + --platform + [--label ]... + --image-store @ + --content-store @ + -> @ + +ghostbox cn:init-image:init-block @ + --at + --platform + -> @ + +ghostbox cn:init-image:name @ -> +``` + +## Mounts + +```text +ghostbox cn:mount:create + --type + --source + --destination + --option ... + --runtime-options + -> @ + +ghostbox cn:mount:block + --format + --source + --destination + [--option ]... + [--runtime-option ]... + -> @ + +ghostbox cn:mount:share + --source + --destination + [--option ]... + [--runtime-option ]... + -> @ + +ghostbox cn:mount:any + --type + --source + --destination + [--option ]... + [--runtime-option ]... + -> @ + +ghostbox cn:mount:shared-mount + --name + --destination + [--option ]... + -> @ + +ghostbox cn:mount:clone @ + --to + -> @ + +ghostbox cn:mount:is-block @ -> +ghostbox cn:mount:type @ -> +ghostbox cn:mount:source @ -> +ghostbox cn:mount:destination @ -> +ghostbox cn:mount:options @ -> ... +ghostbox cn:mount:runtime-options @ -> +``` + +## DNS And Hosts + +```text +ghostbox cn:dns:create + [--nameserver ]... + [--domain ] + [--search-domain ]... + [--option ]... + -> @ + +ghostbox cn:dns:default-nameservers -> ... +ghostbox cn:dns:validate @ +ghostbox cn:dns:resolv-conf @ -> +ghostbox cn:dns:nameservers @ -> ... +ghostbox cn:dns:domain @ -> |null +ghostbox cn:dns:search-domains @ -> ... +ghostbox cn:dns:options @ -> ... + +ghostbox cn:hosts-entry:create + + ... + [--comment ] + -> @ + +ghostbox cn:hosts-entry:localhost-ipv4 [--comment ] -> @ +ghostbox cn:hosts-entry:localhost-ipv6 [--comment ] -> @ +ghostbox cn:hosts-entry:ipv6-localnet [--comment ] -> @ +ghostbox cn:hosts-entry:ipv6-mcastprefix [--comment ] -> @ +ghostbox cn:hosts-entry:ipv6-allnodes [--comment ] -> @ +ghostbox cn:hosts-entry:ipv6-allrouters [--comment ] -> @ +ghostbox cn:hosts-entry:rendered @ -> +ghostbox cn:hosts-entry:ip-address @ -> +ghostbox cn:hosts-entry:hostnames @ -> ... +ghostbox cn:hosts-entry:comment @ -> |null + +ghostbox cn:hosts:create + [--entry @]... + [--comment ] + -> @ + +ghostbox cn:hosts:default -> @ +ghostbox cn:hosts:hosts-file @ -> +ghostbox cn:hosts:entries @ -> @... +ghostbox cn:hosts:comment @ -> |null +``` + +## Socket And Boot Log Configuration + +```text +ghostbox cn:socket:create + --source + --destination + [--permissions ] + [--direction ] + -> @ + +ghostbox cn:socket:id @ -> +ghostbox cn:socket:source @ -> +ghostbox cn:socket:destination @ -> +ghostbox cn:socket:permissions @ -> |null +ghostbox cn:socket:direction @ -> + +ghostbox cn:boot-log:file + --path + [--append=true] + -> @ +``` + +`BootLog.fileHandle(_:)` is excluded because it requires a live host +`FileHandle`; `BootLog.file(path:append:)` is the CLI-safe public factory. + +## Networks And Interfaces + +`VmnetNetwork` is available on macOS 26 and later. + +```text +ghostbox cn:network:vmnet-create + [--mode=shared] + [--subnet ] + [--prefix-v6 ] + -> @ + +ghostbox cn:network:subnet @ -> +ghostbox cn:network:prefix-v6 @ -> |null +ghostbox cn:network:ipv4-gateway @ -> +ghostbox cn:network:ipv6-gateway @ -> |null + +ghostbox cn:network:create-interface @ + + -> @|null + +ghostbox cn:network:create-interface-mtu @ + + + -> @|null + +ghostbox cn:network:create-interface-without-gateway @ + + -> @|null + +ghostbox cn:network:release-interface @ @ + +# Maps to the platform-independent Containerization.NATInterface value type. +ghostbox cn:interface:nat-create + --ipv4-address + [--ipv4-gateway ] + [--ipv6-address ] + [--ipv6-gateway ] + [--mac-address ] + [--mtu=1500] + -> @ + +ghostbox cn:interface:ipv4-address @ -> +ghostbox cn:interface:ipv4-gateway @ -> |null +ghostbox cn:interface:ipv6-address @ -> |null +ghostbox cn:interface:ipv6-gateway @ -> |null +ghostbox cn:interface:mac-address @ -> |null +ghostbox cn:interface:mtu @ -> +``` + +`NATNetworkInterface.init(...reference:)` and `VmnetNetwork.Interface.init` +are excluded because they require a live `vmnet_network_ref` C object. + +## VM Configuration And VMM + +```text +ghostbox cn:vm-config:create + [--cpus=4] + [--memory=1073741824] + [--interface @]... + [--mount =@]... + [--boot-log @] + [--nested-virtualization=false] + -> @ + +ghostbox cn:standard-vm-config:create + @ + -> @ + +ghostbox cn:vmm:create + --kernel @ + --initial-filesystem @ + [--rosetta=false] + [--nested-virtualization=false] + -> @ + +ghostbox cn:vmm:create-instance @ + @ + -> @ + +ghostbox cn:vm-instance:state @ -> +ghostbox cn:vm-instance:mounts @ -> +ghostbox cn:vm-instance:virtiofs-layout @ -> +ghostbox cn:vm-instance:start @ +ghostbox cn:vm-instance:stop @ +ghostbox cn:vm-instance:pause @ +ghostbox cn:vm-instance:resume @ + +ghostbox cn:vm-instance:dial @ + + -> @ +``` + +The VMM constructor fixes `EventLoopGroup` and `Logger` to `nil`. Custom +`VMConfiguration.extensions`, `dialAgent`, listeners, and hotplug operations +remain excluded until Ghostbox defines registry-backed wrappers for their live +protocol objects. + +## Process Configuration + +```text +ghostbox cn:rlimit-kind:create + + -> @ + +ghostbox cn:rlimit:create + --kind @ + --hard + --soft + -> @ + +ghostbox cn:rlimit:create-equal + --kind @ + --limit + -> @ + +ghostbox cn:rlimit:kind @ -> @ +ghostbox cn:rlimit:hard @ -> +ghostbox cn:rlimit:soft @ -> +ghostbox cn:rlimit:to-oci @ -> + +ghostbox cn:capabilities:create + [--bounding ]... + [--effective ]... + [--inheritable ]... + [--permitted ]... + [--ambient ]... + -> @ + +ghostbox cn:capabilities:create-uniform + ... + -> @ + +ghostbox cn:capabilities:all -> @ +ghostbox cn:capabilities:default-oci -> @ +ghostbox cn:capabilities:bounding @ -> ... +ghostbox cn:capabilities:effective @ -> ... +ghostbox cn:capabilities:inheritable @ -> ... +ghostbox cn:capabilities:permitted @ -> ... +ghostbox cn:capabilities:ambient @ -> ... +ghostbox cn:capabilities:to-oci @ -> + +ghostbox cn:process-config:default-path -> + +ghostbox cn:process-config:create + ... + [--environment ]... + [--working-directory=/] + [--user ] + [--rlimit @]... + [--no-new-privileges=false] + [--capabilities @] + [--terminal=false] + [--stdin @] + [--stdout @] + [--stderr @] + -> @ + +ghostbox cn:process-config:from-image-config + + -> @ + +ghostbox cn:process-config:set-terminal-io @ + @ + +ghostbox cn:process-config:arguments @ -> ... +ghostbox cn:process-config:environment-variables @ -> ... +ghostbox cn:process-config:working-directory @ -> +ghostbox cn:process-config:user @ -> +ghostbox cn:process-config:rlimits @ -> @... +ghostbox cn:process-config:no-new-privileges @ -> +ghostbox cn:process-config:capabilities @ -> @ +ghostbox cn:process-config:terminal @ -> +ghostbox cn:process-config:stdin @ -> @|null +ghostbox cn:process-config:stdout @ -> @|null +ghostbox cn:process-config:stderr @ -> @|null +``` + +Stdio and terminal arguments are VMHost-owned protocol objects. Ghostbox proxy +extensions register guest-backed adapters without combining lifecycle calls. + +## Container Configuration + +```text +ghostbox cn:container-config:create-default + -> @ + +ghostbox cn:container-config:create + --process @ + [--cpus=4] + [--memory=1073741824] + [--hostname ] + [--sysctl ]... + [--interface @]... + [--socket @]... + [--mount @]... + [--masked-path ]... + [--readonly-path ]... + [--dns @] + [--hosts @] + [--virtualization=false] + [--boot-log @] + [--oci-runtime-path ] + [--use-init=false] + [--cpu-overhead=1] + [--memory-overhead=134217728] + -> @ + +ghostbox cn:container:default-mounts -> @... +ghostbox cn:container:default-oci-mounts -> ... +ghostbox cn:container:default-masked-paths -> ... +ghostbox cn:container:default-readonly-paths -> ... +ghostbox cn:container:default-copy-chunk-size -> +ghostbox cn:container:max-id-length -> +``` + +## Container Managers + +Distinct constructor verbs avoid ambiguity between Swift overloads whose +optional arguments otherwise produce identical CLI shapes. + +```text +ghostbox cn:manager:create + --kernel @ + --initfs @ + --image-store @ + [--network @] + [--rosetta=false] + [--nested-virtualization=false] + -> @ + +ghostbox cn:manager:create-at-root + --kernel @ + --initfs @ + [--root ] + [--network @] + [--rosetta=false] + [--nested-virtualization=false] + -> @ + +ghostbox cn:manager:create-from-reference + --kernel @ + --initfs-reference + --image-store @ + [--network @] + [--rosetta=false] + [--nested-virtualization=false] + -> @ + +ghostbox cn:manager:create-from-reference-at-root + --kernel @ + --initfs-reference + [--root ] + [--network @] + [--rosetta=false] + [--nested-virtualization=false] + -> @ + +ghostbox cn:manager:create-with-vmm + --vmm @ + [--network @] + -> @ + +ghostbox cn:manager:image-store @ -> @ +``` + +## Manager Container Allocation + +These three framework methods require a non-optional configuration closure. +Ghostbox builds the closure from optional configuration overrides and applies +them to the manager-populated `inout LinuxContainer.Configuration`. It must not +replace the value wholesale: the manager has already populated image process +settings, networking, DNS, and its boot log. No extra lifecycle API is called. + +```text +--process @ +--cpus +--memory +--hostname +--sysctl ... +--interfaces @... +--sockets @... +--mounts @... +--masked-paths ... +--readonly-paths ... +--dns @ +--hosts @ +--virtualization +--boot-log @ +--oci-runtime-path +--use-init +--cpu-overhead +--memory-overhead +``` + +```text +ghostbox cn:manager:create-container @ + + --reference + [--rootfs-size=8589934592] + [--writable-layer-size ] + [--read-only=false] + [--networking=true] + [--progress @] + []... + -> @ + +ghostbox cn:manager:create-container-from-image @ + + --image @ + [--rootfs-size=8589934592] + [--writable-layer-size ] + [--read-only=false] + [--networking=true] + [--progress @] + []... + -> @ + +ghostbox cn:manager:create-container-from-mounts @ + + --image @ + --rootfs @ + [--writable-layer @] + [--networking=true] + []... + -> @ + +ghostbox cn:manager:release-network @ @ +ghostbox cn:manager:delete @ @ +``` + +## Containers + +```text +ghostbox cn:container:create-direct + --rootfs @ + [--writable-layer @] + --vmm @ + --configuration @ + -> @ + +ghostbox cn:container:id @ -> +ghostbox cn:container:rootfs @ -> @ +ghostbox cn:container:writable-layer @ -> @|null +ghostbox cn:container:config @ -> @ +ghostbox cn:container:cpus @ -> +ghostbox cn:container:memory @ -> +ghostbox cn:container:interfaces @ -> @... + +ghostbox cn:container:create @ +ghostbox cn:container:start @ +ghostbox cn:container:stop @ +ghostbox cn:container:kill @ + +ghostbox cn:container:wait @ + [--timeout-seconds ] + -> + +ghostbox cn:container:resize @ + + + +ghostbox cn:container:exec @ + + --configuration @ + -> @ + +ghostbox cn:container:dial-vsock @ + + -> @ + +ghostbox cn:container:close-stdin @ + +ghostbox cn:container:statistics @ + [--category ]... + -> + +ghostbox cn:container:filesystem-operation @ + + + +ghostbox cn:container:copy-in @ + + + [--mode=0644] + [--create-parents=true] + [--chunk-size=1048576] + +ghostbox cn:container:copy-out @ + + + [--create-parents=true] + [--chunk-size=1048576] +``` + +There is no public `LinuxContainer.pause()`, `resume()`, `delete()`, `state`, or +container-level Unix-socket relay operation. VM pause and resume exist only on +`VirtualMachineInstance`, which Containerization exposes to containers through +the scoped `withVirtualMachineInstance` closure. That closure is deliberately +not converted into a durable CLI reference. + +## Processes + +`LinuxProcess` has no public initializer. A process reference is created only +by `LinuxContainer.exec` or `LinuxPod.execInContainer`. + +```text +ghostbox cn:process:id @ -> +ghostbox cn:process:owning-container @ -> |null +ghostbox cn:process:pid @ -> + +ghostbox cn:process:start @ +ghostbox cn:process:kill @ + +ghostbox cn:process:resize @ + + + +ghostbox cn:process:close-stdin @ + +ghostbox cn:process:wait @ + [--timeout-seconds ] + -> + +ghostbox cn:process:delete @ +``` + +## Experimental Pods + +Pod construction, container addition, and process execution only have closure configuration forms. Ghostbox assigns the stored value inside that closure. +For `exec-in-container`, this intentionally replaces Apple's inherited configuration and returns an unstarted process that is not registered in pod state. +`pod config` returns the pod's immutable configuration as a read-only detached +snapshot. Use a separately created `pod-config` reference as a mutable builder. + +```text +ghostbox cn:pod-volume:create + --name + --source + --format + -> @ + +ghostbox cn:pod-config:create -> @ +ghostbox cn:pod-config:set-cpus @ +ghostbox cn:pod-config:set-memory @ +ghostbox cn:pod-config:set-interfaces @ @... +ghostbox cn:pod-config:set-virtualization @ +ghostbox cn:pod-config:set-boot-log @ @|null +ghostbox cn:pod-config:set-share-process-namespace @ +ghostbox cn:pod-config:set-hostname @ |null +ghostbox cn:pod-config:set-dns @ @|null +ghostbox cn:pod-config:set-hosts @ @|null +ghostbox cn:pod-config:set-volumes @ @... + +ghostbox cn:pod-container-config:create -> @ +ghostbox cn:pod-container-config:set-process @ @ +ghostbox cn:pod-container-config:set-cpus @ |null +ghostbox cn:pod-container-config:set-memory @ |null +ghostbox cn:pod-container-config:set-hostname @ |null +ghostbox cn:pod-container-config:set-sysctl @ ... +ghostbox cn:pod-container-config:set-mounts @ @... +ghostbox cn:pod-container-config:set-masked-paths @ ... +ghostbox cn:pod-container-config:set-readonly-paths @ ... +ghostbox cn:pod-container-config:set-sockets @ @... +ghostbox cn:pod-container-config:set-dns @ @|null +ghostbox cn:pod-container-config:set-hosts @ @|null +ghostbox cn:pod-container-config:set-use-init @ + +ghostbox cn:pod:create-direct + --vmm @ + --configuration @ + -> @ + +ghostbox cn:pod:id @ -> +ghostbox cn:pod:config @ -> @ +ghostbox cn:pod:cpus @ -> +ghostbox cn:pod:memory @ -> +ghostbox cn:pod:interfaces @ -> @... + +ghostbox cn:pod:add-container @ + + --rootfs @ + --configuration @ + -> @ + +ghostbox cn:pod:create @ +ghostbox cn:pod:start-container @ @ +ghostbox cn:pod:stop-container @ @ +ghostbox cn:pod:stop @ +ghostbox cn:pod:kill-container @ @ + +ghostbox cn:pod:wait-container @ + @ + [--timeout-seconds ] + -> + +ghostbox cn:pod:resize-container @ + @ + + + +ghostbox cn:pod:exec-in-container @ + @ + + --configuration @ + -> @ + +ghostbox cn:pod:list-containers @ -> @... + +ghostbox cn:pod:statistics @ + [--container @]... + [--category ]... + -> ... + +ghostbox cn:pod:dial-vsock @ + + -> @ + +ghostbox cn:pod:filesystem-operation @ + @ + + + +ghostbox cn:pod:close-container-stdin @ @ + +ghostbox cn:pod:relay-unix-socket @ + @ + @ +``` + +## Content Stores, Authentication, and Progress + +```text +ghostbox cn:content-store:create + --path + -> @ + +ghostbox cn:authentication:create-basic + --username + --password + -> @ + +ghostbox cn:progress-handler:create + --writer @ + -> @ +``` + +`progress-handler create` adapts Apple's callback to newline-delimited JSON +objects written through the supplied registered `Writer`. Each object contains +the framework event's `event` and integer `value` properties. + +## Container Resource Visibility + +Each `LinuxContainer` runs in its own VM. `cpus` and `memory` are workload +cgroup limits, while `/proc/cpuinfo` and `/proc/meminfo` expose VM capacity. +For manager create operations, supplying `cpus` selects zero additional vCPUs +unless `cpuOverhead` is explicit. Supplying `memory` selects the bundled guest +kernel reservation as `memoryOverhead` unless that option is explicit, so +`MemTotal` tracks the requested workload memory. Explicit overhead options retain +Apple's `capacity = limit + overhead` behavior. Cgroup v2 `cpu.max` and +`memory.max`, or `container statistics`, remain authoritative for enforcement. + +## Explicit Exclusions + +```text +LinuxContainer.withVirtualMachineInstance(...) +LinuxPod.withVirtualMachineInstance(...) +BootLog.fileHandle(...) +VmnetNetwork.Interface.init(...) +NATNetworkInterface.init(...reference: vmnet_network_ref...) +Mount.configure(...) +Mount.readonly +ImageStore import/export implementation types +LinuxProcess internal initializer +ProgressHandler inline closures other than the registered writer adapter +Arbitrary Authentication protocol implementations +VMCreationConfig custom protocol implementations +VMConfiguration.extensions +VirtualMachineInstance listeners, agents, and hotplug objects +VZVirtualMachineInstance direct initializer and Configuration closure +Content.decode() generic decoding +Cloud Hypervisor and Linux-only network backends +``` + +These APIs are closure-scoped, internal, require non-serializable host objects, +or are outside the VZ-backed macOS container scope. They must not be presented +as direct CLI operations without a separate registry-backed transport design. diff --git a/GHOSTBOX_CR_CLI_TEMPLATE.md b/GHOSTBOX_CR_CLI_TEMPLATE.md new file mode 100644 index 0000000..bdd5bcc --- /dev/null +++ b/GHOSTBOX_CR_CLI_TEMPLATE.md @@ -0,0 +1,131 @@ +# Ghostbox Container API CLI Template + +This document defines the initial direct Ghostbox CLI catalog for selected APIs +implemented by Apple container `1.2.0` at revision +`6e65319fe476ffe8db8ddaf828a537ed36fe2859`, plus GhostVM's persistent-volume +adapter. It is intentionally limited to the commands listed here. + +The `cr` namespace has the long alias `container`. Commands use one qualified +command token followed by an optional receiver reference and arguments: + +```text +$ ghostbox cr:RESOURCE:OPERATION [@] [arguments] [options] +``` + +The value syntax and reference ownership conventions are the same as in +`GHOSTBOX_CLI_TEMPLATE.md`. Direct commands map to one public Swift API. Volume +commands map to the existing GhostVM adapter and retain their `volume.*` wire +method IDs. + +## Persistent Volumes + +```text +ghostbox cr:volume:create + [--size=8589934592] + -> @ + +ghostbox cr:volume:list -> @... +ghostbox cr:volume:inspect @ -> + +ghostbox cr:volume:mount @ + + --destination + [--read-only=false] + -> @ + +ghostbox cr:volume:delete @ +``` + +Volumes are persistent ext4 images owned by the VM. `inspect` returns name, +format, byte size, and creation time, but never exposes the outer-host backing +path. `delete` permanently removes an unused volume and its contents. Delete +the mount reference before deleting its volume. + +## Memory Size + +```text +ghostbox cr:memory-size:create + -> @ + +ghostbox cr:memory-size:formatted @ -> + +ghostbox cr:memory-size:to-uint64 @ + + -> +``` + +`create` accepts the syntax implemented by `MemorySize`, such as `512mb` or +`2gb`. Conversion uses Foundation information-storage units and rounds to the +nearest unsigned integer, matching the upstream implementation. + +## Resource Labels + +```text +ghostbox cr:resource-labels:create + [--label ]... + -> @ + +ghostbox cr:resource-labels:validate-key +ghostbox cr:resource-labels:validate +ghostbox cr:resource-labels:dictionary @ -> + +ghostbox cr:resource-labels:value @ + + -> |null + +ghostbox cr:resource-labels:key-length-max -> +ghostbox cr:resource-labels:label-length-max -> +``` + +Labels supplied to `create` use `key=value` text. Validation enforces the exact +upstream key and full-label limits. Do not place secrets in labels; dictionary +and value operations return them as plain JSON values. + +## Parser Utilities + +```text +ghostbox cr:parser:memory-as-mib -> +ghostbox cr:parser:memory-as-bytes -> +ghostbox cr:parser:labels ... -> +ghostbox cr:parser:platform -> +ghostbox cr:parser:is-valid-domain-name -> +ghostbox cr:parser:is-valid-domain-name-label -> +ghostbox cr:parser:parse-bool -> |null +``` + +These utilities are deterministic string/value parsers. `labels` does not apply +`ResourceLabels` validation; use the resource-label validation commands when +validated metadata is required. `parse-bool` accepts only `true`, `t`, `false`, +or `f`, case-insensitively, and returns `null` for other input. + +## Source Metadata + +The generator consumes the metadata block below. `swiftSource` values are +repository-relative and line-pinned to the audited revisions named above. + + diff --git a/GHOSTFILE.md b/GHOSTFILE.md new file mode 100644 index 0000000..aee3244 --- /dev/null +++ b/GHOSTFILE.md @@ -0,0 +1,100 @@ +# GhostFile + +GhostFile is a standalone macOS demo for sharing and mounting folders over a +local network with FSKit. + +One `GhostFile.app` instance shares a selected folder through a versioned, +read-only HTTP/3 filesystem API and advertises it with Bonjour. Another instance +discovers that share (or accepts its URL manually) and mounts it through the +embedded `GhostFileFS.appex` extension. + +```text +GhostFile.app (Share) GhostFile.app (Mount) + | | + +-- _ghostfile._udp via mDNS ----------+ + | | + +-- GhostFile v1 over HTTP/3 ---------->+-- GhostFileFS.appex + | + +-- native mount +``` + +## Build and run + +The extension uses the restricted `com.apple.developer.fskit.fsmodule` +entitlement. Select an Apple Developer team that has this capability before +running the signed app. + +```bash +make ghostfile DEVELOPMENT_TEAM=YOUR_TEAM_ID +make run-ghostfile DEVELOPMENT_TEAM=YOUR_TEAM_ID +``` + +Use `open -n build/xcode/Build/Products/Debug/GhostFile.app` to launch a second +instance. Enable **GhostFileFS** under **System Settings > General > Login Items +& Extensions > File System Extensions** before mounting. + +The mounted volume appears under `~/GhostFile Mounts` and can be revealed in +Finder from the app. + +## Protocol + +Version 1 exposes bounded, WebDAV-like operations for each share: + +- `capabilities` +- `metadata(path)` +- `directory(path)` +- `content(path, offset, length)` +- `readlink(path)` + +The wire protocol uses normal HTTP semantics: `GET` requests, HTTPS pseudo +headers, bearer authorization, status codes, content lengths, and byte ranges. +Each request uses an independent bidirectional HTTP/3 stream on one persistent +QUIC connection. Directory responses contain a stable verifier for FSKit +pagination, and file reads are limited to 1 MiB per request. Paths are relative +to the selected share and both lexical traversal and symlink escapes are +rejected. + +GhostHTTP3 embeds Cloudflare's quiche library in a dynamically linked arm64 +framework. Network.framework carries its UDP datagrams, while quiche implements +the QUIC transport, TLS 1.3 handshake, QPACK, HTTP/3 request/response framing, +flow control, and multiplexing. Integration tests cover 32 concurrent 64 KiB +range reads and verify that a two-second paused request doesn't delay an +independent request on the same connection. + +The server represents file bodies as immutable path/offset/length descriptors. +Random-access `DispatchIO` channels perform the actual range reads and deliver +their data outside the serialized HTTP/3 connection actor. Metadata and +directory routing use a separate concurrent Dispatch queue, so blocking file +system calls do not occupy the connection actor or Swift's cooperative executor. + +The service is advertised as `_ghostfile._udp` with `transport=http3` and +`alpn=h3` TXT values. Peers negotiate the standard `h3` ALPN over TLS 1.3 and +QUIC. The server uses an ephemeral certificate whose DER SHA-256 pin is carried +in the share URL, so the self-signed local connection is still authenticated. + +## Current scope + +- Read-only shares and mounts. +- Local-network discovery with Bonjour/mDNS. +- Manual URL mounting for environments where multicast discovery is + unavailable, including VM-to-host networking. +- Access keys and the server public-key pin are passed to the extension in the + FSKit resource URL for this demo. A production version should move credentials + into a shared Keychain access group and persist/pair TLS identities. +- New directory entries and metadata are fetched from the server. macOS may + retain already-read file pages in its unified buffer cache; remount a share to + guarantee a fresh snapshot after an existing source file is overwritten. + +## Verification + +```bash +make test-ghostfile DEVELOPMENT_TEAM=YOUR_TEAM_ID +scripts/stress-ghostfile.sh /path/to/mount /path/to/shared/folder +python3 scripts/benchmark-ghostfile.py \ + /path/to/shared/folder/large-file /path/to/mount/large-file +``` + +The stress script checks parallel reads, checksums, directory enumeration, +spaces and UTF-8 names, symlinks, and enforcement of the read-only mount. +Recorded before/after performance results are in +[`GHOSTFILE_BENCHMARKS.md`](GHOSTFILE_BENCHMARKS.md). diff --git a/GHOSTFILE_BENCHMARKS.md b/GHOSTFILE_BENCHMARKS.md new file mode 100644 index 0000000..8bb1437 --- /dev/null +++ b/GHOSTFILE_BENCHMARKS.md @@ -0,0 +1,137 @@ +# GhostFile benchmarks + +## 2026-08-02: installed writable FSKit prototype + +The earlier read-only benchmark established read performance only; it was not +evidence that filesystem mutations worked. This pass used the signed +`/Applications/GhostFile.app` extension and a real FSKit mount backed by the +workspace share. Every mounted mutation was checked against the source path. + +Functional results: + +- one 3 MiB `write(2)` path split into concurrent FSKit callbacks: passed; +- three simultaneous 1 MiB writes at disjoint offsets in one file: passed; +- create, mkdir, chmod, same- and cross-directory rename, truncate, symlink, + unlink, and rmdir: passed; +- live read-only enable rejected create and chmod with `EROFS`; disabling it + restored writes on the existing mount; +- writable stress: 25 checks, including 200 parallel operation batches, with + zero failures; +- XCTest: 48 tests, one intentional skip, zero failures. + +Mounted-versus-native results use the existing 75.5 MiB and 8,192-file +fixtures. Values are medians of three samples. + +| Test | Previous FSKit | Current FSKit | Change | +| --- | ---: | ---: | ---: | +| Random 4 KiB read (`F_NOCACHE`) | 1,302.8 us/op | 1,216.7 us/op | 6.6% lower latency | +| Sequential read (`F_NOCACHE`) | 12.7 MiB/s | 123.4 MiB/s | 9.7x | +| Warm sequential read | 17,215.5 MiB/s | 18,058.5 MiB/s | 1.05x | +| Recursive enumeration | 26,284 entries/s | 173,472 entries/s | 6.6x | +| Small-file open + read | 2,318.8 IOPS | 1,110.9 IOPS | 0.48x | +| Directory listing | 513.3 IOPS | 3,933.0 IOPS | 7.7x | + +Sequential mounted writes of a 64 MiB file measured 135.3, 136.0, and +135.2 MiB/s (about 135.3 MiB/s median). There is no valid previous write +number because the old mounted path was read-only. Hard links remain explicitly +unsupported (`ENOTSUP`) rather than being reported as functional. + +## 2026-07-31: receive-side QUIC datagram batching + +The remaining throughput ceiling was a serialized per-datagram feedback loop, +not file I/O or HTTP/3 stream head-of-line blocking. Although each +`NWConnection` registered 64 concurrent `receiveMessage` calls, every callback +created an actor task that independently performed QUIC receive, HTTP/3 event +polling, and an awaited outgoing flush. That made ACK/control processing and +response progress pay the Swift task, actor, quiche, and Network.framework +costs once per UDP packet. + +The client and server now re-arm the receive immediately, queue completed UDP +datagrams on their connection actor, and drain up to 64 datagrams before one +HTTP/3 event poll and outgoing flush. + +### Direct HTTP/3 result + +The same 75.5 MiB fixture and 1,350-byte QUIC payload were used before and +after. The after values are medians of three runs without diagnostic logging. + +| Test | Before batching | After batching | Improvement | +| --- | ---: | ---: | ---: | +| Sequential 1 MiB ranges | 16.8 MiB/s | 167.7 MiB/s | 10.0x | +| 16 concurrent streams | 27.4 MiB/s | 192.8 MiB/s | 7.0x | + +After samples: + +- Sequential: 148.6, 168.4, 167.7 MiB/s +- 16-stream: 192.8, 189.5, 193.8 MiB/s + +### Diagnostic evidence + +Opt-in `GHOSTFILE_HTTP3_DIAGNOSTICS=1` sampling showed the pre-fix client +spending about 490 ms of each 500 ms interval waiting on single-packet UDP +sends, while the server's loopback QUIC RTT inflated to roughly 28 ms. The +server emitted only about 7,250 packets per half-second. After receive-side +batching, RTT fell to roughly 1.2 ms and the server emitted about 57,000 packets +in a half-second with only five packets reported lost across the transfer. + +As a separate isolation test, increasing only the loopback QUIC payload from +1,350 to 8,000 bytes raised the pre-fix result to 83.3 MiB/s sequential and +93.1 MiB/s with 16 streams. That confirmed the ceiling scaled with UDP packet +count. Jumbo payloads are not the production fix because real network paths +must retain a conservative MTU; receive-side batching removes the per-packet +serialization while keeping the 1,350-byte payload. + +## 2026-07-31: synchronous body producer to DispatchIO + +These measurements use the same 75.5 MiB fixture on one Apple Silicon Mac. +Direct HTTP/3 runs use one persistent loopback QUIC connection. Mounted runs +compare the source file with the FSKit mount and use `F_NOCACHE` where noted. +Values are medians; the raw direct HTTP/3 samples are included because the +16-stream result has occasional low outliers. + +### Direct HTTP/3 + +| Test | Before | After | +| --- | ---: | ---: | +| Sequential 1 MiB ranges | 16.8 MiB/s | 16.8 MiB/s | +| 16 concurrent streams | 27.8 MiB/s | 27.4 MiB/s | + +Before samples: + +- Sequential: 16.7, 16.8, 16.9 MiB/s +- 16-stream: 28.1, 19.6, 27.8 MiB/s + +After samples: + +- Sequential: 16.5, 16.5, 17.1, 16.8, 17.0 MiB/s +- 16-stream: 29.0, 27.2, 29.2, 27.4, 16.8 MiB/s + +### FSKit mount versus native I/O + +| Test | Before | After | +| --- | ---: | ---: | +| Random 4 KiB read | 1,250.1 us/op | 1,302.8 us/op | +| Sequential `F_NOCACHE` | 13.2 MiB/s | 12.7 MiB/s | +| Warm sequential | 17,944.1 MiB/s | 17,215.5 MiB/s | +| `stat` | 0.8 us/op | 0.8 us/op | +| `readdir` | 515.2 us/op | 524.4 us/op | +| Recursive enumeration | 27,105 entries/s | 26,284 entries/s | +| Small-file open + read | 2,437.7 IOPS | 2,318.8 IOPS | +| Directory listing | 536.2 IOPS | 513.3 IOPS | + +A fresh-mount random-read scaling check after the change measured 768 IOPS +with one worker and 1,869 IOPS with 16 workers, a 2.43x throughput increase. + +### Interpretation + +DispatchIO removes regular-file reads and byte copying from the serialized +HTTP/3 connection actor. Routing operations such as `lstat` and directory +enumeration run on a separate Dispatch queue. This prevents file I/O from +stalling QUIC packet, ACK, and timeout processing, but it does not materially +raise throughput: the before/after differences above are within run-to-run +variance. The remaining performance ceiling is in the shared HTTP/3 packet +pump rather than synchronous file reads. + +The after measurements also include reducing the per-datagram output buffer +from 65,535 bytes to the configured 1,350-byte QUIC payload size. Without that +change, 16-stream runs frequently collapsed to approximately 16--18 MiB/s. diff --git a/Makefile b/Makefile index a6b5b8d..c07de50 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # GhostVM Makefile # Builds vmctl CLI and the SwiftUI app via xcodebuild -# Load .env for notarization credentials (NOTARY_APPLE_ID, NOTARY_TEAM_ID, NOTARY_PASSWORD) +# Load local signing and notarization configuration. -include .env export @@ -10,17 +10,35 @@ GHOSTTOOLS_SIGN_ID ?= $(CODESIGN_ID) APP_PROVISIONING_PROFILE ?= .var/profiles/GhostVM_App_Distribution.provisionprofile HELPER_PROVISIONING_PROFILE ?= .var/profiles/GhostVM_Helper_Distribution.provisionprofile VMCTL_PROVISIONING_PROFILE ?= .var/profiles/vmctl_command_line.provisionprofile +FSKIT_PROVISIONING_PROFILE ?= .var/profiles/GhostVM_FS_Distribution.provisionprofile -# Inject build timestamp into patch version during development builds. -# Set to 0 for production releases (make dist does this automatically). +# Inject the build timestamp into the patch version. +# Set to 0 only when a canonical release version is explicitly required. INJECT_TIMESTAMP ?= 1 BUILD_TIMESTAMP := $(shell date +%Y%m%d%H%M%S) +GHOSTFILE_MAJOR_MINOR ?= 1.0 +GHOSTFILE_VERSION ?= $(GHOSTFILE_MAJOR_MINOR).$(BUILD_TIMESTAMP) +GHOSTFILE_BUILD_NUMBER ?= $(BUILD_TIMESTAMP) +GHOSTFILE_KEEP_INTERMEDIATES ?= 0 +GHOSTFILE_ARCHIVE = build/GhostFile-$(GHOSTFILE_VERSION).xcarchive +GHOSTFILE_EXPORT_DIR = build/GhostFile-$(GHOSTFILE_VERSION)-export +GHOSTFILE_DERIVED_DATA = build/.GhostFile-$(GHOSTFILE_VERSION)-DerivedData +GHOSTFILE_EXPORT_OPTIONS = build/GhostFile-$(GHOSTFILE_VERSION)-DeveloperIDExportOptions.plist +GHOSTFILE_DMG = build/GhostFile-$(GHOSTFILE_VERSION)-arm64.dmg +GHOSTFILE_NOTARY_INPUT = build/GhostFile-$(GHOSTFILE_VERSION)-notary-submission-arm64.dmg +GHOSTFILE_ARTIFACT = build/GhostFile-$(GHOSTFILE_VERSION)-notarized-arm64.dmg +GHOSTFILE_SHARED_DOWNLOADS ?= /Volumes/My Shared Files/Downloads +GHOSTFILE_LSREGISTER = /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister +GHOSTFILE_CODESIGN_ID ?= $(shell security find-identity -v -p codesigning | sed -n 's/.*"\(Developer ID Application:[^"]*\)".*/\1/p' | head -1) +GHOSTFILE_SIGNING_TEAM ?= $(shell security find-identity -v -p codesigning | sed -n 's/.*"Developer ID Application:.*(\([A-Z0-9]*\))".*/\1/p' | head -1) +GHOSTFILE_NOTARY_TIMEOUT ?= 45m APP_SKIP_XCODE_SIGNING ?= 0 XCODE_ALLOW_PROVISIONING_UPDATES ?= 1 # Xcode project settings (generated via xcodegen) XCODE_PROJECT = macOS/GhostVM.xcodeproj XCODE_CONFIG ?= Release +DEBUG_DMG_CONFIGURATION ?= Release BUILD_DIR ?= build/xcode APP_NAME = GhostVM VERSION_FILE = .version @@ -30,17 +48,24 @@ PLIST_GEN_DIR = build/generated-plists PLIST_GHOSTVM_TEMPLATE = macOS/GhostVM/VMApp-Info.template.plist PLIST_HELPER_TEMPLATE = macOS/GhostVMHelper/Info.template.plist PLIST_TOOLS_TEMPLATE = macOS/GhostTools/Sources/GhostTools/Resources/Info.template.plist +PLIST_FSKIT_TEMPLATE = macOS/GhostVMFS/Info.template.plist PLIST_GHOSTVM = $(PLIST_GEN_DIR)/GhostVM-Info.plist PLIST_HELPER = $(PLIST_GEN_DIR)/GhostVMHelper-Info.plist PLIST_TOOLS = $(PLIST_GEN_DIR)/GhostTools-Info.plist +PLIST_FSKIT = $(PLIST_GEN_DIR)/GhostVMFS-Info.plist + +# GhostHTTP3 arm64 dynamic framework (built via Rust/quiche) +GHOSTHTTP3_DIR = macOS/GhostHTTP3 +GHOSTHTTP3_FRAMEWORK = $(GHOSTHTTP3_DIR)/.build/artifacts/GhostHTTP3.framework BASE_VERSION := $(strip $(shell cat "$(VERSION_FILE)" 2>/dev/null)) ifeq ($(BASE_VERSION),) $(error Missing $(VERSION_FILE). Create it with a version like 1.85.0) endif +BASE_MAJOR_MINOR := $(word 1,$(subst ., ,$(BASE_VERSION))).$(word 2,$(subst ., ,$(BASE_VERSION))) -.PHONY: all cli app clean help run launch generate test uitest framework dist debug-dmg tools debug-tools dmg ghosttools-icon ghostvm-icon debug debug-export website website-build sparkle-tools sparkle-sign capture composite screenshots bump check-version render-plists prepare-app-plists prepare-tools-plist +.PHONY: all cli app clean help run launch ghostfile ghostfile-release ghostfile-dmg ghostfile-notarized ghostfile-notarized-dmg run-ghostfile run-ghostfile-release test-ghostfile generate test test-ghostbox-docker test-ghostbox-docker-compose uitest framework dist debug-dmg tools debug-tools dmg ghosttools-icon ghostvm-icon debug debug-export website website-build sparkle-tools sparkle-sign capture composite screenshots bump check-version render-plists prepare-app-plists prepare-tools-plist ghosthttp3-framework all: help @@ -55,7 +80,8 @@ render-plists: @for ITEM in \ "$(PLIST_GHOSTVM_TEMPLATE):$(PLIST_GHOSTVM)" \ "$(PLIST_HELPER_TEMPLATE):$(PLIST_HELPER)" \ - "$(PLIST_TOOLS_TEMPLATE):$(PLIST_TOOLS)"; do \ + "$(PLIST_TOOLS_TEMPLATE):$(PLIST_TOOLS)" \ + "$(PLIST_FSKIT_TEMPLATE):$(PLIST_FSKIT)"; do \ TEMPLATE="$${ITEM%%:*}"; \ OUT="$${ITEM#*:}"; \ cp "$$TEMPLATE" "$$OUT"; \ @@ -66,7 +92,7 @@ render-plists: prepare-app-plists: render-plists ifeq ($(INJECT_TIMESTAMP),1) @echo "Injecting build timestamp $(BUILD_TIMESTAMP) into GhostVM and GhostVMHelper..." - @for PLIST in "$(PLIST_GHOSTVM)" "$(PLIST_HELPER)"; do \ + @for PLIST in "$(PLIST_GHOSTVM)" "$(PLIST_HELPER)" "$(PLIST_FSKIT)"; do \ MAJOR_MINOR=$$(plutil -extract CFBundleShortVersionString raw "$$PLIST" | sed 's/\.[^.]*$$//'); \ plutil -replace CFBundleShortVersionString -string "$$MAJOR_MINOR.$(BUILD_TIMESTAMP)" "$$PLIST"; \ plutil -replace CFBundleVersion -string "$$MAJOR_MINOR.$(BUILD_TIMESTAMP)" "$$PLIST"; \ @@ -92,12 +118,25 @@ framework: $(XCODE_PROJECT) # Build the vmctl CLI (depends on framework) cli: $(XCODE_PROJECT) +ifeq ($(APP_SKIP_XCODE_SIGNING),1) + xcodebuild -project $(XCODE_PROJECT) \ + -scheme vmctl \ + -configuration $(XCODE_CONFIG) \ + -derivedDataPath $(BUILD_DIR) \ + CODE_SIGN_STYLE=Manual \ + CODE_SIGN_IDENTITY=- \ + DEVELOPMENT_TEAM= \ + CODE_SIGNING_ALLOWED=NO \ + CODE_SIGNING_REQUIRED=NO \ + build +else xcodebuild -project $(XCODE_PROJECT) \ -scheme vmctl \ -configuration $(XCODE_CONFIG) \ -derivedDataPath $(BUILD_DIR) \ DEVELOPMENT_TEAM="$(DEVELOPMENT_TEAM)" \ build +endif @echo "vmctl built at: $(BUILD_DIR)/Build/Products/$(XCODE_CONFIG)/vmctl.app/Contents/MacOS/vmctl" # Build the SwiftUI app via xcodebuild (includes GhostTools.dmg) @@ -244,10 +283,155 @@ run: debug launch: app open "$(BUILD_DIR)/Build/Products/$(XCODE_CONFIG)/$(APP_NAME).app" +# Build the GhostHTTP3 arm64 dynamic framework if not already built. +ghosthttp3-framework: + @"$(GHOSTHTTP3_DIR)/scripts/ensure-framework.sh" + +# Build the standalone GhostFile network filesystem demo and its FSKit extension. +ghostfile: $(XCODE_PROJECT) ghosthttp3-framework + @if [ -z "$(DEVELOPMENT_TEAM)" ]; then \ + echo "ERROR: DEVELOPMENT_TEAM is required to sign GhostFileFS.appex"; \ + echo "Set it in .env or run: make ghostfile DEVELOPMENT_TEAM=YOUR_TEAM_ID"; \ + exit 1; \ + fi + xcodebuild -project $(XCODE_PROJECT) \ + -scheme GhostFile \ + -configuration Debug \ + -derivedDataPath $(BUILD_DIR) \ + -allowProvisioningUpdates \ + DEVELOPMENT_TEAM="$(DEVELOPMENT_TEAM)" \ + build + +# Build the optimized arm64 GhostFile app used for performance and distribution testing. +ghostfile-release: $(XCODE_PROJECT) ghosthttp3-framework + @if [ -z "$(DEVELOPMENT_TEAM)" ]; then \ + echo "ERROR: DEVELOPMENT_TEAM is required to sign GhostFileFS.appex"; \ + echo "Set it in .env or run: make ghostfile-release DEVELOPMENT_TEAM=YOUR_TEAM_ID"; \ + exit 1; \ + fi + xcodebuild -project $(XCODE_PROJECT) \ + -scheme GhostFile \ + -configuration Release \ + -derivedDataPath $(BUILD_DIR) \ + -allowProvisioningUpdates \ + DEVELOPMENT_TEAM="$(DEVELOPMENT_TEAM)" \ + ARCHS=arm64 \ + ONLY_ACTIVE_ARCH=YES \ + build + +# Create a timestamp-versioned, Developer ID signed arm64 GhostFile DMG. +# This target deliberately does not notarize, which makes it useful for local +# release verification without requiring notary credentials. Distribute only +# the artifact produced by ghostfile-notarized-dmg. +ghostfile-dmg: $(XCODE_PROJECT) ghosthttp3-framework + @if [ -z "$(GHOSTFILE_SIGNING_TEAM)" ]; then \ + echo "ERROR: GHOSTFILE_SIGNING_TEAM (or a Developer ID identity) is required"; \ + exit 1; \ + fi + @if [ -z "$(GHOSTFILE_CODESIGN_ID)" ]; then \ + echo "ERROR: No Developer ID Application identity found in the keychain"; \ + exit 1; \ + fi + @echo "Building GhostFile $(GHOSTFILE_VERSION) ($(GHOSTFILE_BUILD_NUMBER))..." + rm -rf "$(GHOSTFILE_ARCHIVE)" "$(GHOSTFILE_EXPORT_DIR)" "$(GHOSTFILE_DERIVED_DATA)" + rm -f "$(GHOSTFILE_EXPORT_OPTIONS)" "$(GHOSTFILE_DMG)" + xcodebuild archive -project $(XCODE_PROJECT) \ + -scheme GhostFile \ + -configuration Release \ + -archivePath "$(GHOSTFILE_ARCHIVE)" \ + -derivedDataPath "$(GHOSTFILE_DERIVED_DATA)" \ + -allowProvisioningUpdates \ + DEVELOPMENT_TEAM="$(GHOSTFILE_SIGNING_TEAM)" \ + MARKETING_VERSION="$(GHOSTFILE_VERSION)" \ + CURRENT_PROJECT_VERSION="$(GHOSTFILE_BUILD_NUMBER)" \ + ARCHS=arm64 \ + ONLY_ACTIVE_ARCH=YES + cp macOS/GhostFile/DeveloperIDExportOptions.plist "$(GHOSTFILE_EXPORT_OPTIONS)" + plutil -replace teamID -string "$(GHOSTFILE_SIGNING_TEAM)" "$(GHOSTFILE_EXPORT_OPTIONS)" + xcodebuild -exportArchive \ + -archivePath "$(GHOSTFILE_ARCHIVE)" \ + -exportPath "$(GHOSTFILE_EXPORT_DIR)" \ + -exportOptionsPlist "$(GHOSTFILE_EXPORT_OPTIONS)" \ + -allowProvisioningUpdates + GHOSTFILE_CODESIGN_ID="$(GHOSTFILE_CODESIGN_ID)" \ + GHOSTFILE_DMG_README="macOS/GhostFile/DMG_README.txt" \ + GHOSTFILE_EXPECTED_VERSION="$(GHOSTFILE_VERSION)" \ + GHOSTFILE_EXPECTED_BUILD="$(GHOSTFILE_BUILD_NUMBER)" \ + scripts/package-ghostfile-dmg.sh \ + "$(GHOSTFILE_EXPORT_DIR)/GhostFile.app" \ + "$(GHOSTFILE_DMG)" \ + "GhostFile" + @# LaunchServices eagerly discovers FSKit extensions inside archives and + @# DerivedData. Remove non-installed registrations before returning. + @for APP in \ + "$(GHOSTFILE_ARCHIVE)/Products/Applications/GhostFile.app" \ + "$(GHOSTFILE_EXPORT_DIR)/GhostFile.app" \ + "$(GHOSTFILE_DERIVED_DATA)/Build/Products/Release/GhostFile.app"; do \ + if [ -d "$$APP" ]; then \ + /usr/bin/pluginkit -r "$$APP/Contents/Extensions/GhostFileFS.appex" >/dev/null 2>&1 || true; \ + $(GHOSTFILE_LSREGISTER) -u "$$APP" >/dev/null 2>&1 || true; \ + fi; \ + done + @if [ "$(GHOSTFILE_KEEP_INTERMEDIATES)" != "1" ]; then \ + rm -rf "$(GHOSTFILE_ARCHIVE)" "$(GHOSTFILE_EXPORT_DIR)" "$(GHOSTFILE_DERIVED_DATA)"; \ + rm -f "$(GHOSTFILE_EXPORT_OPTIONS)"; \ + fi + @if [ -d "$(GHOSTFILE_SHARED_DOWNLOADS)" ]; then \ + cp "$(GHOSTFILE_DMG)" "$(GHOSTFILE_SHARED_DOWNLOADS)/$$(basename "$(GHOSTFILE_DMG)")"; \ + fi + @echo "Signed, unnotarized GhostFile DMG: $(GHOSTFILE_DMG)" + +# Submit the signed DMG with notarytool, staple the accepted ticket, and run +# Gatekeeper checks. A Keychain profile is preferred; CI may use an App Store +# Connect API key or the legacy Apple-ID environment variables. +ghostfile-notarized-dmg: ghostfile-dmg + rm -f "$(GHOSTFILE_NOTARY_INPUT)" "$(GHOSTFILE_ARTIFACT)" + cp "$(GHOSTFILE_DMG)" "$(GHOSTFILE_NOTARY_INPUT)" + NOTARY_TIMEOUT="$(GHOSTFILE_NOTARY_TIMEOUT)" scripts/notarize-ghostfile-dmg.sh "$(GHOSTFILE_NOTARY_INPUT)" + mv "$(GHOSTFILE_NOTARY_INPUT)" "$(GHOSTFILE_ARTIFACT)" + @if [ -d "$(GHOSTFILE_SHARED_DOWNLOADS)" ]; then \ + cp "$(GHOSTFILE_ARTIFACT)" "$(GHOSTFILE_SHARED_DOWNLOADS)/$$(basename "$(GHOSTFILE_ARTIFACT)")"; \ + fi + @echo "Notarized GhostFile artifact: $(GHOSTFILE_ARTIFACT)" + +# Backward-compatible spelling for the old ZIP-producing target. +ghostfile-notarized: ghostfile-notarized-dmg + +run-ghostfile: ghostfile + open -n "$(BUILD_DIR)/Build/Products/Debug/GhostFile.app" + +run-ghostfile-release: ghostfile-release + open -n "$(BUILD_DIR)/Build/Products/Release/GhostFile.app" + +test-ghostfile: $(XCODE_PROJECT) ghosthttp3-framework + @if [ -z "$(DEVELOPMENT_TEAM)" ]; then \ + echo "ERROR: DEVELOPMENT_TEAM is required to sign the GhostFile test host and FSKit extension"; \ + echo "Set it in .env or run: make test-ghostfile DEVELOPMENT_TEAM=YOUR_TEAM_ID"; \ + exit 1; \ + fi + xcodebuild test -project $(XCODE_PROJECT) \ + -scheme GhostFileTests \ + -destination 'platform=macOS' \ + -derivedDataPath $(BUILD_DIR) \ + -allowProvisioningUpdates \ + DEVELOPMENT_TEAM="$(DEVELOPMENT_TEAM)" + @TEST_APP="$(BUILD_DIR)/Build/Products/Debug/GhostFile.app"; \ + if [ -d "$$TEST_APP" ]; then \ + /usr/bin/pluginkit -r "$$TEST_APP/Contents/Extensions/GhostFileFS.appex" >/dev/null 2>&1 || true; \ + $(GHOSTFILE_LSREGISTER) -u "$$TEST_APP" >/dev/null 2>&1 || true; \ + fi + # Run unit tests -test: $(XCODE_PROJECT) +test: $(XCODE_PROJECT) test-ghostbox-docker test-ghostbox-docker-compose xcodebuild test -project $(XCODE_PROJECT) -scheme GhostVMTests -destination 'platform=macOS' - swift test --package-path macOS/GhostTools --filter AsyncVSockIOTests + xcodebuild test -project $(XCODE_PROJECT) -scheme GhostboxRuntimeTests -destination 'platform=macOS' + swift test --package-path macOS/GhostTools + +test-ghostbox-docker: + sh scripts/test-ghostbox-docker.sh + +test-ghostbox-docker-compose: + sh scripts/test-ghostbox-docker-compose.sh # Run UI tests (excludes screenshot-capture tests; use 'make capture' for those) uitest: $(XCODE_PROJECT) @@ -308,20 +492,26 @@ GHOSTTOOLS_DIR = macOS/GhostTools GHOSTTOOLS_BUILD_DIR = $(BUILD_DIR)/GhostTools GHOSTTOOLS_APP = $(GHOSTTOOLS_BUILD_DIR)/GhostTools.app GHOSTTOOLS_DMG = $(BUILD_DIR)/GhostTools.dmg +GHOSTBOX_DOCKER = scripts/ghostbox-docker +GHOSTBOX_DOCKER_COMPOSE = scripts/ghostbox-docker-compose +# Virtualization.framework rejects compressed UDIF images as storage attachments. +GHOSTTOOLS_DMG_FORMAT = UDRW # Build GhostTools guest agent (.app bundle, signed) tools: ghosttools-icon @echo "Building GhostTools..." @$(MAKE) --no-print-directory prepare-tools-plist INJECT_TIMESTAMP=$(INJECT_TIMESTAMP) @# Force relink so the embedded __TEXT/__info_plist picks up the new timestamp - @rm -f "$(GHOSTTOOLS_BUILD_DIR)/release/GhostTools" + @rm -f "$(GHOSTTOOLS_BUILD_DIR)/release/GhostTools" "$(GHOSTTOOLS_BUILD_DIR)/release/ghostbox" swift build --package-path $(GHOSTTOOLS_DIR) --scratch-path $(GHOSTTOOLS_BUILD_DIR) -c release @# Assemble .app bundle @rm -rf "$(GHOSTTOOLS_APP)" @mkdir -p "$(GHOSTTOOLS_APP)/Contents/MacOS" @mkdir -p "$(GHOSTTOOLS_APP)/Contents/Resources" @cp "$(GHOSTTOOLS_BUILD_DIR)/release/GhostTools" "$(GHOSTTOOLS_APP)/Contents/MacOS/" + @cp "$(GHOSTTOOLS_BUILD_DIR)/release/ghostbox" "$(GHOSTTOOLS_APP)/Contents/MacOS/" vtool -set-build-version macos 26.0 26.0 -replace -output "$(GHOSTTOOLS_APP)/Contents/MacOS/GhostTools" "$(GHOSTTOOLS_APP)/Contents/MacOS/GhostTools" + vtool -set-build-version macos 26.0 26.0 -replace -output "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" @cp "$(PLIST_TOOLS)" "$(GHOSTTOOLS_APP)/Contents/Info.plist" @# Generate release notes from git log since last tag @LAST_TAG=$$(git describe --tags --abbrev=0 2>/dev/null); \ @@ -342,8 +532,13 @@ debug-tools: vtool -set-build-version macos 26.0 26.0 -replace \ -output $(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools-debug \ $(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools + vtool -set-build-version macos 26.0 26.0 -replace \ + -output $(GHOSTTOOLS_BUILD_DIR)/debug/ghostbox-debug \ + $(GHOSTTOOLS_BUILD_DIR)/debug/ghostbox codesign --force -s "-" $(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools-debug + codesign --force -s "-" $(GHOSTTOOLS_BUILD_DIR)/debug/ghostbox-debug @echo "Debug binary: $(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools-debug" + @echo "Debug binary: $(GHOSTTOOLS_BUILD_DIR)/debug/ghostbox-debug" @echo "Copy to guest and use: lldb GhostTools-debug" # Generate GhostTools .icns from source PNG @@ -400,13 +595,21 @@ $(GHOSTVM_ICON_ICNS): $(GHOSTVM_ICON_SRC) dmg: tools @echo "Creating GhostTools.dmg..." @rm -rf "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" - @mkdir -p "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" + @mkdir -p "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin" @cp -R "$(GHOSTTOOLS_APP)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/" @cp "$(GHOSTTOOLS_DIR)/README.txt" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/" + @mkdir -p "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/examples" + @cp -R examples/ghostbox "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/examples/" + @# Keep guest-facing command-line tools under one conventional directory. + @cp "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox" + @cp "$(GHOSTBOX_DOCKER)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox-docker" + @cp "$(GHOSTBOX_DOCKER_COMPOSE)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox-docker-compose" + codesign --force -s "$(GHOSTTOOLS_SIGN_ID)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox" @rm -f "$(GHOSTTOOLS_DMG)" - hdiutil makehybrid -o "$(GHOSTTOOLS_DMG)" \ - -hfs -hfs-volume-name "GhostTools" \ - "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" + hdiutil create -volname "GhostTools" \ + -srcfolder "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" \ + -ov -format $(GHOSTTOOLS_DMG_FORMAT) "$(GHOSTTOOLS_DMG)" + @xattr -c "$(GHOSTTOOLS_DMG)" @echo "GhostTools.dmg created at: $(GHOSTTOOLS_DMG)" # Sparkle tools for signing updates @@ -427,7 +630,8 @@ sparkle-tools: $(SPARKLE_TOOLS_DIR)/bin/sign_update # Distribution settings DIST_DIR = build/dist DMG_NAME = GhostVM -VERSION ?= $(shell git describe --tags --always 2>/dev/null || echo "dev") +VERSION ?= $(BASE_MAJOR_MINOR).$(BUILD_TIMESTAMP) +NOTARY_KEYCHAIN_PROFILE ?= # Auto-detect Developer ID Application identity for distribution DIST_CODESIGN_ID := $(shell security find-identity -v -p codesigning | grep "Developer ID Application" | head -1 | sed 's/.*"\(.*\)".*/\1/') @@ -436,7 +640,7 @@ DIST_CODESIGN_ID := $(shell security find-identity -v -p codesigning | grep "Dev # Note: If you get "Operation not permitted", grant Terminal Full Disk Access in # System Preferences > Privacy & Security > Full Disk Access dist: - $(MAKE) app cli INJECT_TIMESTAMP=0 APP_SKIP_XCODE_SIGNING=1 + $(MAKE) app cli INJECT_TIMESTAMP=1 BUILD_TIMESTAMP=$(BUILD_TIMESTAMP) APP_SKIP_XCODE_SIGNING=1 @# Verify we have a real signing identity for distribution @if [ -z "$(DIST_CODESIGN_ID)" ]; then \ echo "Error: No 'Developer ID Application' identity found in keychain."; \ @@ -445,14 +649,14 @@ dist: exit 1; \ fi @# Verify notarization credentials are set - @if [ -z "$(NOTARY_APPLE_ID)" ] || [ -z "$(NOTARY_TEAM_ID)" ] || [ -z "$(NOTARY_PASSWORD)" ]; then \ - echo "ERROR: Notarization requires NOTARY_APPLE_ID, NOTARY_TEAM_ID, and NOTARY_PASSWORD"; \ - echo "Set these in a .env file or as environment variables."; \ + @if [ -z "$(NOTARY_KEYCHAIN_PROFILE)" ] && { [ -z "$(NOTARY_APPLE_ID)" ] || [ -z "$(NOTARY_TEAM_ID)" ] || [ -z "$(NOTARY_PASSWORD)" ]; }; then \ + echo "ERROR: Notarization requires NOTARY_KEYCHAIN_PROFILE or Apple ID credentials."; \ + echo "Set a keychain profile, or NOTARY_APPLE_ID, NOTARY_TEAM_ID, and NOTARY_PASSWORD."; \ exit 1; \ fi @# Verify provisioning profile certificates match the signing identity (AMFI rejects @# apps where the profile cert doesn't match the signing cert, even if entitlements match) - @scripts/verify-profile-cert.sh "$(DIST_CODESIGN_ID)" $(APP_PROVISIONING_PROFILE) $(HELPER_PROVISIONING_PROFILE) $(VMCTL_PROVISIONING_PROFILE) + @scripts/verify-profile-cert.sh "$(DIST_CODESIGN_ID)" $(APP_PROVISIONING_PROFILE) $(HELPER_PROVISIONING_PROFILE) $(VMCTL_PROVISIONING_PROFILE) $(FSKIT_PROVISIONING_PROFILE) @echo "Creating distribution DMG (version $(VERSION))..." @echo "Signing with: $(DIST_CODESIGN_ID)" @rm -rf "$(DIST_DIR)" @@ -470,6 +674,9 @@ dist: test -f "$(HELPER_PROVISIONING_PROFILE)" || (echo "ERROR: HELPER_PROVISIONING_PROFILE not found: $(HELPER_PROVISIONING_PROFILE)" && exit 1); \ cp "$(HELPER_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/embedded.provisionprofile"; \ fi + @if [ -n "$(HELPER_PROVISIONING_PROFILE)" ]; then \ + cp "$(HELPER_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/ghostvm-container-runtime.xpc/Contents/embedded.provisionprofile"; \ + fi @if /usr/libexec/PlistBuddy -c "Print :com.apple.vm.networking" macOS/GhostVM/entitlements.plist >/dev/null 2>&1 && [ -z "$(APP_PROVISIONING_PROFILE)" ]; then \ echo "ERROR: APP_PROVISIONING_PROFILE is required for macOS/GhostVM/entitlements.plist (com.apple.vm.networking present)"; \ exit 1; \ @@ -486,6 +693,12 @@ dist: test -f "$(VMCTL_PROVISIONING_PROFILE)" || (echo "ERROR: VMCTL_PROVISIONING_PROFILE not found: $(VMCTL_PROVISIONING_PROFILE)" && exit 1); \ cp "$(VMCTL_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/vmctl.app/Contents/embedded.provisionprofile"; \ fi + @if [ -z "$(FSKIT_PROVISIONING_PROFILE)" ]; then \ + echo "ERROR: FSKIT_PROVISIONING_PROFILE is required for the GhostVMFS extension"; \ + exit 1; \ + fi + @test -f "$(FSKIT_PROVISIONING_PROFILE)" || (echo "ERROR: FSKIT_PROVISIONING_PROFILE not found: $(FSKIT_PROVISIONING_PROFILE)" && exit 1) + cp "$(FSKIT_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/embedded.provisionprofile" @# --- Inside-out code signing for notarization --- @echo "Signing nested components (inside-out)..." @# 1. Sign all embedded frameworks (GhostVMKit, NIO, etc.) in GhostVMHelper.app @@ -502,6 +715,34 @@ dist: codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ fi; \ done + @# 1c. Sign Debug dylibs and standalone container helpers + @for dylib in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/MacOS/"*.dylib; do \ + if [ -f "$$dylib" ]; then \ + echo " Signing $$(basename $$dylib) (in Helper)"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ + fi; \ + done + @if [ -f "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/Helpers/ghostvm-image-fetch" ]; then \ + echo " Signing ghostvm-image-fetch"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" \ + "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/Helpers/ghostvm-image-fetch"; \ + fi + @# Sign the runtime XPC service explicitly (entitlements + helper profile) BEFORE the + @# generic XPC loop so the later generic re-sign cannot strip its vmnet entitlements. + @if [ -d "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/ghostvm-container-runtime.xpc" ]; then \ + echo " Signing ghostvm-container-runtime.xpc"; \ + codesign --force --options runtime --timestamp \ + --entitlements macOS/GhostVMContainerRuntime/entitlements.plist \ + -s "$(DIST_CODESIGN_ID)" \ + "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/ghostvm-container-runtime.xpc"; \ + fi + @# Sign remaining (ordinary) XPC services generically, skipping the runtime XPC + @for xpc in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/"*.xpc; do \ + if [ -d "$$xpc" ] && [ "$$(basename "$$xpc")" != "ghostvm-container-runtime.xpc" ]; then \ + echo " Signing $$(basename $$xpc) (in Helper)"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$xpc"; \ + fi; \ + done @# 2. Sign GhostVMHelper.app (with its own entitlements) @echo " Signing GhostVMHelper.app" codesign --force --options runtime --timestamp \ @@ -539,6 +780,32 @@ dist: codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ fi; \ done + @# 4b. Sign the FSKit extension before signing its containing app. + @FOUND_GHOST_HTTP=0; for fw in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/Frameworks/"GhostHTTP_*.framework; do \ + if [ -d "$$fw" ]; then FOUND_GHOST_HTTP=1; fi; \ + done; \ + if [ "$$FOUND_GHOST_HTTP" != "1" ]; then \ + echo "ERROR: GhostVMFS is missing its GhostHTTP package framework"; exit 1; \ + fi + @test ! -f "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/MacOS/GhostVMFS.debug.dylib" || \ + (echo "ERROR: GhostVMFS was packaged from a Debug build"; exit 1) + @for fw in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/Frameworks/"*.framework; do \ + if [ -d "$$fw" ]; then \ + echo " Signing $$(basename $$fw) (in GhostVMFS)"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$fw"; \ + fi; \ + done + @for dylib in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/MacOS/"*.dylib; do \ + if [ -f "$$dylib" ]; then \ + echo " Signing $$(basename $$dylib) (in GhostVMFS)"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ + fi; \ + done + @echo " Signing GhostVMFS.appex" + codesign --force --options runtime --timestamp \ + --entitlements macOS/GhostVMFS/entitlements.plist \ + -s "$(DIST_CODESIGN_ID)" \ + "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex" @# 5. Sign vmctl.app (frameworks, then the bundle itself with entitlements) @for fw in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/vmctl.app/Contents/Frameworks/"*.framework; do \ if [ -d "$$fw" ]; then \ @@ -552,6 +819,12 @@ dist: codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ fi; \ done + @for dylib in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/vmctl.app/Contents/MacOS/"*.dylib; do \ + if [ -f "$$dylib" ]; then \ + echo " Signing $$(basename $$dylib) (in vmctl)"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ + fi; \ + done @echo " Signing vmctl.app" codesign --force --options runtime --timestamp \ --entitlements macOS/GhostVM/vmctl/entitlements.plist \ @@ -560,16 +833,29 @@ dist: @# 5b. Re-create GhostTools.dmg with Developer ID signing for notarization @echo " Re-signing GhostTools for distribution..." @rm -rf "$(DIST_DIR)/ghosttools-stage" - @mkdir -p "$(DIST_DIR)/ghosttools-stage" + @mkdir -p "$(DIST_DIR)/ghosttools-stage/bin" @cp -R "$(GHOSTTOOLS_APP)" "$(DIST_DIR)/ghosttools-stage/" @cp "$(GHOSTTOOLS_DIR)/README.txt" "$(DIST_DIR)/ghosttools-stage/" + @mkdir -p "$(DIST_DIR)/ghosttools-stage/examples" + @cp -R examples/ghostbox "$(DIST_DIR)/ghosttools-stage/examples/" + @cp "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox" + @cp "$(GHOSTBOX_DOCKER)" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox-docker" + @cp "$(GHOSTBOX_DOCKER_COMPOSE)" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox-docker-compose" codesign --force --options runtime --timestamp --deep --entitlements "$(GHOSTTOOLS_DIR)/Sources/GhostTools/Resources/entitlements.plist" -s "$(DIST_CODESIGN_ID)" "$(DIST_DIR)/ghosttools-stage/GhostTools.app" + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox" @rm -f "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" - hdiutil makehybrid -o "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" \ - -hfs -hfs-volume-name "GhostTools" \ - "$(DIST_DIR)/ghosttools-stage" + hdiutil create -volname "GhostTools" \ + -srcfolder "$(DIST_DIR)/ghosttools-stage" \ + -ov -format $(GHOSTTOOLS_DMG_FORMAT) "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" + @xattr -c "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" @rm -rf "$(DIST_DIR)/ghosttools-stage" @# 6. Sign the main app bundle (top-level, with entitlements) + @for dylib in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/MacOS/"*.dylib; do \ + if [ -f "$$dylib" ]; then \ + echo " Signing $$(basename $$dylib) (in $(APP_NAME))"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ + fi; \ + done @echo " Signing $(APP_NAME).app" codesign --force --options runtime --timestamp \ --entitlements macOS/GhostVM/entitlements.plist \ @@ -590,11 +876,15 @@ dist: codesign --force --timestamp -s "$(DIST_CODESIGN_ID)" "$(DIST_DIR)/$(DMG_NAME)-$(VERSION).dmg" @echo "DMG signed with: $(DIST_CODESIGN_ID)" @# --- Notarization --- - xcrun notarytool submit "$(DIST_DIR)/$(DMG_NAME)-$(VERSION).dmg" \ - --apple-id "$(NOTARY_APPLE_ID)" \ - --team-id "$(NOTARY_TEAM_ID)" \ - --password "$(NOTARY_PASSWORD)" \ - --wait + @if [ -n "$(NOTARY_KEYCHAIN_PROFILE)" ]; then \ + xcrun notarytool submit "$(DIST_DIR)/$(DMG_NAME)-$(VERSION).dmg" \ + --keychain-profile "$(NOTARY_KEYCHAIN_PROFILE)" --wait; \ + else \ + xcrun notarytool submit "$(DIST_DIR)/$(DMG_NAME)-$(VERSION).dmg" \ + --apple-id "$(NOTARY_APPLE_ID)" \ + --team-id "$(NOTARY_TEAM_ID)" \ + --password "$(NOTARY_PASSWORD)" --wait; \ + fi xcrun stapler staple "$(DIST_DIR)/$(DMG_NAME)-$(VERSION).dmg" @echo "Distribution created: $(DIST_DIR)/$(DMG_NAME)-$(VERSION).dmg" @echo "vmctl is at: $(APP_NAME).app/Contents/PlugIns/Helpers/vmctl.app/Contents/MacOS/vmctl" @@ -605,67 +895,80 @@ dist: debug-dmg: $(XCODE_PROJECT) ghostvm-icon ghosttools-icon @# Build GhostTools (debug) @$(MAKE) --no-print-directory prepare-tools-plist INJECT_TIMESTAMP=1 BUILD_TIMESTAMP=$(BUILD_TIMESTAMP) - @rm -f "$(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools" + @rm -f "$(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools" "$(GHOSTTOOLS_BUILD_DIR)/debug/ghostbox" swift build --package-path $(GHOSTTOOLS_DIR) --scratch-path $(GHOSTTOOLS_BUILD_DIR) -c debug @rm -rf "$(GHOSTTOOLS_APP)" @mkdir -p "$(GHOSTTOOLS_APP)/Contents/MacOS" "$(GHOSTTOOLS_APP)/Contents/Resources" @cp "$(GHOSTTOOLS_BUILD_DIR)/debug/GhostTools" "$(GHOSTTOOLS_APP)/Contents/MacOS/" + @cp "$(GHOSTTOOLS_BUILD_DIR)/debug/ghostbox" "$(GHOSTTOOLS_APP)/Contents/MacOS/" vtool -set-build-version macos 26.0 26.0 -replace -output "$(GHOSTTOOLS_APP)/Contents/MacOS/GhostTools" "$(GHOSTTOOLS_APP)/Contents/MacOS/GhostTools" + vtool -set-build-version macos 26.0 26.0 -replace -output "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" @cp "$(PLIST_TOOLS)" "$(GHOSTTOOLS_APP)/Contents/Info.plist" @cp "$(GHOSTTOOLS_ICON_ICNS)" "$(GHOSTTOOLS_APP)/Contents/Resources/" codesign --force --deep --entitlements "$(GHOSTTOOLS_DIR)/Sources/GhostTools/Resources/entitlements.plist" -s "$(GHOSTTOOLS_SIGN_ID)" "$(GHOSTTOOLS_APP)" @# Package GhostTools.dmg @rm -rf "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" - @mkdir -p "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" + @mkdir -p "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin" @cp -R "$(GHOSTTOOLS_APP)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/" @cp "$(GHOSTTOOLS_DIR)/README.txt" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/" + @mkdir -p "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/examples" + @cp -R examples/ghostbox "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/examples/" + @cp "$(GHOSTTOOLS_APP)/Contents/MacOS/ghostbox" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox" + @cp "$(GHOSTBOX_DOCKER)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox-docker" + @cp "$(GHOSTBOX_DOCKER_COMPOSE)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox-docker-compose" + codesign --force -s "$(GHOSTTOOLS_SIGN_ID)" "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage/bin/ghostbox" @rm -f "$(GHOSTTOOLS_DMG)" - hdiutil makehybrid -o "$(GHOSTTOOLS_DMG)" \ - -hfs -hfs-volume-name "GhostTools" \ - "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" - @# Build app + cli (debug) + hdiutil create -volname "GhostTools" \ + -srcfolder "$(GHOSTTOOLS_BUILD_DIR)/dmg-stage" \ + -ov -format $(GHOSTTOOLS_DMG_FORMAT) "$(GHOSTTOOLS_DMG)" + @# Use Release products even for the timestamped debug DMG. A Debug FSKit + @# extension contains Xcode trampoline dylibs and is not a distributable module. @$(MAKE) --no-print-directory prepare-app-plists INJECT_TIMESTAMP=1 BUILD_TIMESTAMP=$(BUILD_TIMESTAMP) - xcodebuild -project $(XCODE_PROJECT) -scheme $(APP_NAME) -configuration Debug -derivedDataPath $(BUILD_DIR) \ + xcodebuild -project $(XCODE_PROJECT) -scheme $(APP_NAME) -configuration $(DEBUG_DMG_CONFIGURATION) -derivedDataPath $(BUILD_DIR) \ CODE_SIGN_STYLE=Manual \ CODE_SIGN_IDENTITY=- \ DEVELOPMENT_TEAM= \ CODE_SIGNING_ALLOWED=NO \ CODE_SIGNING_REQUIRED=NO \ build - xcodebuild -project $(XCODE_PROJECT) -scheme vmctl -configuration Debug -derivedDataPath $(BUILD_DIR) \ + xcodebuild -project $(XCODE_PROJECT) -scheme vmctl -configuration $(DEBUG_DMG_CONFIGURATION) -derivedDataPath $(BUILD_DIR) \ CODE_SIGN_STYLE=Manual \ CODE_SIGN_IDENTITY=- \ DEVELOPMENT_TEAM= \ CODE_SIGNING_ALLOWED=NO \ CODE_SIGNING_REQUIRED=NO \ build - @# Copy resources into debug app - @mkdir -p "$(BUILD_DIR)/Build/Products/Debug/$(APP_NAME).app/Contents/Resources" - @cp macOS/GhostVM/Resources/ghostvm.png "$(BUILD_DIR)/Build/Products/Debug/$(APP_NAME).app/Contents/Resources/" - @cp macOS/GhostVM/Resources/ghostvm-dark.png "$(BUILD_DIR)/Build/Products/Debug/$(APP_NAME).app/Contents/Resources/" - @cp build/GhostVMIcon.icns "$(BUILD_DIR)/Build/Products/Debug/$(APP_NAME).app/Contents/Resources/GhostVMIcon.icns" - @cp "$(GHOSTTOOLS_DMG)" "$(BUILD_DIR)/Build/Products/Debug/$(APP_NAME).app/Contents/Resources/" + @# Copy resources into the timestamped app. + @mkdir -p "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app/Contents/Resources" + @cp macOS/GhostVM/Resources/ghostvm.png "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app/Contents/Resources/" + @cp macOS/GhostVM/Resources/ghostvm-dark.png "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app/Contents/Resources/" + @cp build/GhostVMIcon.icns "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app/Contents/Resources/GhostVMIcon.icns" + @cp "$(GHOSTTOOLS_DMG)" "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app/Contents/Resources/" @# Verify we have a real signing identity for distribution @if [ -z "$(DIST_CODESIGN_ID)" ]; then \ echo "Error: No 'Developer ID Application' identity found in keychain."; \ exit 1; \ fi - @# Verify notarization credentials are set - @if [ -z "$(NOTARY_APPLE_ID)" ] || [ -z "$(NOTARY_TEAM_ID)" ] || [ -z "$(NOTARY_PASSWORD)" ]; then \ - echo "ERROR: Notarization requires NOTARY_APPLE_ID, NOTARY_TEAM_ID, and NOTARY_PASSWORD"; \ + @# Verify notarization credentials are set unless a local-only artifact was requested. + @if [ "$(SKIP_NOTARIZATION)" != "1" ] && [ -z "$(NOTARY_KEYCHAIN_PROFILE)" ] && { [ -z "$(NOTARY_APPLE_ID)" ] || [ -z "$(NOTARY_TEAM_ID)" ] || [ -z "$(NOTARY_PASSWORD)" ]; }; then \ + echo "ERROR: Notarization requires NOTARY_KEYCHAIN_PROFILE or Apple ID credentials."; \ + echo "Set SKIP_NOTARIZATION=1 to create a signed local-testing DMG."; \ exit 1; \ fi - @scripts/verify-profile-cert.sh "$(DIST_CODESIGN_ID)" $(APP_PROVISIONING_PROFILE) $(HELPER_PROVISIONING_PROFILE) $(VMCTL_PROVISIONING_PROFILE) + @scripts/verify-profile-cert.sh "$(DIST_CODESIGN_ID)" $(APP_PROVISIONING_PROFILE) $(HELPER_PROVISIONING_PROFILE) $(VMCTL_PROVISIONING_PROFILE) $(FSKIT_PROVISIONING_PROFILE) $(eval DEBUG_VERSION := $(strip $(shell echo $(BASE_VERSION) | sed 's/\.[^.]*$$//')).$(BUILD_TIMESTAMP)) @echo "Creating debug DMG (version $(DEBUG_VERSION))..." @echo "Signing with: $(DIST_CODESIGN_ID)" @rm -rf "$(DIST_DIR)" @mkdir -p "$(DIST_DIR)/dmg-stage" - cp -R "$(BUILD_DIR)/Build/Products/Debug/$(APP_NAME).app" "$(DIST_DIR)/dmg-stage/" - cp -R "$(BUILD_DIR)/Build/Products/Debug/vmctl.app" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/" + cp -R "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app" "$(DIST_DIR)/dmg-stage/" + cp -R "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/vmctl.app" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/" + @pluginkit -r "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex" >/dev/null 2>&1 || true + @"$(GHOSTFILE_LSREGISTER)" -u "$(BUILD_DIR)/Build/Products/$(DEBUG_DMG_CONFIGURATION)/$(APP_NAME).app" >/dev/null 2>&1 || true @if [ -n "$(HELPER_PROVISIONING_PROFILE)" ]; then \ test -f "$(HELPER_PROVISIONING_PROFILE)" || (echo "ERROR: HELPER_PROVISIONING_PROFILE not found: $(HELPER_PROVISIONING_PROFILE)" && exit 1); \ cp "$(HELPER_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/embedded.provisionprofile"; \ + cp "$(HELPER_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/ghostvm-container-runtime.xpc/Contents/embedded.provisionprofile"; \ fi @if [ -n "$(APP_PROVISIONING_PROFILE)" ]; then \ test -f "$(APP_PROVISIONING_PROFILE)" || (echo "ERROR: APP_PROVISIONING_PROFILE not found: $(APP_PROVISIONING_PROFILE)" && exit 1); \ @@ -675,6 +978,10 @@ debug-dmg: $(XCODE_PROJECT) ghostvm-icon ghosttools-icon test -f "$(VMCTL_PROVISIONING_PROFILE)" || (echo "ERROR: VMCTL_PROVISIONING_PROFILE not found: $(VMCTL_PROVISIONING_PROFILE)" && exit 1); \ cp "$(VMCTL_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/vmctl.app/Contents/embedded.provisionprofile"; \ fi + @if [ -n "$(FSKIT_PROVISIONING_PROFILE)" ]; then \ + test -f "$(FSKIT_PROVISIONING_PROFILE)" || (echo "ERROR: FSKIT_PROVISIONING_PROFILE not found: $(FSKIT_PROVISIONING_PROFILE)" && exit 1); \ + cp "$(FSKIT_PROVISIONING_PROFILE)" "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/embedded.provisionprofile"; \ + fi @# Sign GhostVMHelper (frameworks, MacOS dylibs, then bundle) @for fw in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/Frameworks/"*.framework; do \ if [ -e "$$fw" ]; then \ @@ -692,6 +999,27 @@ debug-dmg: $(XCODE_PROJECT) ghostvm-icon ghosttools-icon codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ fi; \ done + @if [ -f "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/Helpers/ghostvm-image-fetch" ]; then \ + echo " Signing ghostvm-image-fetch"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" \ + "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/Helpers/ghostvm-image-fetch"; \ + fi + @# Sign the runtime XPC service explicitly (entitlements + helper profile) BEFORE the + @# helper so its vmnet entitlements are not stripped by a later generic re-sign. + @if [ -d "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/ghostvm-container-runtime.xpc" ]; then \ + echo " Signing ghostvm-container-runtime.xpc"; \ + codesign --force --options runtime --timestamp \ + --entitlements macOS/GhostVMContainerRuntime/entitlements.plist \ + -s "$(DIST_CODESIGN_ID)" \ + "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/ghostvm-container-runtime.xpc"; \ + fi + @# Sign remaining (ordinary) XPC services in the helper generically + @for xpc in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/PlugIns/Helpers/GhostVMHelper.app/Contents/XPCServices/"*.xpc; do \ + if [ -e "$$xpc" ] && [ "$$(basename "$$xpc")" != "ghostvm-container-runtime.xpc" ]; then \ + echo " Signing $$(basename $$xpc) (in Helper)"; \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$xpc"; \ + fi; \ + done codesign --force --options runtime --timestamp \ --entitlements macOS/GhostVMHelper/entitlements.plist \ -s "$(DIST_CODESIGN_ID)" \ @@ -739,17 +1067,48 @@ debug-dmg: $(XCODE_PROJECT) ghostvm-icon ghosttools-icon codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ fi; \ done + @# Sign the FSKit extension before its containing app. + @FOUND_GHOST_HTTP=0; for fw in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/Frameworks/"GhostHTTP_*.framework; do \ + if [ -d "$$fw" ]; then FOUND_GHOST_HTTP=1; fi; \ + done; \ + if [ "$$FOUND_GHOST_HTTP" != "1" ]; then \ + echo "ERROR: GhostVMFS is missing its GhostHTTP package framework"; exit 1; \ + fi + @test ! -f "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/MacOS/GhostVMFS.debug.dylib" || \ + (echo "ERROR: GhostVMFS was packaged from a Debug build"; exit 1) + @for fw in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/Frameworks/"*.framework; do \ + if [ -e "$$fw" ]; then \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$fw"; \ + fi; \ + done + @for dylib in "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex/Contents/MacOS/"*.dylib; do \ + if [ -e "$$dylib" ]; then \ + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$$dylib"; \ + fi; \ + done + codesign --force --options runtime --timestamp \ + --entitlements macOS/GhostVMFS/entitlements.plist \ + -s "$(DIST_CODESIGN_ID)" \ + "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Extensions/GhostVMFS.appex" @# Re-sign GhostTools.dmg inside the app bundle - @mkdir -p "$(DIST_DIR)/ghosttools-stage" + @mkdir -p "$(DIST_DIR)/ghosttools-stage/bin" @hdiutil attach "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" -mountpoint "$(DIST_DIR)/ghosttools-mount" -nobrowse @ditto "$(DIST_DIR)/ghosttools-mount/GhostTools.app" "$(DIST_DIR)/ghosttools-stage/GhostTools.app" @hdiutil detach "$(DIST_DIR)/ghosttools-mount" + @cp "$(GHOSTTOOLS_DIR)/README.txt" "$(DIST_DIR)/ghosttools-stage/README.txt" + @mkdir -p "$(DIST_DIR)/ghosttools-stage/examples" + @cp -R examples/ghostbox "$(DIST_DIR)/ghosttools-stage/examples/" @xattr -cr "$(DIST_DIR)/ghosttools-stage/GhostTools.app" codesign --force --options runtime --timestamp --deep --entitlements "$(GHOSTTOOLS_DIR)/Sources/GhostTools/Resources/entitlements.plist" -s "$(DIST_CODESIGN_ID)" "$(DIST_DIR)/ghosttools-stage/GhostTools.app" + @# Restore the guest-facing bin directory after re-signing the app bundle. + @cp "$(DIST_DIR)/ghosttools-stage/GhostTools.app/Contents/MacOS/ghostbox" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox" + @cp "$(GHOSTBOX_DOCKER)" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox-docker" + @cp "$(GHOSTBOX_DOCKER_COMPOSE)" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox-docker-compose" + codesign --force --options runtime --timestamp -s "$(DIST_CODESIGN_ID)" "$(DIST_DIR)/ghosttools-stage/bin/ghostbox" @rm -f "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" - hdiutil makehybrid -o "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" \ - -hfs -hfs-volume-name "GhostTools" \ - "$(DIST_DIR)/ghosttools-stage" + hdiutil create -volname "GhostTools" \ + -srcfolder "$(DIST_DIR)/ghosttools-stage" \ + -ov -format $(GHOSTTOOLS_DMG_FORMAT) "$(DIST_DIR)/dmg-stage/$(APP_NAME).app/Contents/Resources/GhostTools.dmg" @rm -rf "$(DIST_DIR)/ghosttools-stage" @# Strip xattrs and sign main app MacOS dylibs then bundle @xattr -cr "$(DIST_DIR)/dmg-stage/$(APP_NAME).app" @@ -771,13 +1130,20 @@ debug-dmg: $(XCODE_PROJECT) ghostvm-icon ghosttools-icon -ov -format UDZO "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" @rm -rf "$(DIST_DIR)/dmg-stage" codesign --force --timestamp -s "$(DIST_CODESIGN_ID)" "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" - @# Notarize - xcrun notarytool submit "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" \ - --apple-id "$(NOTARY_APPLE_ID)" \ - --team-id "$(NOTARY_TEAM_ID)" \ - --password "$(NOTARY_PASSWORD)" \ - --wait - xcrun stapler staple "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" + @# Notarize unless this is an explicitly local-only build. + @if [ "$(SKIP_NOTARIZATION)" = "1" ]; then \ + echo "Skipping notarization (local-testing DMG)."; \ + elif [ -n "$(NOTARY_KEYCHAIN_PROFILE)" ]; then \ + xcrun notarytool submit "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" \ + --keychain-profile "$(NOTARY_KEYCHAIN_PROFILE)" --wait && \ + xcrun stapler staple "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg"; \ + else \ + xcrun notarytool submit "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" \ + --apple-id "$(NOTARY_APPLE_ID)" \ + --team-id "$(NOTARY_TEAM_ID)" \ + --password "$(NOTARY_PASSWORD)" --wait && \ + xcrun stapler staple "$(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg"; \ + fi @echo "Debug distribution created: $(DIST_DIR)/$(DMG_NAME)-$(DEBUG_VERSION).dmg" @echo "vmctl is at: $(APP_NAME).app/Contents/PlugIns/Helpers/vmctl.app/Contents/MacOS/vmctl" @@ -799,7 +1165,7 @@ website-build: # Bump canonical app version used to render generated plists # Usage: make bump VERSION=1.2.0 bump: - @if [ -z "$(VERSION)" ] || [ "$(VERSION)" = "$$(git describe --tags --always 2>/dev/null || echo dev)" ]; then \ + @if [ -z "$(VERSION)" ] || [ "$(VERSION)" = "$(BASE_MAJOR_MINOR).$(BUILD_TIMESTAMP)" ]; then \ echo "Usage: make bump VERSION=x.y.z"; exit 1; \ fi @echo "Bumping canonical version to $(VERSION)..." @@ -812,7 +1178,7 @@ bump: check-version: @BASE="$$(cat "$(VERSION_FILE)")"; \ echo "Canonical version: $$BASE"; \ - for PLIST in "$(PLIST_GHOSTVM)" "$(PLIST_HELPER)" "$(PLIST_TOOLS)"; do \ + for PLIST in "$(PLIST_GHOSTVM)" "$(PLIST_HELPER)" "$(PLIST_TOOLS)" "$(PLIST_FSKIT)"; do \ if [ -f "$$PLIST" ]; then \ CUR=$$(plutil -extract CFBundleShortVersionString raw "$$PLIST"); \ echo " $$(basename "$$PLIST"): $$CUR"; \ @@ -834,6 +1200,12 @@ help: @echo " make debug-export - Debug build ad-hoc signed (no Xcode needed on target)" @echo " make run - Build and run attached to terminal" @echo " make launch - Build and launch detached" + @echo " make ghostfile - Build GhostFile.app and its FSKit extension" + @echo " make ghostfile-dmg - Create a Developer ID signed GhostFile DMG (not notarized)" + @echo " make ghostfile-notarized-dmg - Create, notarize, staple, and verify the GhostFile DMG" + @echo " make ghosthttp3-framework - Build the GhostHTTP3 arm64 dynamic framework" + @echo " make run-ghostfile - Build and launch another GhostFile instance" + @echo " make test-ghostfile - Run GhostFile protocol and server tests" @echo " make test - Run unit tests" @echo " make uitest - Run UI tests" @echo " make capture - Capture raw screenshots from UI tests → build/screenshots/" @@ -848,7 +1220,7 @@ help: @echo " make sparkle-sign - Sign DMG for Sparkle auto-updates" @echo " make website - Run Next.js dev server (Website/)" @echo " make website-build - Build Next.js site for production" - @echo " make bump VERSION=x.y.z - Bump version in all 3 targets" + @echo " make bump VERSION=x.y.z - Bump version in all versioned targets" @echo " make check-version - Verify all targets have the same version" @echo " make clean - Remove build artifacts and generated project" @echo "" @@ -856,9 +1228,13 @@ help: @echo " DEVELOPMENT_TEAM - Apple Developer team ID (via .env file, see .env.example)" @echo " CODESIGN_ID - Code signing identity (default: Apple Development)" @echo " XCODE_CONFIG - Xcode build configuration (default: Release)" - @echo " VERSION - Version for DMG (default: git describe)" + @echo " VERSION - Version for DMG (default: MAJOR.MINOR.YYYYMMDDHHMMSS)" + @echo " GHOSTFILE_VERSION - GhostFile release version (default: 1.0.TIMESTAMP)" + @echo " GHOSTFILE_BUILD_NUMBER - Monotonic GhostFile bundle build number" @echo "" @echo "Notarization (via .env file or environment):" + @echo " NOTARY_KEYCHAIN_PROFILE - Preferred notarytool Keychain profile" + @echo " NOTARY_KEY_FILE / NOTARY_KEY_ID / NOTARY_ISSUER_ID - CI API key" @echo " NOTARY_APPLE_ID - Apple ID for notarization" @echo " NOTARY_TEAM_ID - Team ID for notarization" @echo " NOTARY_PASSWORD - App-specific password for notarization" diff --git a/Packages/GhostHTTP/Sources/GhostHTTP/GhostHTTP.swift b/Packages/GhostHTTP/Sources/GhostHTTP/GhostHTTP.swift index 19b8581..69a2e03 100644 --- a/Packages/GhostHTTP/Sources/GhostHTTP/GhostHTTP.swift +++ b/Packages/GhostHTTP/Sources/GhostHTTP/GhostHTTP.swift @@ -22,6 +22,7 @@ public enum HTTPQueryParser { public enum HTTPStatus: Int, Sendable { case switchingProtocols = 101 case ok = 200 + case partialContent = 206 case created = 201 case noContent = 204 case badRequest = 400 @@ -30,17 +31,21 @@ public enum HTTPStatus: Int, Sendable { case notFound = 404 case methodNotAllowed = 405 case requestTimeout = 408 + case conflict = 409 case payloadTooLarge = 413 + case rangeNotSatisfiable = 416 case headerTooLarge = 431 case badGateway = 502 case serviceUnavailable = 503 case gatewayTimeout = 504 + case insufficientStorage = 507 case internalServerError = 500 public var reasonPhrase: String { switch self { case .switchingProtocols: return "Switching Protocols" case .ok: return "OK" + case .partialContent: return "Partial Content" case .created: return "Created" case .noContent: return "No Content" case .badRequest: return "Bad Request" @@ -49,11 +54,14 @@ public enum HTTPStatus: Int, Sendable { case .notFound: return "Not Found" case .methodNotAllowed: return "Method Not Allowed" case .requestTimeout: return "Request Timeout" + case .conflict: return "Conflict" case .payloadTooLarge: return "Payload Too Large" + case .rangeNotSatisfiable: return "Range Not Satisfiable" case .headerTooLarge: return "Request Header Fields Too Large" case .badGateway: return "Bad Gateway" case .serviceUnavailable: return "Service Unavailable" case .gatewayTimeout: return "Gateway Timeout" + case .insufficientStorage: return "Insufficient Storage" case .internalServerError: return "Internal Server Error" } } @@ -682,7 +690,9 @@ public enum HTTPCodec { throw HTTPError.headerTooLarge(maxBytes: maxHeaderBytes) } - let count = Darwin.read(fd, &chunk, chunk.count) + let count = chunk.withUnsafeMutableBytes { buffer in + Darwin.read(fd, buffer.baseAddress, buffer.count) + } if count > 0 { buffer.append(contentsOf: chunk[0.. Latest Release   - Platform + Platform   Architecture

@@ -52,7 +52,7 @@ GhostVM is a native macOS app for creating and managing macOS virtual machines o 2. Open the DMG and drag **GhostVM.app** to your Applications folder 3. Launch GhostVM and create your first workspace -**Requirements:** macOS 15+ (Sequoia) on Apple Silicon (M1 or later) +**Requirements:** macOS 26+ (Tahoe) on Apple Silicon (M1 or later) ## CLI Usage @@ -95,7 +95,7 @@ vmctl remote --name dev apps ## Building from Source -**Requirements:** Xcode 15+ and [XcodeGen](https://github.com/yonaskolb/XcodeGen) +**Requirements:** Xcode 26+ and [XcodeGen](https://github.com/yonaskolb/XcodeGen) ```bash brew install xcodegen diff --git a/RUNTIME_FOUNDATIONS.md b/RUNTIME_FOUNDATIONS.md new file mode 100644 index 0000000..18fbacc --- /dev/null +++ b/RUNTIME_FOUNDATIONS.md @@ -0,0 +1,92 @@ +# GhostVM Runtime Foundations + +GhostVM's VM and container features share control-plane concepts, but they do +not share packet processors or guest compatibility APIs. + +```text +Docker CLI / Compose + | + v +GhostTools frontend and internal CLI + | + v +container runtime protocol over vsock + | + v +GhostVMHelper + | + +-- ghostvm-image-fetch (short-lived) + | +-- kernel and ImageStore preparation + | + +-- GhostVMContainerRuntime.xpc (one per GhostVMHelper) + +-- all Containerization container VMs +``` + +GhostVM does not start `container-apiserver`, `container-core-images`, or a +global container daemon. A short-lived `ghostvm-image-fetch` subprocess prepares +the kernel, requested image, and vminit image in a per-VM application-support +root. After it exits, the helper's application-scoped +`GhostVMContainerRuntime.xpc` opens that store without pulling and calls +`ContainerManager` and `LinuxContainer` directly. One runtime process hosts all +container VMs for its containing helper. Lifecycle control uses raw XPC while +standard streams use file descriptors transferred in the XPC run request. + +## Network management + +`NetworkManager` owns backend-neutral network definitions and workload +endpoints. Both VM NICs and container interfaces attach through this control +plane. + +The initial backend drivers are deliberately distinct: + +- `virtualization-nat` uses `VZNATNetworkDeviceAttachment` when host containers + are disabled. +- `bridged` uses a selected host interface. +- `vmnet-shared` is active for container-enabled NAT VMs. `GhostVMHelper` + reserves one `VMNET_SHARED_MODE` network per macOS VM, reserves `.2` for the + VM through DHCP, and allocates `.3+` statically to that VM's containers. The + helper sends the opaque vmnet serialization and allocated interface settings + directly to its runtime XPC service with every run. The runtime reconstructs + the exact network before creating the container VM attachment. Reconstruction + failure fails the run; it never silently creates an unrelated NAT network. + +The multi-NIC configuration concepts from PR #144 can be adapted to these +types. Its custom ARP, DHCP, DNS, NAT, and TCP implementation is not part of the +runtime foundation. + +## Content store + +`ContentAddressedStore` owns immutable blobs under OCI-style digest paths: + +```text +content/ + blobs/ + sha256/ + ingest/ + refs/ + snapshots/ +``` + +Writers copy or download into `ingest`, verify the SHA-256 digest, and publish +with a same-volume rename. Existing blobs are reused. Blob deletion, reference +counting, and leases are intentionally deferred. + +## Runtime protocol + +The guest-to-host API uses stable resource methods such as `image.pull`, +`container.create`, and `process.start`. Docker's HTTP API remains a guest-side +frontend and is never forwarded directly to the host. + +Every request includes a major/minor version, request ID, method, and +method-specific parameters. Frontends query `system.capabilities` before using +optional methods. There is no one-shot run request or migration fallback. + +## GhostTools CLI + +`ghostbox` is the native diagnostic frontend. It is built as +a GhostTools package product, copied into `GhostTools.app/Contents/MacOS`, and +placed at `GhostTools/bin/ghostbox` for direct testing. + +The next guest layer is a Docker Engine API adapter that shares the same runtime +client and translates Docker operations into one or more runtime protocol +methods. diff --git a/Website/src/app/apple-silicon-mac-virtual-machines/page.tsx b/Website/src/app/apple-silicon-mac-virtual-machines/page.tsx index 883e8e0..5dbc289 100644 --- a/Website/src/app/apple-silicon-mac-virtual-machines/page.tsx +++ b/Website/src/app/apple-silicon-mac-virtual-machines/page.tsx @@ -353,7 +353,7 @@ export default function AppleSiliconMacVirtualMachines() {

Requirements

  • Mac with Apple Silicon (M1, M2, M3, M4, or later)
    • -
  • macOS 15 Sequoia or later
    • +
  • macOS 26 Tahoe or later
  • At least 8GB RAM (16GB+ recommended)
  • 20GB+ free disk space per VM
diff --git a/Website/src/app/docs/building-from-source/page.tsx b/Website/src/app/docs/building-from-source/page.tsx index cf10bfb..2631f38 100644 --- a/Website/src/app/docs/building-from-source/page.tsx +++ b/Website/src/app/docs/building-from-source/page.tsx @@ -7,7 +7,7 @@ import { siteConfig } from "@/config/site"; export const metadata: Metadata = { title: "Build GhostVM from Source - Xcode Setup Guide", description: - "Build GhostVM from source with Xcode 15+ and XcodeGen. Clone the repo, generate project, and compile the app. Contributor guide for Mac developers.", + "Build GhostVM from source with Xcode 26+ and XcodeGen. Clone the repo, generate project, and compile the app. Contributor guide for Mac developers.", }; export default function BuildingFromSource() { @@ -20,8 +20,8 @@ export default function BuildingFromSource() {

Prerequisites

    -
  • macOS 15+ (Sequoia) on Apple Silicon (M1 or later)
    • -
  • Xcode 15+
    • +
  • macOS 26+ (Tahoe) on Apple Silicon (M1 or later)
    • +
  • Xcode 26+
  • XcodeGen
    • diff --git a/Website/src/app/docs/getting-started/page.tsx b/Website/src/app/docs/getting-started/page.tsx index bd37484..bb13d26 100644 --- a/Website/src/app/docs/getting-started/page.tsx +++ b/Website/src/app/docs/getting-started/page.tsx @@ -23,7 +23,7 @@ export default function GettingStarted() {

    Requirements

      -
    • macOS 15+ (Sequoia) on Apple Silicon (M1 or later)
      • +
    • macOS 26+ (Tahoe) on Apple Silicon (M1 or later)

    Installation

    diff --git a/Website/src/app/download/page.tsx b/Website/src/app/download/page.tsx index de433f5..c8f0279 100644 --- a/Website/src/app/download/page.tsx +++ b/Website/src/app/download/page.tsx @@ -47,7 +47,7 @@ export default function DownloadPage() {
  • - macOS 15 Sequoia or later + macOS 26 Tahoe or later
@@ -57,7 +57,7 @@ export default function DownloadPage() { Build from Source
-

Requires Xcode 15+ and XcodeGen:

+

Requires Xcode 26+ and XcodeGen:

               
                 {`brew install xcodegen
diff --git a/Website/src/app/macos-virtual-machine-for-development/page.tsx b/Website/src/app/macos-virtual-machine-for-development/page.tsx
index 88c7f6d..17ee2c1 100644
--- a/Website/src/app/macos-virtual-machine-for-development/page.tsx
+++ b/Website/src/app/macos-virtual-machine-for-development/page.tsx
@@ -233,7 +233,7 @@ export default function MacOSVirtualMachineForDevelopment() {
             Mac with Apple Silicon (M1, M2, M3, M4, or later)
           
           
  • 
-            macOS 15 Sequoia or later
+            macOS 26 Tahoe or later
           
    • 
           
  • 
             8GB+ RAM recommended (16GB+ for comfortable
@@ -273,7 +273,7 @@ export default function MacOSVirtualMachineForDevelopment() {
         
    4. Testing macOS Versions
    
         
    
           Run different macOS versions side by side. Test your app on Sonoma
-          while your host runs Sequoia. No need for multiple physical machines.
+          while your host runs Tahoe. No need for multiple physical machines.
         
    
 
         
    5. AI Agent Workspaces
    
diff --git a/Website/src/components/landing/DownloadCTA.tsx b/Website/src/components/landing/DownloadCTA.tsx
index dd317ee..7e12745 100644
--- a/Website/src/components/landing/DownloadCTA.tsx
+++ b/Website/src/components/landing/DownloadCTA.tsx
@@ -22,7 +22,7 @@ export default function DownloadCTA() {
         
    
           
    
             
-            macOS 15+ (Sequoia)
+            macOS 26+ (Tahoe)
           
    
           
    
             
diff --git a/docs/GHOSTFILE_RELEASE.md b/docs/GHOSTFILE_RELEASE.md
new file mode 100644
index 0000000..7dc70a6
--- /dev/null
+++ b/docs/GHOSTFILE_RELEASE.md
@@ -0,0 +1,112 @@
+# Releasing GhostFile
+
+GhostFile ships as a Developer ID signed, notarized, and stapled APFS disk
+image. The disk image contains `GhostFile.app`, an `/Applications` shortcut,
+and a short installation README.
+
+## One-time setup
+
+The release Mac needs:
+
+- macOS 26 and Xcode 26.4 or newer;
+- `xcodegen` (`brew install xcodegen`);
+- Rust 1.88 or newer, unless the reusable GhostHTTP3 toolchain image is
+  already available;
+- a **Developer ID Application** certificate for the GhostFile team;
+- permission and provisioning for the `com.apple.developer.fskit.fsmodule`
+  entitlement.
+
+The preferred notarization credential is a Keychain profile. This keeps the
+Apple ID app-specific password out of shell history, process listings, and the
+repository:
+
+```sh
+xcrun notarytool store-credentials ghostfile-notary \
+  --apple-id you@example.com \
+  --team-id YOUR_TEAM_ID
+```
+
+Enter the app-specific password at the secure prompt. Then add this to the
+untracked `.env` file:
+
+```sh
+NOTARY_KEYCHAIN_PROFILE=ghostfile-notary
+```
+
+App Store Connect API keys are also supported for CI through
+`NOTARY_KEY_FILE`, `NOTARY_KEY_ID`, and, for team keys,
+`NOTARY_ISSUER_ID`. The older `NOTARY_APPLE_ID`, `NOTARY_TEAM_ID`, and
+`NOTARY_PASSWORD` combination remains supported as a fallback.
+
+## Build a locally verifiable DMG
+
+```sh
+make ghostfile-dmg \
+  GHOSTFILE_VERSION=1.0.0 \
+  GHOSTFILE_BUILD_NUMBER=100
+```
+
+This archives GhostFile, exports it with Developer ID signing, verifies the
+app and embedded FSKit extension, creates and signs the disk image, mounts it
+read-only for inspection, and unregisters temporary FSKit copies. It does not
+contact Apple's notary service and must not be distributed.
+
+When no version or build number is supplied, the same timestamp is used for
+both, yielding a naturally increasing build number. Explicit build numbers
+must increase for each published version.
+
+## Build the distributable artifact
+
+```sh
+make ghostfile-notarized-dmg \
+  GHOSTFILE_VERSION=1.0.0 \
+  GHOSTFILE_BUILD_NUMBER=100
+```
+
+The release target performs the local DMG build and then:
+
+1. submits a separate, clearly named staging copy with `notarytool --wait`;
+2. records the submission JSON next to the image;
+3. retrieves the detailed Apple log if notarization is rejected;
+4. staples and validates the accepted ticket;
+5. checks the DMG and contained app with Gatekeeper;
+6. copies the final DMG to `GHOSTFILE_SHARED_DOWNLOADS` when that directory
+   exists.
+
+Only distribute the resulting file named
+`GhostFile--notarized-arm64.dmg`.
+
+If submission fails, that final filename is never created. The rejected
+`*-notary-submission-arm64.dmg` and Apple log remain available for diagnosis.
+
+## Standalone helpers
+
+The packaging and notarization stages can be rerun independently:
+
+```sh
+GHOSTFILE_CODESIGN_ID='Developer ID Application: Example (TEAMID)' \
+GHOSTFILE_DMG_README=macOS/GhostFile/DMG_README.txt \
+scripts/package-ghostfile-dmg.sh \
+  /path/to/GhostFile.app \
+  build/GhostFile-local-arm64.dmg
+
+NOTARY_KEYCHAIN_PROFILE=ghostfile-notary \
+scripts/notarize-ghostfile-dmg.sh \
+  build/GhostFile-local-arm64.dmg
+```
+
+The packaging helper refuses development-signed apps, apps without hardened
+runtime, mismatched app/extension versions, and extensions missing the FSKit
+entitlement.
+
+## CI secrets
+
+A CI signing runner needs these secrets or their equivalent:
+
+- the Developer ID Application certificate and its import password;
+- a Developer ID provisioning profile covering `org.ghostvm.ghostfile.fs`;
+- an App Store Connect API private key, key ID, and issuer ID;
+- `GHOSTFILE_SIGNING_TEAM`.
+
+Never commit certificates, provisioning profiles, API keys, app-specific
+passwords, generated notarization JSON, or temporary keychains.
diff --git a/docs/ghostbox-api/README.md b/docs/ghostbox-api/README.md
new file mode 100644
index 0000000..3f716bb
--- /dev/null
+++ b/docs/ghostbox-api/README.md
@@ -0,0 +1,41 @@
+# Ghostbox API Reference
+
+This reference maps all 282 cataloged Ghostbox direct CLI methods to their
+corresponding Apple Containerization, Apple container, or GhostVM adapter APIs.
+
+The combined command catalog is defined by
+[`GHOSTBOX_CLI_COMMANDS.json`](../../GHOSTBOX_CLI_COMMANDS.json),
+[`GHOSTBOX_CLI_TEMPLATE.md`](../../GHOSTBOX_CLI_TEMPLATE.md), and
+[`GHOSTBOX_CR_CLI_TEMPLATE.md`](../../GHOSTBOX_CR_CLI_TEMPLATE.md).
+Containerization links are pinned to `0.40.1` revision
+`7800b4642171561c95b5f55500b19e5dce5acd45`; container links are pinned to
+`1.2.0` revision `6e65319fe476ffe8db8ddaf828a537ed36fe2859`.
+
+CLI tables show inputs only. Ghostbox output types and the corresponding Swift
+declarations are intentionally omitted.
+
+| Page | Resources | Methods |
+|---|---|---:|
+| [Images and Content](images-and-content.md) | `content-store`, `authentication`, `progress-handler`, `image-store`, `image-description`, `image`, `content` | 41 |
+| [Boot and Mounts](boot-and-mounts.md) | `kernel-command-line`, `kernel`, `kernel-image`, `init-image`, `mount`, `boot-log` | 34 |
+| [Networking and Host Configuration](networking-and-host-configuration.md) | `dns`, `hosts-entry`, `hosts`, `socket`, `network`, `interface` | 46 |
+| [Virtual Machines](virtual-machines.md) | `vm-config`, `standard-vm-config`, `vmm`, `vm-instance` | 12 |
+| [Process Configuration](process-configuration.md) | `rlimit-kind`, `rlimit`, `capabilities`, `process-config` | 32 |
+| [Containers, Managers, and Processes](containers-managers-and-processes.md) | `container-config`, `manager`, `container`, `process` | 49 |
+| [Pods](pods.md) | `pod-volume`, `pod-config`, `pod-container-config`, `pod` | 46 |
+| [Container Volumes](container-volumes.md) | `volume` | 5 |
+| [Container Memory and Labels](container-memory-and-labels.md) | `memory-size`, `resource-labels` | 10 |
+| [Container Parser Utilities](container-parser-utilities.md) | `parser` | 7 |
+| **Total** | **39 resources** | **282** |
+
+## Signature Conventions
+
+- `cn:RESOURCE:OPERATION` selects the Containerization namespace; its long
+  namespace alias is `containerization`.
+- `cr:RESOURCE:OPERATION` selects the container namespace; its long namespace
+  alias is `container`.
+- `` is a literal input.
+- `@` is an existing VMHost-owned object reference.
+- `[argument]` is optional.
+- `argument...` is repeatable.
+- `[--argument=default]` is optional and shows the framework default.
diff --git a/docs/ghostbox-api/boot-and-mounts.md b/docs/ghostbox-api/boot-and-mounts.md
new file mode 100644
index 0000000..7eb39a4
--- /dev/null
+++ b/docs/ghostbox-api/boot-and-mounts.md
@@ -0,0 +1,88 @@
+# Ghostbox Boot and Mounts API
+
+This page maps the 34 Ghostbox boot and mount methods to their corresponding
+Apple Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `kernel-command-line` | 7 |
+| `kernel` | 5 |
+| `kernel-image` | 5 |
+| `init-image` | 4 |
+| `mount` | 12 |
+| `boot-log` | 1 |
+| **Total** | **34** |
+
+## Kernel Command Line
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:kernel-command-line:create <command-line:name>
    [--kernel-argument <argument:string>]...
    [--init-argument <argument:string>]...
     | [`Kernel.CommandLine.init(kernelArgs:initArgs:)`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/init(kernelargs:initargs:)) |
+| 
    ghostbox cn:kernel-command-line:create-debug <command-line:name>
    <debug:bool>
    <panic:int>
    [--init-argument <argument:string>]...
     | [`Kernel.CommandLine.init(debug:panic:initArgs:)`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/init(debug:panic:initargs:)) |
+| 
    ghostbox cn:kernel-command-line:add-debug @<kernel-command-line:id>
     | [`Kernel.CommandLine.addDebug()`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/adddebug()) |
+| 
    ghostbox cn:kernel-command-line:add-panic @<kernel-command-line:id> <level:int>
     | [`Kernel.CommandLine.addPanic(level:)`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/addpanic(level:)) |
+| 
    ghostbox cn:kernel-command-line:set-agent-log-level @<kernel-command-line:id> <level:logger-level>
     | [`Kernel.CommandLine.setAgentLogLevel(level:)`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/setagentloglevel(level:)) |
+| 
    ghostbox cn:kernel-command-line:kernel-arguments @<kernel-command-line:id>
     | [`Kernel.CommandLine.kernelArgs`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/kernelargs) |
+| 
    ghostbox cn:kernel-command-line:init-arguments @<kernel-command-line:id>
     | [`Kernel.CommandLine.initArgs`](https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/initargs) |
+
+## Kernel
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:kernel:create <kernel:name>
    --path <path:host-url>
    --platform <platform:system-platform>
    [--command-line @<kernel-command-line:id>]
     | [`Kernel.init(path:platform:commandline:)`](https://apple.github.io/containerization/documentation/containerization/kernel/init(path:platform:commandline:)) |
+| 
    ghostbox cn:kernel:path @<kernel:id>
     | [`Kernel.path`](https://apple.github.io/containerization/documentation/containerization/kernel/path) |
+| 
    ghostbox cn:kernel:platform @<kernel:id>
     | [`Kernel.platform`](https://apple.github.io/containerization/documentation/containerization/kernel/platform) |
+| 
    ghostbox cn:kernel:kernel-arguments @<kernel:id>
     | [`Kernel.kernelArgs`](https://apple.github.io/containerization/documentation/containerization/kernel/kernelargs) |
+| 
    ghostbox cn:kernel:init-arguments @<kernel:id>
     | [`Kernel.initArgs`](https://apple.github.io/containerization/documentation/containerization/kernel/initargs) |
+
+Without `--command-line`, `kernel create` supplies a non-debug command line with
+panic level zero to the Apple initializer.
+
+## Kernel Image
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:kernel-image:from-image <kernel-image:name>
    @<image:id>
     | [`KernelImage.init(image:)`](https://apple.github.io/containerization/documentation/containerization/kernelimage/init(image:)) |
+| 
    ghostbox cn:kernel-image:create <kernel-image:name>
    <reference:string>
    --kernel @<kernel:id>...
    [--label <key-value:string>]...
    --image-store @<image-store:id>
    --content-store @<content-store:id>
     | [`KernelImage.create(reference:binaries:labels:imageStore:contentStore:)`](https://apple.github.io/containerization/documentation/containerization/kernelimage/create(reference:binaries:labels:imagestore:contentstore:)) |
+| 
    ghostbox cn:kernel-image:kernel @<kernel-image:id>
    <platform:system-platform>
     | [`KernelImage.kernel(for:)`](https://apple.github.io/containerization/documentation/containerization/kernelimage/kernel(for:)) |
+| 
    ghostbox cn:kernel-image:name @<kernel-image:id>
     | [`KernelImage.name`](https://apple.github.io/containerization/documentation/containerization/kernelimage/name) |
+| 
    ghostbox cn:kernel-image:media-type
     | [`KernelImage.mediaType`](https://apple.github.io/containerization/documentation/containerization/kernelimage/mediatype) |
+
+## Init Image
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:init-image:from-image <init-image:name>
    @<image:id>
     | [`InitImage.init(image:)`](https://apple.github.io/containerization/documentation/containerization/initimage/init(image:)) |
+| 
    ghostbox cn:init-image:create <init-image:name>
    <reference:string>
    --rootfs <rootfs:host-url>
    --platform <platform:oci-platform>
    [--label <key-value:string>]...
    --image-store @<image-store:id>
    --content-store @<content-store:id>
     | [`InitImage.create(reference:rootfs:platform:labels:imageStore:contentStore:)`](https://apple.github.io/containerization/documentation/containerization/initimage/create(reference:rootfs:platform:labels:imagestore:contentstore:)) |
+| 
    ghostbox cn:init-image:init-block @<init-image:id>
    --at <destination:host-url>
    --platform <platform:system-platform>
     | [`InitImage.initBlock(at:for:)`](https://apple.github.io/containerization/documentation/containerization/initimage/initblock(at:for:)) |
+| 
    ghostbox cn:init-image:name @<init-image:id>
     | [`InitImage.name`](https://apple.github.io/containerization/documentation/containerization/initimage/name) |
+
+## Mount
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:mount:create <mount:name>
    --type <type:string>
    --source <source:string>
    --destination <destination:container-path>
    --option <option:string>...
    --runtime-options <runtime-options:mount-runtime-options>
     | [`Mount.init(type:source:destination:options:runtimeOptions:)`](https://apple.github.io/containerization/documentation/containerization/mount/init(type:source:destination:options:runtimeoptions:)) |
+| 
    ghostbox cn:mount:block <mount:name>
    --format <format:string>
    --source <source:string>
    --destination <destination:container-path>
    [--option <option:string>]...
    [--runtime-option <option:string>]...
     | [`Mount.block(format:source:destination:options:runtimeOptions:)`](https://apple.github.io/containerization/documentation/containerization/mount/block(format:source:destination:options:runtimeoptions:)) |
+| 
    ghostbox cn:mount:share <mount:name>
    --source <source:string>
    --destination <destination:container-path>
    [--option <option:string>]...
    [--runtime-option <option:string>]...
     | [`Mount.share(source:destination:options:runtimeOptions:)`](https://apple.github.io/containerization/documentation/containerization/mount/share(source:destination:options:runtimeoptions:)) |
+| 
    ghostbox cn:mount:any <mount:name>
    --type <type:string>
    --source <source:string>
    --destination <destination:container-path>
    [--option <option:string>]...
    [--runtime-option <option:string>]...
     | [`Mount.any(type:source:destination:options:runtimeOptions:)`](https://apple.github.io/containerization/documentation/containerization/mount/any(type:source:destination:options:runtimeoptions:)) |
+| 
    ghostbox cn:mount:shared-mount <mount:name>
    --name <volume-name:string>
    --destination <destination:container-path>
    [--option <option:string>]...
     | [`Mount.sharedMount(name:destination:options:)`](https://apple.github.io/containerization/documentation/containerization/mount/sharedmount(name:destination:options:)) |
+| 
    ghostbox cn:mount:clone @<mount:id>
    --to <destination:host-path>
     | [`Mount.clone(to:)`](https://apple.github.io/containerization/documentation/containerization/mount/clone(to:)) |
+| 
    ghostbox cn:mount:is-block @<mount:id>
     | [`Mount.isBlock`](https://apple.github.io/containerization/documentation/containerization/mount/isblock) |
+| 
    ghostbox cn:mount:type @<mount:id>
     | [`Mount.type`](https://apple.github.io/containerization/documentation/containerization/mount/type) |
+| 
    ghostbox cn:mount:source @<mount:id>
     | [`Mount.source`](https://apple.github.io/containerization/documentation/containerization/mount/source) |
+| 
    ghostbox cn:mount:destination @<mount:id>
     | [`Mount.destination`](https://apple.github.io/containerization/documentation/containerization/mount/destination) |
+| 
    ghostbox cn:mount:options @<mount:id>
     | [`Mount.options`](https://apple.github.io/containerization/documentation/containerization/mount/options) |
+| 
    ghostbox cn:mount:runtime-options @<mount:id>
     | [`Mount.runtimeOptions`](https://apple.github.io/containerization/documentation/containerization/mount/runtimeoptions-swift.property) |
+
+The `block`, `share`, and `any` commands pass repeated `--runtime-option`
+values to Apple's `runtimeOptions` array parameter.
+
+## Boot Log
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:boot-log:file <boot-log:name>
    --path <path:host-url>
    [--append=true]
     | [`BootLog.file(path:append:)`](https://apple.github.io/containerization/documentation/containerization/bootlog/file(path:append:)) |
diff --git a/docs/ghostbox-api/container-memory-and-labels.md b/docs/ghostbox-api/container-memory-and-labels.md
new file mode 100644
index 0000000..b740fdf
--- /dev/null
+++ b/docs/ghostbox-api/container-memory-and-labels.md
@@ -0,0 +1,37 @@
+# Ghostbox Container Memory and Labels API
+
+This page maps the ten initial `cr` memory-size and resource-label commands to
+public Swift APIs in Apple container `1.2.0`, revision
+`6e65319fe476ffe8db8ddaf828a537ed36fe2859`.
+
+| Resource | Methods |
+|---|---:|
+| `memory-size` | 3 |
+| `resource-labels` | 7 |
+| **Total** | **10** |
+
+## Memory Size
+
+| Ghostbox Signature | Swift API |
+|---|---|
+| 
    ghostbox cr:memory-size:create <memory-size:name> <value:string>
     | [`MemorySize.init(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L27-L29) in `ContainerPersistence` |
+| 
    ghostbox cr:memory-size:formatted @<memory-size:id>
     | [`MemorySize.formatted`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L51-L55) in `ContainerPersistence` |
+| 
    ghostbox cr:memory-size:to-uint64 @<memory-size:id>
    <unit:bytes|kibibytes|mebibytes|gibibytes|tebibytes|pebibytes>
     | [`MemorySize.toUInt64(unit:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L59-L61) in `ContainerPersistence` |
+
+Memory input follows the upstream parser. Conversion rounds the selected
+Foundation information-storage unit to the nearest unsigned integer.
+
+## Resource Labels
+
+| Ghostbox Signature | Swift API |
+|---|---|
+| 
    ghostbox cr:resource-labels:create <resource-labels:name>
    [--label <label:string>]...
     | [`ResourceLabels.init(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L39-L44) in `ContainerResource` |
+| 
    ghostbox cr:resource-labels:validate-key <key:string>
     | [`ResourceLabels.validateLabelKey(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L46-L57) in `ContainerResource` |
+| 
    ghostbox cr:resource-labels:validate <key:string> <value:string>
     | [`ResourceLabels.validateLabel(key:value:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L59-L65) in `ContainerResource` |
+| 
    ghostbox cr:resource-labels:dictionary @<resource-labels:id>
     | [`ResourceLabels.dictionary`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L25) in `ContainerResource` |
+| 
    ghostbox cr:resource-labels:value @<resource-labels:id>
    <key:string>
     | [`ResourceLabels.subscript(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L89-L92) in `ContainerResource` |
+| 
    ghostbox cr:resource-labels:key-length-max
     | [`ResourceLabels.keyLengthMax`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L21) in `ContainerResource` |
+| 
    ghostbox cr:resource-labels:label-length-max
     | [`ResourceLabels.labelLengthMax`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L23) in `ContainerResource` |
+
+Create labels use `key=value` input. Labels are returned as plain JSON, so they
+must not contain secrets.
diff --git a/docs/ghostbox-api/container-parser-utilities.md b/docs/ghostbox-api/container-parser-utilities.md
new file mode 100644
index 0000000..d959bce
--- /dev/null
+++ b/docs/ghostbox-api/container-parser-utilities.md
@@ -0,0 +1,23 @@
+# Ghostbox Container Parser Utilities API
+
+This page maps the seven initial `cr:parser` commands to public APIs in Apple
+container `1.2.0`, revision `6e65319fe476ffe8db8ddaf828a537ed36fe2859`.
+
+| Resource | Methods |
+|---|---:|
+| `parser` | 7 |
+| **Total** | **7** |
+
+| Ghostbox Signature | Swift API |
+|---|---|
+| 
    ghostbox cr:parser:memory-as-mib <memory:string>
     | [`Parser.memoryStringAsMiB(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L57-L61) in `ContainerAPIClient` |
+| 
    ghostbox cr:parser:memory-as-bytes <memory:string>
     | [`Parser.memoryStringAsBytes(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L63-L67) in `ContainerAPIClient` |
+| 
    ghostbox cr:parser:labels <label:string>...
     | [`Parser.labels(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L244-L261) in `ContainerAPIClient` |
+| 
    ghostbox cr:parser:platform <platform:string>
     | [`Parser.platform(from:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L101-L103) in `ContainerAPIClient` |
+| 
    ghostbox cr:parser:is-valid-domain-name <name:string>
     | [`Parser.isValidDomainName(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L895-L900) in `ContainerAPIClient` |
+| 
    ghostbox cr:parser:is-valid-domain-name-label <label:string>
     | [`Parser.isValidDomainNameLabel(_:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L902-L908) in `ContainerAPIClient` |
+| 
    ghostbox cr:parser:parse-bool <value:string>
     | [`Parser.parseBool(string:)`](https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L1061-L1063) in `ContainerAPIClient` |
+
+`labels` parses text but does not apply `ResourceLabels` validation. `parse-bool`
+returns `null` for values other than case-insensitive `true`, `t`, `false`, and
+`f`.
diff --git a/docs/ghostbox-api/container-volumes.md b/docs/ghostbox-api/container-volumes.md
new file mode 100644
index 0000000..3eca7d4
--- /dev/null
+++ b/docs/ghostbox-api/container-volumes.md
@@ -0,0 +1,22 @@
+# Ghostbox Container Volume API
+
+This page documents the five `cr` volume commands implemented by GhostVM's
+persistent-volume adapter. These commands retain the existing `volume.*` wire
+method IDs; they do not call Apple container's volume CLI commands.
+
+| Resource | Methods |
+|---|---:|
+| `volume` | 5 |
+| **Total** | **5** |
+
+| Ghostbox Signature | Swift Source |
+|---|---|
+| 
    ghostbox cr:volume:create <volume:name>
    [--size=8589934592]
     | [`GhostboxVolumeStore.create(name:sizeInBytes:)`](../../macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L32-L85) in `GhostVMContainerRuntime` |
+| 
    ghostbox cr:volume:list
     | [`GhostboxVolumeStore.list()`](../../macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L88-L91) in `GhostVMContainerRuntime` |
+| 
    ghostbox cr:volume:inspect @<volume:id>
     | [`GhostboxVolumeStore.inspect(name:)`](../../macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L93-L96) in `GhostVMContainerRuntime` |
+| 
    ghostbox cr:volume:mount @<volume:id>
    <mount:name>
    --destination <destination:container-path>
    [--read-only=false]
     | [`GhostboxVolumeStore.makeMount(volumeName:mountReference:destination:readOnly:)`](../../macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L110-L130) in `GhostVMContainerRuntime` |
+| 
    ghostbox cr:volume:delete @<volume:id>
     | [`GhostboxVolumeStore.delete(name:)`](../../macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L98-L108) in `GhostVMContainerRuntime` |
+
+`inspect` intentionally redacts the outer-host backing path. A volume can have
+only one active mount reference, and an active mount prevents deletion.
+`delete` permanently removes the volume and its contents.
diff --git a/docs/ghostbox-api/containers-managers-and-processes.md b/docs/ghostbox-api/containers-managers-and-processes.md
new file mode 100644
index 0000000..3dc552c
--- /dev/null
+++ b/docs/ghostbox-api/containers-managers-and-processes.md
@@ -0,0 +1,93 @@
+# Ghostbox Containers, Managers, and Processes API
+
+This page maps the 49 Ghostbox container configuration, manager, container, and
+process methods to their corresponding Apple Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `container-config` | 2 |
+| `manager` | 11 |
+| `container` | 27 |
+| `process` | 9 |
+| **Total** | **49** |
+
+## Container Configuration
+
+Each `LinuxContainer` runs in its own VM. `cpus` and `memory` configure workload
+cgroup limits, while `/proc/cpuinfo` and `/proc/meminfo` expose VM capacity.
+Manager create operations with an explicit CPU limit default to zero additional
+vCPUs. An explicit memory limit defaults to enough VM overhead to compensate for
+the bundled guest kernel's reserved pages, making `MemTotal` track the limit.
+Supplying `cpuOverhead` or `memoryOverhead` remains authoritative. Inspect cgroup
+v2 `cpu.max` and `memory.max`, or use `container statistics`, for enforcement.
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:container-config:create-default
    <container-config:name>
     | [`LinuxContainer.Configuration.init()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/configuration/init()) |
+| 
    ghostbox cn:container-config:create
    <container-config:name>
    --process @<process-config:id>
    [--cpus=4]
    [--memory=1073741824]
    [--hostname <hostname:string>]
    [--sysctl <key-value:string>]...
    [--interface @<interface:id>]...
    [--socket @<socket:id>]...
    [--mount @<mount:id>]...
    [--masked-path <path:container-path>]...
    [--readonly-path <path:container-path>]...
    [--dns @<dns:id>]
    [--hosts @<hosts:id>]
    [--virtualization=false]
    [--boot-log @<boot-log:id>]
    [--oci-runtime-path <path:container-path>]
    [--use-init=false]
    [--cpu-overhead=1]
    [--memory-overhead=134217728]
     | [`LinuxContainer.Configuration.init(process:cpus:memoryInBytes:hostname:sysctl:interfaces:sockets:mounts:maskedPaths:readonlyPaths:dns:hosts:virtualization:bootLog:ociRuntimePath:useInit:cpuOverhead:memoryOverhead:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/configuration/init(process:cpus:memoryinbytes:hostname:sysctl:interfaces:sockets:mounts:maskedpaths:readonlypaths:dns:hosts:virtualization:bootlog:ociruntimepath:useinit:cpuoverhead:memoryoverhead:)) |
+
+## Manager
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:manager:create <manager:name>
    --kernel @<kernel:id>
    --initfs @<mount:id>
    --image-store @<image-store:id>
    [--network @<network:id>]
    [--rosetta=false]
    [--nested-virtualization=false]
     | [`ContainerManager.init(kernel:initfs:imageStore:network:rosetta:nestedVirtualization:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfs:imagestore:network:rosetta:nestedvirtualization:)) |
+| 
    ghostbox cn:manager:create-at-root <manager:name>
    --kernel @<kernel:id>
    --initfs @<mount:id>
    [--root <root:host-url>]
    [--network @<network:id>]
    [--rosetta=false]
    [--nested-virtualization=false]
     | [`ContainerManager.init(kernel:initfs:root:network:rosetta:nestedVirtualization:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfs:root:network:rosetta:nestedvirtualization:)) |
+| 
    ghostbox cn:manager:create-from-reference <manager:name>
    --kernel @<kernel:id>
    --initfs-reference <reference:string>
    --image-store @<image-store:id>
    [--network @<network:id>]
    [--rosetta=false]
    [--nested-virtualization=false]
     | [`ContainerManager.init(kernel:initfsReference:imageStore:network:rosetta:nestedVirtualization:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfsreference:imagestore:network:rosetta:nestedvirtualization:)) |
+| 
    ghostbox cn:manager:create-from-reference-at-root
    <manager:name>
    --kernel @<kernel:id>
    --initfs-reference <reference:string>
    [--root <root:host-url>]
    [--network @<network:id>]
    [--rosetta=false]
    [--nested-virtualization=false]
     | [`ContainerManager.init(kernel:initfsReference:root:network:rosetta:nestedVirtualization:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfsreference:root:network:rosetta:nestedvirtualization:)) |
+| 
    ghostbox cn:manager:create-with-vmm <manager:name>
    --vmm @<vmm:id>
    [--network @<network:id>]
     | [`ContainerManager.init(vmm:network:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/init(vmm:network:)) |
+| 
    ghostbox cn:manager:image-store @<manager:id>
     | [`ContainerManager.imageStore`](https://apple.github.io/containerization/documentation/containerization/containermanager/imagestore) |
+| 
    ghostbox cn:manager:create-container @<manager:id>
    <container:name>
    --reference <reference:string>
    [--rootfs-size=8589934592]
    [--writable-layer-size <bytes:uint64>]
    [--read-only=false]
    [--networking=true]
    [--progress @<progress-handler:id>]
    [--process @<process-config:id>]
    [--cpus <cpus:int>]
    [--memory <bytes:uint64>]
    [--hostname <hostname:string>]
    [--sysctl <key-value:string>]...
    [--interfaces @<interface:id>]...
    [--sockets @<socket:id>]...
    [--mounts @<mount:id>]...
    [--masked-paths <path:container-path>]...
    [--readonly-paths <path:container-path>]...
    [--dns @<dns:id>]
    [--hosts @<hosts:id>]
    [--virtualization <enabled:bool>]
    [--boot-log @<boot-log:id>]
    [--oci-runtime-path <path:container-path>]
    [--use-init <enabled:bool>]
    [--cpu-overhead <cpus:int>]
    [--memory-overhead <bytes:uint64>]
     | [`ContainerManager.create(_:reference:rootfsSizeInBytes:writableLayerSizeInBytes:readOnly:networking:progress:configuration:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/create(_:reference:rootfssizeinbytes:writablelayersizeinbytes:readonly:networking:progress:configuration:)) |
+| 
    ghostbox cn:manager:create-container-from-image @<manager:id>
    <container:name>
    --image @<image:id>
    [--rootfs-size=8589934592]
    [--writable-layer-size <bytes:uint64>]
    [--read-only=false]
    [--networking=true]
    [--progress @<progress-handler:id>]
    [--process @<process-config:id>]
    [--cpus <cpus:int>]
    [--memory <bytes:uint64>]
    [--hostname <hostname:string>]
    [--sysctl <key-value:string>]...
    [--interfaces @<interface:id>]...
    [--sockets @<socket:id>]...
    [--mounts @<mount:id>]...
    [--masked-paths <path:container-path>]...
    [--readonly-paths <path:container-path>]...
    [--dns @<dns:id>]
    [--hosts @<hosts:id>]
    [--virtualization <enabled:bool>]
    [--boot-log @<boot-log:id>]
    [--oci-runtime-path <path:container-path>]
    [--use-init <enabled:bool>]
    [--cpu-overhead <cpus:int>]
    [--memory-overhead <bytes:uint64>]
     | [`ContainerManager.create(_:image:rootfsSizeInBytes:writableLayerSizeInBytes:readOnly:networking:progress:configuration:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/create(_:image:rootfssizeinbytes:writablelayersizeinbytes:readonly:networking:progress:configuration:)) |
+| 
    ghostbox cn:manager:create-container-from-mounts @<manager:id>
    <container:name>
    --image @<image:id>
    --rootfs @<mount:id>
    [--writable-layer @<mount:id>]
    [--networking=true]
    [--process @<process-config:id>]
    [--cpus <cpus:int>]
    [--memory <bytes:uint64>]
    [--hostname <hostname:string>]
    [--sysctl <key-value:string>]...
    [--interfaces @<interface:id>]...
    [--sockets @<socket:id>]...
    [--mounts @<mount:id>]...
    [--masked-paths <path:container-path>]...
    [--readonly-paths <path:container-path>]...
    [--dns @<dns:id>]
    [--hosts @<hosts:id>]
    [--virtualization <enabled:bool>]
    [--boot-log @<boot-log:id>]
    [--oci-runtime-path <path:container-path>]
    [--use-init <enabled:bool>]
    [--cpu-overhead <cpus:int>]
    [--memory-overhead <bytes:uint64>]
     | [`ContainerManager.create(_:image:rootfs:writableLayer:networking:configuration:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/create(_:image:rootfs:writablelayer:networking:configuration:)) |
+| 
    ghostbox cn:manager:release-network @<manager:id>
    @<container:id>
     | [`ContainerManager.releaseNetwork(_:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/releasenetwork(_:)) |
+| 
    ghostbox cn:manager:delete @<manager:id>
    @<container:id>
     | [`ContainerManager.delete(_:)`](https://apple.github.io/containerization/documentation/containerization/containermanager/delete(_:)) |
+
+## Container
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:container:default-mounts
     | [`LinuxContainer.defaultMounts()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultmounts()) |
+| 
    ghostbox cn:container:default-oci-mounts
     | [`LinuxContainer.defaultOCIMounts()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultocimounts()) |
+| 
    ghostbox cn:container:default-masked-paths
     | [`LinuxContainer.defaultMaskedPaths()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultmaskedpaths()) |
+| 
    ghostbox cn:container:default-readonly-paths
     | [`LinuxContainer.defaultReadonlyPaths()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultreadonlypaths()) |
+| 
    ghostbox cn:container:default-copy-chunk-size
     | [`LinuxContainer.defaultCopyChunkSize`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultcopychunksize) |
+| 
    ghostbox cn:container:max-id-length
     | [`LinuxContainer.maxIDLength`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/maxidlength) |
+| 
    ghostbox cn:container:create-direct <container:name>
    --rootfs @<mount:id>
    [--writable-layer @<mount:id>]
    --vmm @<vmm:id>
    --configuration @<container-config:id>
     | [`LinuxContainer.init(_:rootfs:writableLayer:vmm:configuration:logger:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/init(_:rootfs:writablelayer:vmm:configuration:logger:)) |
+| 
    ghostbox cn:container:id @<container:id>
     | [`LinuxContainer.id`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/id) |
+| 
    ghostbox cn:container:rootfs @<container:id>
     | [`LinuxContainer.rootfs`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/rootfs) |
+| 
    ghostbox cn:container:writable-layer @<container:id>
     | [`LinuxContainer.writableLayer`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/writablelayer) |
+| 
    ghostbox cn:container:config @<container:id>
     | [`LinuxContainer.config`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/config) |
+| 
    ghostbox cn:container:cpus @<container:id>
     | [`LinuxContainer.cpus`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/cpus) |
+| 
    ghostbox cn:container:memory @<container:id>
     | [`LinuxContainer.memoryInBytes`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/memoryinbytes) |
+| 
    ghostbox cn:container:interfaces @<container:id>
     | [`LinuxContainer.interfaces`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/interfaces) |
+| 
    ghostbox cn:container:create @<container:id>
     | [`LinuxContainer.create()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/create()) |
+| 
    ghostbox cn:container:start @<container:id>
     | [`LinuxContainer.start()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/start()) |
+| 
    ghostbox cn:container:stop @<container:id>
     | [`LinuxContainer.stop()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/stop()) |
+| 
    ghostbox cn:container:kill @<container:id>
    <signal:linux-signal>
     | [`LinuxContainer.kill(_:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/kill(_:)) |
+| 
    ghostbox cn:container:wait @<container:id>
    [--timeout-seconds <seconds:int64>]
     | [`LinuxContainer.wait(timeoutInSeconds:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/wait(timeoutinseconds:)) |
+| 
    ghostbox cn:container:resize @<container:id>
    <width:uint16>
    <height:uint16>
     | [`LinuxContainer.resize(to:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/resize(to:)) |
+| 
    ghostbox cn:container:exec @<container:id>
    <process:name>
    --configuration @<process-config:id>
     | [`LinuxContainer.exec(_:configuration:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/exec(_:configuration:)-7nhhe) |
+| 
    ghostbox cn:container:dial-vsock @<container:id>
    <port:uint32>
     | [`LinuxContainer.dialVsock(port:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/dialvsock(port:)) |
+| 
    ghostbox cn:container:close-stdin @<container:id>
     | [`LinuxContainer.closeStdin()`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/closestdin()) |
+| 
    ghostbox cn:container:statistics @<container:id>
    [--category <category:statistics-category>]...
     | [`LinuxContainer.statistics(categories:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/statistics(categories:)) |
+| 
    ghostbox cn:container:filesystem-operation @<container:id>
    <operation:freeze|thaw|trim>
    <path:container-path>
     | [`LinuxContainer.filesystemOperation(operation:path:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/filesystemoperation(operation:path:)) |
+| 
    ghostbox cn:container:copy-in @<container:id>
    <source:host-url>
    <destination:container-url>
    [--mode=0644]
    [--create-parents=true]
    [--chunk-size=1048576]
     | [`LinuxContainer.copyIn(from:to:mode:createParents:chunkSize:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/copyin(from:to:mode:createparents:chunksize:)) |
+| 
    ghostbox cn:container:copy-out @<container:id>
    <source:container-url>
    <destination:host-url>
    [--create-parents=true]
    [--chunk-size=1048576]
     | [`LinuxContainer.copyOut(from:to:createParents:chunkSize:)`](https://apple.github.io/containerization/documentation/containerization/linuxcontainer/copyout(from:to:createparents:chunksize:)) |
+
+## Process
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:process:id @<process:id>
     | [`LinuxProcess.id`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/id) |
+| 
    ghostbox cn:process:owning-container @<process:id>
     | [`LinuxProcess.owningContainer`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/owningcontainer) |
+| 
    ghostbox cn:process:pid @<process:id>
     | [`LinuxProcess.pid`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/pid) |
+| 
    ghostbox cn:process:start @<process:id>
     | [`LinuxProcess.start()`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/start()) |
+| 
    ghostbox cn:process:kill @<process:id>
    <signal:linux-signal>
     | [`LinuxProcess.kill(_:)`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/kill(_:)) |
+| 
    ghostbox cn:process:resize @<process:id>
    <width:uint16>
    <height:uint16>
     | [`LinuxProcess.resize(to:)`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/resize(to:)) |
+| 
    ghostbox cn:process:close-stdin @<process:id>
     | [`LinuxProcess.closeStdin()`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/closestdin()) |
+| 
    ghostbox cn:process:wait @<process:id>
    [--timeout-seconds <seconds:int64>]
     | [`LinuxProcess.wait(timeoutInSeconds:)`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/wait(timeoutinseconds:)) |
+| 
    ghostbox cn:process:delete @<process:id>
     | [`LinuxProcess.delete()`](https://apple.github.io/containerization/documentation/containerization/linuxprocess/delete()) |
diff --git a/docs/ghostbox-api/images-and-content.md b/docs/ghostbox-api/images-and-content.md
new file mode 100644
index 0000000..bc23814
--- /dev/null
+++ b/docs/ghostbox-api/images-and-content.md
@@ -0,0 +1,99 @@
+# Ghostbox Images and Content API
+
+This page maps the 41 Ghostbox image and content methods to their corresponding
+Apple Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json` and
+  `GHOSTBOX_CLI_TEMPLATE.md`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `image-store` | 16 |
+| `content-store` | 1 |
+| `authentication` | 1 |
+| `progress-handler` | 1 |
+| `image-description` | 5 |
+| `image` | 12 |
+| `content` | 5 |
+| **Total** | **41** |
+
+## Image Store
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:image-store:create <image-store:name>
    --path <path:host-url>
    [--content-store @<content-store:id>]
     | [`ImageStore.init(path:contentStore:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/init(path:contentstore:)) |
+| 
    ghostbox cn:image-store:default
     | [`ImageStore.default`](https://apple.github.io/containerization/documentation/containerization/imagestore/default) |
+| 
    ghostbox cn:image-store:path @<image-store:id>
     | [`ImageStore.path`](https://apple.github.io/containerization/documentation/containerization/imagestore/path) |
+| 
    ghostbox cn:image-store:get @<image-store:id>
    <reference:string>
    [--pull=false]
     | [`ImageStore.get(reference:pull:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/get(reference:pull:)) |
+| 
    ghostbox cn:image-store:list @<image-store:id>
     | [`ImageStore.list()`](https://apple.github.io/containerization/documentation/containerization/imagestore/list()) |
+| 
    ghostbox cn:image-store:create-image @<image-store:id>
    @<image-description:id>
     | [`ImageStore.create(description:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/create(description:)) |
+| 
    ghostbox cn:image-store:delete @<image-store:id>
    <reference:string>
    [--perform-cleanup=false]
     | [`ImageStore.delete(reference:performCleanup:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/delete(reference:performcleanup:)) |
+| 
    ghostbox cn:image-store:clean-up-orphaned-blobs @<image-store:id>
     | [`ImageStore.cleanUpOrphanedBlobs()`](https://apple.github.io/containerization/documentation/containerization/imagestore/cleanuporphanedblobs()) |
+| 
    ghostbox cn:image-store:calculate-orphaned-blobs-size @<image-store:id>
     | [`ImageStore.calculateOrphanedBlobsSize()`](https://apple.github.io/containerization/documentation/containerization/imagestore/calculateorphanedblobssize()) |
+| 
    ghostbox cn:image-store:tag @<image-store:id>
    <existing-reference:string>
    <new-reference:string>
     | [`ImageStore.tag(existing:new:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/tag(existing:new:)) |
+| 
    ghostbox cn:image-store:pull @<image-store:id>
    <reference:string>
    [--platform <platform:oci-platform>]
    [--insecure=false]
    [--authentication @<authentication:id>]
    [--progress @<progress-handler:id>]
    [--max-concurrent-downloads=3]
     | [`ImageStore.pull(reference:platform:insecure:auth:progress:maxConcurrentDownloads:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/pull(reference:platform:insecure:auth:progress:maxconcurrentdownloads:)) |
+| 
    ghostbox cn:image-store:push @<image-store:id>
    <reference:string>
    [--platform <platform:oci-platform>]
    [--insecure=false]
    [--authentication @<authentication:id>]
    [--progress @<progress-handler:id>]
     | [`ImageStore.push(reference:platform:insecure:auth:progress:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/push(reference:platform:insecure:auth:progress:)) |
+| 
    ghostbox cn:image-store:push-many @<image-store:id>
    <reference:string>...
    [--platform <platform:oci-platform>]
    [--insecure=false]
    [--authentication @<authentication:id>]
    [--max-concurrent-uploads=3]
    [--progress @<progress-handler:id>]
     | [`ImageStore.push(references:platform:insecure:auth:maxConcurrentUploads:progress:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/push(references:platform:insecure:auth:maxconcurrentuploads:progress:)) |
+| 
    ghostbox cn:image-store:save @<image-store:id>
    <reference:string>...
    --out <directory:host-url>
    [--platform <platform:oci-platform>]
     | [`ImageStore.save(references:out:platform:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/save(references:out:platform:)) |
+| 
    ghostbox cn:image-store:load @<image-store:id>
    <directory:host-url>
    [--progress @<progress-handler:id>]
     | [`ImageStore.load(from:progress:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/load(from:progress:)) |
+| 
    ghostbox cn:image-store:get-init-image @<image-store:id>
    <reference:string>
    [--authentication @<authentication:id>]
    [--progress @<progress-handler:id>]
     | [`ImageStore.getInitImage(reference:auth:progress:)`](https://apple.github.io/containerization/documentation/containerization/imagestore/getinitimage(reference:auth:progress:)) |
+
+`image-store push` and `image-store push-many` select Apple's single-reference
+and multiple-reference `push` overloads respectively.
+
+## Content Store, Authentication, and Progress
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:content-store:create <content-store:name>
    --path <path:host-url>
     | [`LocalContentStore.init(path:)`](https://apple.github.io/containerization/documentation/containerizationoci/localcontentstore/init(path:)) |
+| 
    ghostbox cn:authentication:create-basic <authentication:name>
    --username <username:string>
    --password <password:string>
     | [`BasicAuthentication.init(username:password:)`](https://apple.github.io/containerization/documentation/containerizationoci/basicauthentication/init(username:password:)) |
+| 
    ghostbox cn:progress-handler:create <progress-handler:name>
    --writer @<writer:id>
     | [`ProgressHandler`](https://apple.github.io/containerization/documentation/containerizationextras/progresshandler) |
+
+The progress-handler command is a Ghostbox transport adapter for Apple's
+callback type. It writes newline-delimited `{event,value}` JSON objects through
+the selected Apple `Writer` implementation.
+
+## Image Description
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:image-description:create
    <image-description:name>
    <reference:string>
    <descriptor:oci-descriptor-json>
     | [`Image.Description.init(reference:descriptor:)`](https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/init(reference:descriptor:)) |
+| 
    ghostbox cn:image-description:reference @<image-description:id>
     | [`Image.Description.reference`](https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/reference) |
+| 
    ghostbox cn:image-description:descriptor @<image-description:id>
     | [`Image.Description.descriptor`](https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/descriptor) |
+| 
    ghostbox cn:image-description:digest @<image-description:id>
     | [`Image.Description.digest`](https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/digest) |
+| 
    ghostbox cn:image-description:media-type @<image-description:id>
     | [`Image.Description.mediaType`](https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/mediatype) |
+
+## Image
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:image:create <image:name>
    @<image-description:id>
    @<content-store:id>
     | [`Image.init(description:contentStore:)`](https://apple.github.io/containerization/documentation/containerization/image/init(description:contentstore:)) |
+| 
    ghostbox cn:image:description @<image:id>
     | [`Image.description`](https://apple.github.io/containerization/documentation/containerization/image/description-swift.property) |
+| 
    ghostbox cn:image:descriptor @<image:id>
     | [`Image.descriptor`](https://apple.github.io/containerization/documentation/containerization/image/descriptor) |
+| 
    ghostbox cn:image:digest @<image:id>
     | [`Image.digest`](https://apple.github.io/containerization/documentation/containerization/image/digest) |
+| 
    ghostbox cn:image:media-type @<image:id>
     | [`Image.mediaType`](https://apple.github.io/containerization/documentation/containerization/image/mediatype) |
+| 
    ghostbox cn:image:reference @<image:id>
     | [`Image.reference`](https://apple.github.io/containerization/documentation/containerization/image/reference) |
+| 
    ghostbox cn:image:index @<image:id>
     | [`Image.index()`](https://apple.github.io/containerization/documentation/containerization/image/index()) |
+| 
    ghostbox cn:image:manifest @<image:id>
    <platform:oci-platform>
     | [`Image.manifest(for:)`](https://apple.github.io/containerization/documentation/containerization/image/manifest(for:)) |
+| 
    ghostbox cn:image:descriptor-for @<image:id>
    <platform:oci-platform>
     | [`Image.descriptor(for:)`](https://apple.github.io/containerization/documentation/containerization/image/descriptor(for:)) |
+| 
    ghostbox cn:image:config @<image:id>
    <platform:oci-platform>
     | [`Image.config(for:)`](https://apple.github.io/containerization/documentation/containerization/image/config(for:)) |
+| 
    ghostbox cn:image:referenced-digests @<image:id>
     | [`Image.referencedDigests()`](https://apple.github.io/containerization/documentation/containerization/image/referenceddigests()) |
+| 
    ghostbox cn:image:get-content @<image:id>
    <digest:string>
     | [`Image.getContent(digest:)`](https://apple.github.io/containerization/documentation/containerization/image/getcontent(digest:)) |
+
+## Content
+
+The linked `Content` APIs belong to the `ContainerizationOCI` module.
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:content:path @<content:id>
     | [`Content.path`](https://apple.github.io/containerization/documentation/containerizationoci/content/path) |
+| 
    ghostbox cn:content:digest @<content:id>
     | [`Content.digest()`](https://apple.github.io/containerization/documentation/containerizationoci/content/digest()) |
+| 
    ghostbox cn:content:size @<content:id>
     | [`Content.size()`](https://apple.github.io/containerization/documentation/containerizationoci/content/size()) |
+| 
    ghostbox cn:content:data @<content:id>
     | [`Content.data()`](https://apple.github.io/containerization/documentation/containerizationoci/content/data()) |
+| 
    ghostbox cn:content:data-range @<content:id>
    <offset:uint64>
    <length:int>
     | [`Content.data(offset:length:)`](https://apple.github.io/containerization/documentation/containerizationoci/content/data(offset:length:)) |
+
+Ghostbox enforces its direct-protocol byte limit before returning content data.
+For `content data-range`, a CLI length of zero means read from the offset through
+the end of the content.
diff --git a/docs/ghostbox-api/networking-and-host-configuration.md b/docs/ghostbox-api/networking-and-host-configuration.md
new file mode 100644
index 0000000..48d5182
--- /dev/null
+++ b/docs/ghostbox-api/networking-and-host-configuration.md
@@ -0,0 +1,100 @@
+# Ghostbox Networking and Host Configuration API
+
+This page maps the 46 Ghostbox networking and host configuration methods to
+their corresponding Apple Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json` and
+  `GHOSTBOX_CLI_TEMPLATE.md`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `dns` | 8 |
+| `hosts-entry` | 11 |
+| `hosts` | 5 |
+| `socket` | 6 |
+| `network` | 9 |
+| `interface` | 7 |
+| **Total** | **46** |
+
+## DNS
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:dns:create <dns:name>
    [--nameserver <address:string>]...
    [--domain <domain:string>]
    [--search-domain <domain:string>]...
    [--option <option:string>]...
     | [`DNS.init(nameservers:domain:searchDomains:options:)`](https://apple.github.io/containerization/documentation/containerization/dns/init(nameservers:domain:searchdomains:options:)) |
+| 
    ghostbox cn:dns:default-nameservers
     | [`DNS.defaultNameservers`](https://apple.github.io/containerization/documentation/containerization/dns/defaultnameservers) |
+| 
    ghostbox cn:dns:validate @<dns:id>
     | [`DNS.validate()`](https://apple.github.io/containerization/documentation/containerization/dns/validate()) |
+| 
    ghostbox cn:dns:resolv-conf @<dns:id>
     | [`DNS.resolvConf`](https://apple.github.io/containerization/documentation/containerization/dns/resolvconf) |
+| 
    ghostbox cn:dns:nameservers @<dns:id>
     | [`DNS.nameservers`](https://apple.github.io/containerization/documentation/containerization/dns/nameservers) |
+| 
    ghostbox cn:dns:domain @<dns:id>
     | [`DNS.domain`](https://apple.github.io/containerization/documentation/containerization/dns/domain) |
+| 
    ghostbox cn:dns:search-domains @<dns:id>
     | [`DNS.searchDomains`](https://apple.github.io/containerization/documentation/containerization/dns/searchdomains) |
+| 
    ghostbox cn:dns:options @<dns:id>
     | [`DNS.options`](https://apple.github.io/containerization/documentation/containerization/dns/options) |
+
+## Hosts Entry
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:hosts-entry:create <hosts-entry:name>
    <ip-address:string>
    <hostname:string>...
    [--comment <comment:string>]
     | [`Hosts.Entry.init(ipAddress:hostnames:comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/init(ipaddress:hostnames:comment:)) |
+| 
    ghostbox cn:hosts-entry:localhost-ipv4 <hosts-entry:name>
    [--comment <comment:string>]
     | [`Hosts.Entry.localHostIPV4(comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/localhostipv4(comment:)) |
+| 
    ghostbox cn:hosts-entry:localhost-ipv6 <hosts-entry:name>
    [--comment <comment:string>]
     | [`Hosts.Entry.localHostIPV6(comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/localhostipv6(comment:)) |
+| 
    ghostbox cn:hosts-entry:ipv6-localnet <hosts-entry:name>
    [--comment <comment:string>]
     | [`Hosts.Entry.ipv6LocalNet(comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6localnet(comment:)) |
+| 
    ghostbox cn:hosts-entry:ipv6-mcastprefix <hosts-entry:name>
    [--comment <comment:string>]
     | [`Hosts.Entry.ipv6MulticastPrefix(comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6multicastprefix(comment:)) |
+| 
    ghostbox cn:hosts-entry:ipv6-allnodes <hosts-entry:name>
    [--comment <comment:string>]
     | [`Hosts.Entry.ipv6AllNodes(comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6allnodes(comment:)) |
+| 
    ghostbox cn:hosts-entry:ipv6-allrouters <hosts-entry:name>
    [--comment <comment:string>]
     | [`Hosts.Entry.ipv6AllRouters(comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6allrouters(comment:)) |
+| 
    ghostbox cn:hosts-entry:rendered @<hosts-entry:id>
     | [`Hosts.Entry.rendered`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/rendered) |
+| 
    ghostbox cn:hosts-entry:ip-address @<hosts-entry:id>
     | [`Hosts.Entry.ipAddress`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipaddress) |
+| 
    ghostbox cn:hosts-entry:hostnames @<hosts-entry:id>
     | [`Hosts.Entry.hostnames`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/hostnames) |
+| 
    ghostbox cn:hosts-entry:comment @<hosts-entry:id>
     | [`Hosts.Entry.comment`](https://apple.github.io/containerization/documentation/containerization/hosts/entry/comment) |
+
+## Hosts
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:hosts:create <hosts:name>
    [--entry @<hosts-entry:id>]...
    [--comment <comment:string>]
     | [`Hosts.init(entries:comment:)`](https://apple.github.io/containerization/documentation/containerization/hosts/init(entries:comment:)) |
+| 
    ghostbox cn:hosts:default
     | [`Hosts.default`](https://apple.github.io/containerization/documentation/containerization/hosts/default) |
+| 
    ghostbox cn:hosts:hosts-file @<hosts:id>
     | [`Hosts.hostsFile`](https://apple.github.io/containerization/documentation/containerization/hosts/hostsfile) |
+| 
    ghostbox cn:hosts:entries @<hosts:id>
     | [`Hosts.entries`](https://apple.github.io/containerization/documentation/containerization/hosts/entries) |
+| 
    ghostbox cn:hosts:comment @<hosts:id>
     | [`Hosts.comment`](https://apple.github.io/containerization/documentation/containerization/hosts/comment) |
+
+## Socket
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:socket:create <socket:name>
    --source <source:host-url>
    --destination <destination:host-url>
    [--permissions <permissions:file-permissions>]
    [--direction <direction:into|out-of>]
     | [`UnixSocketConfiguration.init(source:destination:permissions:direction:)`](https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/init(source:destination:permissions:direction:)) |
+| 
    ghostbox cn:socket:id @<socket:id>
     | [`UnixSocketConfiguration.id`](https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/id) |
+| 
    ghostbox cn:socket:source @<socket:id>
     | [`UnixSocketConfiguration.source`](https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/source) |
+| 
    ghostbox cn:socket:destination @<socket:id>
     | [`UnixSocketConfiguration.destination`](https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/destination) |
+| 
    ghostbox cn:socket:permissions @<socket:id>
     | [`UnixSocketConfiguration.permissions`](https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/permissions) |
+| 
    ghostbox cn:socket:direction @<socket:id>
     | [`UnixSocketConfiguration.direction`](https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/direction-swift.property) |
+
+## Network
+
+`VmnetNetwork` is available on macOS 26 and later.
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:network:vmnet-create <network:name>
    [--mode=shared]
    [--subnet <subnet:cidrv4>]
    [--prefix-v6 <prefix:cidrv6>]
     | [`VmnetNetwork.init(mode:subnet:prefixV6:)`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/init(mode:subnet:prefixv6:)) |
+| 
    ghostbox cn:network:subnet @<network:id>
     | [`VmnetNetwork.subnet`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/subnet) |
+| 
    ghostbox cn:network:prefix-v6 @<network:id>
     | [`VmnetNetwork.prefixV6`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/prefixv6) |
+| 
    ghostbox cn:network:ipv4-gateway @<network:id>
     | [`VmnetNetwork.ipv4Gateway`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/ipv4gateway) |
+| 
    ghostbox cn:network:ipv6-gateway @<network:id>
     | [`VmnetNetwork.ipv6Gateway`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/ipv6gateway) |
+| 
    ghostbox cn:network:create-interface @<network:id>
    <interface:name>
     | [`VmnetNetwork.createInterface(_:)`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/createinterface(_:)) |
+| 
    ghostbox cn:network:create-interface-mtu @<network:id>
    <interface:name>
    <mtu:uint32>
     | [`VmnetNetwork.createInterface(_:mtu:)`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/createinterface(_:mtu:)) |
+| 
    ghostbox cn:network:create-interface-without-gateway @<network:id>
    <interface:name>
     | [`VmnetNetwork.createInterfaceWithoutGateway(_:)`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/createinterfacewithoutgateway(_:)) |
+| 
    ghostbox cn:network:release-interface @<network:id>
    @<interface:id>
     | [`VmnetNetwork.releaseInterface(_:)`](https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/releaseinterface(_:)) |
+
+## Interface
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:interface:nat-create <interface:name>
    --ipv4-address <address:cidrv4>
    [--ipv4-gateway <gateway:ipv4-address>]
    [--ipv6-address <address:cidrv6>]
    [--ipv6-gateway <gateway:ipv6-address>]
    [--mac-address <address:mac-address>]
    [--mtu=1500]
     | [`NATInterface.init(ipv4Address:ipv4Gateway:ipv6Address:ipv6Gateway:macAddress:mtu:)`](https://apple.github.io/containerization/documentation/containerization/natinterface/init(ipv4address:ipv4gateway:ipv6address:ipv6gateway:macaddress:mtu:)) |
+| 
    ghostbox cn:interface:ipv4-address @<interface:id>
     | [`Interface.ipv4Address`](https://apple.github.io/containerization/documentation/containerization/interface/ipv4address) |
+| 
    ghostbox cn:interface:ipv4-gateway @<interface:id>
     | [`Interface.ipv4Gateway`](https://apple.github.io/containerization/documentation/containerization/interface/ipv4gateway) |
+| 
    ghostbox cn:interface:ipv6-address @<interface:id>
     | [`Interface.ipv6Address`](https://apple.github.io/containerization/documentation/containerization/interface/ipv6address) |
+| 
    ghostbox cn:interface:ipv6-gateway @<interface:id>
     | [`Interface.ipv6Gateway`](https://apple.github.io/containerization/documentation/containerization/interface/ipv6gateway) |
+| 
    ghostbox cn:interface:mac-address @<interface:id>
     | [`Interface.macAddress`](https://apple.github.io/containerization/documentation/containerization/interface/macaddress) |
+| 
    ghostbox cn:interface:mtu @<interface:id>
     | [`Interface.mtu`](https://apple.github.io/containerization/documentation/containerization/interface/mtu) |
+
+The interface accessors use `Interface` protocol requirements because Ghostbox
+stores and reads both NAT and vmnet-backed interfaces through `any Interface`.
diff --git a/docs/ghostbox-api/pods.md b/docs/ghostbox-api/pods.md
new file mode 100644
index 0000000..9a02560
--- /dev/null
+++ b/docs/ghostbox-api/pods.md
@@ -0,0 +1,89 @@
+# Ghostbox Pods API
+
+This page maps the 46 Ghostbox pod methods to their corresponding Apple
+Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json`.
+- Apple API mappings are sourced from `GhostboxPodCommands.swift`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `pod-volume` | 1 |
+| `pod-config` | 11 |
+| `pod-container-config` | 13 |
+| `pod` | 21 |
+| **Total** | **46** |
+
+## Pod Volume
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:pod-volume:create <pod-volume:name>
    --name <volume-name:string>
    --source <source:pod-volume-source>
    --format <format:string>
     | [`LinuxPod.PodVolume.init(name:source:format:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/podvolume/init(name:source:format:)) |
+
+## Pod Configuration
+
+The `set-*` commands assign the supplied value to the linked documented
+`LinuxPod.Configuration` property.
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:pod-config:create <pod-config:name>
     | [`LinuxPod.Configuration.init()`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/init()) |
+| 
    ghostbox cn:pod-config:set-cpus @<pod-config:id> <cpus:int>
     | [`LinuxPod.Configuration.cpus`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/cpus) |
+| 
    ghostbox cn:pod-config:set-memory @<pod-config:id> <bytes:uint64>
     | [`LinuxPod.Configuration.memoryInBytes`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/memoryinbytes) |
+| 
    ghostbox cn:pod-config:set-interfaces @<pod-config:id> @<interface:id>...
     | [`LinuxPod.Configuration.interfaces`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/interfaces) |
+| 
    ghostbox cn:pod-config:set-virtualization @<pod-config:id> <enabled:bool>
     | [`LinuxPod.Configuration.virtualization`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/virtualization) |
+| 
    ghostbox cn:pod-config:set-boot-log @<pod-config:id> @<boot-log:id>|null
     | [`LinuxPod.Configuration.bootLog`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/bootlog) |
+| 
    ghostbox cn:pod-config:set-share-process-namespace @<pod-config:id> <enabled:bool>
     | [`LinuxPod.Configuration.shareProcessNamespace`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/shareprocessnamespace) |
+| 
    ghostbox cn:pod-config:set-hostname @<pod-config:id> <hostname:string>|null
     | [`LinuxPod.Configuration.hostname`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/hostname) |
+| 
    ghostbox cn:pod-config:set-dns @<pod-config:id> @<dns:id>|null
     | [`LinuxPod.Configuration.dns`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/dns) |
+| 
    ghostbox cn:pod-config:set-hosts @<pod-config:id> @<hosts:id>|null
     | [`LinuxPod.Configuration.hosts`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/hosts) |
+| 
    ghostbox cn:pod-config:set-volumes @<pod-config:id> @<pod-volume:id>...
     | [`LinuxPod.Configuration.volumes`](https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/volumes) |
+
+## Pod Container Configuration
+
+The `set-*` commands assign the supplied value to the linked documented
+`LinuxPod.ContainerConfiguration` property.
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:pod-container-config:create <pod-container-config:name>
     | [`LinuxPod.ContainerConfiguration.init()`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/init()) |
+| 
    ghostbox cn:pod-container-config:set-process @<pod-container-config:id> @<process-config:id>
     | [`LinuxPod.ContainerConfiguration.process`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/process) |
+| 
    ghostbox cn:pod-container-config:set-cpus @<pod-container-config:id> <cpus:int>|null
     | [`LinuxPod.ContainerConfiguration.cpus`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/cpus) |
+| 
    ghostbox cn:pod-container-config:set-memory @<pod-container-config:id> <bytes:uint64>|null
     | [`LinuxPod.ContainerConfiguration.memoryInBytes`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/memoryinbytes) |
+| 
    ghostbox cn:pod-container-config:set-hostname @<pod-container-config:id> <hostname:string>|null
     | [`LinuxPod.ContainerConfiguration.hostname`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/hostname) |
+| 
    ghostbox cn:pod-container-config:set-sysctl @<pod-container-config:id> <key-value:string>...
     | [`LinuxPod.ContainerConfiguration.sysctl`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/sysctl) |
+| 
    ghostbox cn:pod-container-config:set-mounts @<pod-container-config:id> @<mount:id>...
     | [`LinuxPod.ContainerConfiguration.mounts`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/mounts) |
+| 
    ghostbox cn:pod-container-config:set-masked-paths @<pod-container-config:id> <path:container-path>...
     | [`LinuxPod.ContainerConfiguration.maskedPaths`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/maskedpaths) |
+| 
    ghostbox cn:pod-container-config:set-readonly-paths @<pod-container-config:id> <path:container-path>...
     | [`LinuxPod.ContainerConfiguration.readonlyPaths`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/readonlypaths) |
+| 
    ghostbox cn:pod-container-config:set-sockets @<pod-container-config:id> @<socket:id>...
     | [`LinuxPod.ContainerConfiguration.sockets`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/sockets) |
+| 
    ghostbox cn:pod-container-config:set-dns @<pod-container-config:id> @<dns:id>|null
     | [`LinuxPod.ContainerConfiguration.dns`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/dns) |
+| 
    ghostbox cn:pod-container-config:set-hosts @<pod-container-config:id> @<hosts:id>|null
     | [`LinuxPod.ContainerConfiguration.hosts`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/hosts) |
+| 
    ghostbox cn:pod-container-config:set-use-init @<pod-container-config:id> <enabled:bool>
     | [`LinuxPod.ContainerConfiguration.useInit`](https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/useinit) |
+
+## Pod
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:pod:create-direct <pod:name>
    --vmm @<vmm:id>
    --configuration @<pod-config:id>
     | [`LinuxPod.init(_:vmm:logger:configuration:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/init(_:vmm:logger:configuration:)) |
+| 
    ghostbox cn:pod:id @<pod:id>
     | [`LinuxPod.id`](https://apple.github.io/containerization/documentation/containerization/linuxpod/id) |
+| 
    ghostbox cn:pod:config @<pod:id>
     | [`LinuxPod.config`](https://apple.github.io/containerization/documentation/containerization/linuxpod/config) |
+| 
    ghostbox cn:pod:cpus @<pod:id>
     | [`LinuxPod.cpus`](https://apple.github.io/containerization/documentation/containerization/linuxpod/cpus) |
+| 
    ghostbox cn:pod:memory @<pod:id>
     | [`LinuxPod.memoryInBytes`](https://apple.github.io/containerization/documentation/containerization/linuxpod/memoryinbytes) |
+| 
    ghostbox cn:pod:interfaces @<pod:id>
     | [`LinuxPod.interfaces`](https://apple.github.io/containerization/documentation/containerization/linuxpod/interfaces) |
+| 
    ghostbox cn:pod:add-container @<pod:id>
    <container:name>
    --rootfs @<mount:id>
    --configuration @<pod-container-config:id>
     | [`LinuxPod.addContainer(_:rootfs:configuration:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/addcontainer(_:rootfs:configuration:)) |
+| 
    ghostbox cn:pod:create @<pod:id>
     | [`LinuxPod.create()`](https://apple.github.io/containerization/documentation/containerization/linuxpod/create()) |
+| 
    ghostbox cn:pod:start-container @<pod:id> @<pod-container:id>
     | [`LinuxPod.startContainer(_:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/startcontainer(_:)) |
+| 
    ghostbox cn:pod:stop-container @<pod:id> @<pod-container:id>
     | [`LinuxPod.stopContainer(_:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/stopcontainer(_:)) |
+| 
    ghostbox cn:pod:stop @<pod:id>
     | [`LinuxPod.stop()`](https://apple.github.io/containerization/documentation/containerization/linuxpod/stop()) |
+| 
    ghostbox cn:pod:kill-container @<pod:id> @<pod-container:id> <signal:linux-signal>
     | [`LinuxPod.killContainer(_:signal:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/killcontainer(_:signal:)) |
+| 
    ghostbox cn:pod:wait-container @<pod:id>
    @<pod-container:id>
    [--timeout-seconds <seconds:int64>]
     | [`LinuxPod.waitContainer(_:timeoutInSeconds:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/waitcontainer(_:timeoutinseconds:)) |
+| 
    ghostbox cn:pod:resize-container @<pod:id>
    @<pod-container:id>
    <width:uint16>
    <height:uint16>
     | [`LinuxPod.resizeContainer(_:to:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/resizecontainer(_:to:)) |
+| 
    ghostbox cn:pod:exec-in-container @<pod:id>
    @<pod-container:id>
    <process:name>
    --configuration @<process-config:id>
     | [`LinuxPod.execInContainer(_:processID:configuration:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/execincontainer(_:processid:configuration:)) |
+| 
    ghostbox cn:pod:list-containers @<pod:id>
     | [`LinuxPod.listContainers()`](https://apple.github.io/containerization/documentation/containerization/linuxpod/listcontainers()) |
+| 
    ghostbox cn:pod:statistics @<pod:id>
    [--container @<pod-container:id>]...
    [--category <category:statistics-category>]...
     | [`LinuxPod.statistics(containerIDs:categories:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/statistics(containerids:categories:)) |
+| 
    ghostbox cn:pod:dial-vsock @<pod:id>
    <port:uint32>
     | [`LinuxPod.dialVsock(port:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/dialvsock(port:)) |
+| 
    ghostbox cn:pod:filesystem-operation @<pod:id>
    @<pod-container:id>
    <operation:freeze|thaw|trim>
    <path:container-path>
     | [`LinuxPod.filesystemOperation(_:operation:path:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/filesystemoperation(_:operation:path:)) |
+| 
    ghostbox cn:pod:close-container-stdin @<pod:id> @<pod-container:id>
     | [`LinuxPod.closeContainerStdin(_:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/closecontainerstdin(_:)) |
+| 
    ghostbox cn:pod:relay-unix-socket @<pod:id>
    @<pod-container:id>
    @<socket:id>
     | [`LinuxPod.relayUnixSocket(_:socket:)`](https://apple.github.io/containerization/documentation/containerization/linuxpod/relayunixsocket(_:socket:)) |
diff --git a/docs/ghostbox-api/process-configuration.md b/docs/ghostbox-api/process-configuration.md
new file mode 100644
index 0000000..d94f7ab
--- /dev/null
+++ b/docs/ghostbox-api/process-configuration.md
@@ -0,0 +1,71 @@
+# Ghostbox Process Configuration API
+
+This page maps the 32 Ghostbox process configuration methods to their
+corresponding Apple Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json`.
+- Apple API mappings are sourced from
+  `macOS/GhostVMContainerRuntime/Ghostbox/GhostboxConfigurationCommands.swift`
+  and `macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBuiltinCommands.swift`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `rlimit-kind` | 1 |
+| `rlimit` | 6 |
+| `capabilities` | 10 |
+| `process-config` | 15 |
+| **Total** | **32** |
+
+## Rlimit Kind
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:rlimit-kind:create <rlimit-kind:name>
    <oci-name:string>
     | [`LinuxRLimit.Kind.init(_:)`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/kind-swift.struct/init(_:)) |
+
+## Rlimit
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:rlimit:create <rlimit:name>
    --kind @<rlimit-kind:id>
    --hard <hard:uint64>
    --soft <soft:uint64>
     | [`LinuxRLimit.init(kind:hard:soft:)`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/init(kind:hard:soft:)) |
+| 
    ghostbox cn:rlimit:create-equal <rlimit:name>
    --kind @<rlimit-kind:id>
    --limit <limit:uint64>
     | [`LinuxRLimit.init(kind:limit:)`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/init(kind:limit:)) |
+| 
    ghostbox cn:rlimit:kind @<rlimit:id>
     | [`LinuxRLimit.kind`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/kind-swift.property) |
+| 
    ghostbox cn:rlimit:hard @<rlimit:id>
     | [`LinuxRLimit.hard`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/hard) |
+| 
    ghostbox cn:rlimit:soft @<rlimit:id>
     | [`LinuxRLimit.soft`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/soft) |
+| 
    ghostbox cn:rlimit:to-oci @<rlimit:id>
     | [`LinuxRLimit.toOCI()`](https://apple.github.io/containerization/documentation/containerization/linuxrlimit/tooci()) |
+
+## Capabilities
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:capabilities:create <capabilities:name>
    [--bounding <capability:linux-capability>]...
    [--effective <capability:linux-capability>]...
    [--inheritable <capability:linux-capability>]...
    [--permitted <capability:linux-capability>]...
    [--ambient <capability:linux-capability>]...
     | [`LinuxCapabilities.init(bounding:effective:inheritable:permitted:ambient:)`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/init(bounding:effective:inheritable:permitted:ambient:)) |
+| 
    ghostbox cn:capabilities:create-uniform <capabilities:name>
    <capability:linux-capability>...
     | [`LinuxCapabilities.init(capabilities:)`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/init(capabilities:)) |
+| 
    ghostbox cn:capabilities:all
     | [`LinuxCapabilities.allCapabilities`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/allcapabilities) |
+| 
    ghostbox cn:capabilities:default-oci
     | [`LinuxCapabilities.defaultOCICapabilities`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/defaultocicapabilities) |
+| 
    ghostbox cn:capabilities:bounding @<capabilities:id>
     | [`LinuxCapabilities.bounding`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/bounding) |
+| 
    ghostbox cn:capabilities:effective @<capabilities:id>
     | [`LinuxCapabilities.effective`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/effective) |
+| 
    ghostbox cn:capabilities:inheritable @<capabilities:id>
     | [`LinuxCapabilities.inheritable`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/inheritable) |
+| 
    ghostbox cn:capabilities:permitted @<capabilities:id>
     | [`LinuxCapabilities.permitted`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/permitted) |
+| 
    ghostbox cn:capabilities:ambient @<capabilities:id>
     | [`LinuxCapabilities.ambient`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/ambient) |
+| 
    ghostbox cn:capabilities:to-oci @<capabilities:id>
     | [`LinuxCapabilities.toOCI()`](https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/tooci()) |
+
+## Process Config
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:process-config:default-path
     | [`LinuxProcessConfiguration.defaultPath`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/defaultpath) |
+| 
    ghostbox cn:process-config:create <process-config:name>
    <argument:string>...
    [--environment <assignment:string>]...
    [--working-directory=/]
    [--user <user:oci-user>]
    [--rlimit @<rlimit:id>]...
    [--no-new-privileges=false]
    [--capabilities @<capabilities:id>]
    [--terminal=false]
    [--stdin @<reader-stream:id>]
    [--stdout @<writer:id>]
    [--stderr @<writer:id>]
     | [`LinuxProcessConfiguration.init(arguments:environmentVariables:workingDirectory:user:rlimits:noNewPrivileges:capabilities:terminal:stdin:stdout:stderr:)`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/init(arguments:environmentvariables:workingdirectory:user:rlimits:nonewprivileges:capabilities:terminal:stdin:stdout:stderr:)) |
+| 
    ghostbox cn:process-config:from-image-config <process-config:name>
    <image-config:oci-image-config>
     | [`LinuxProcessConfiguration.init(from:)`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/init(from:)) |
+| 
    ghostbox cn:process-config:set-terminal-io @<process-config:id>
    @<terminal:id>
     | [`LinuxProcessConfiguration.setTerminalIO(terminal:)`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/setterminalio(terminal:)) |
+| 
    ghostbox cn:process-config:arguments @<process-config:id>
     | [`LinuxProcessConfiguration.arguments`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/arguments) |
+| 
    ghostbox cn:process-config:environment-variables @<process-config:id>
     | [`LinuxProcessConfiguration.environmentVariables`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/environmentvariables) |
+| 
    ghostbox cn:process-config:working-directory @<process-config:id>
     | [`LinuxProcessConfiguration.workingDirectory`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/workingdirectory) |
+| 
    ghostbox cn:process-config:user @<process-config:id>
     | [`LinuxProcessConfiguration.user`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/user) |
+| 
    ghostbox cn:process-config:rlimits @<process-config:id>
     | [`LinuxProcessConfiguration.rlimits`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/rlimits) |
+| 
    ghostbox cn:process-config:no-new-privileges @<process-config:id>
     | [`LinuxProcessConfiguration.noNewPrivileges`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/nonewprivileges) |
+| 
    ghostbox cn:process-config:capabilities @<process-config:id>
     | [`LinuxProcessConfiguration.capabilities`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/capabilities) |
+| 
    ghostbox cn:process-config:terminal @<process-config:id>
     | [`LinuxProcessConfiguration.terminal`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/terminal) |
+| 
    ghostbox cn:process-config:stdin @<process-config:id>
     | [`LinuxProcessConfiguration.stdin`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/stdin) |
+| 
    ghostbox cn:process-config:stdout @<process-config:id>
     | [`LinuxProcessConfiguration.stdout`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/stdout) |
+| 
    ghostbox cn:process-config:stderr @<process-config:id>
     | [`LinuxProcessConfiguration.stderr`](https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/stderr) |
diff --git a/docs/ghostbox-api/virtual-machines.md b/docs/ghostbox-api/virtual-machines.md
new file mode 100644
index 0000000..3540472
--- /dev/null
+++ b/docs/ghostbox-api/virtual-machines.md
@@ -0,0 +1,48 @@
+# Ghostbox Virtual Machines API
+
+This page maps the 12 Ghostbox virtual machine methods to their corresponding
+Apple Containerization APIs.
+
+- Ghostbox signatures are sourced from `GHOSTBOX_CLI_COMMANDS.json`.
+- Apple API links are pinned to Containerization `0.40.1`, revision
+  `7800b4642171561c95b5f55500b19e5dce5acd45`.
+
+| Resource | Methods |
+|---|---:|
+| `vm-config` | 1 |
+| `standard-vm-config` | 1 |
+| `vmm` | 2 |
+| `vm-instance` | 8 |
+| **Total** | **12** |
+
+## VM Config
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:vm-config:create <vm-config:name>
    [--cpus=4]
    [--memory=1073741824]
    [--interface @<interface:id>]...
    [--mount <workload-id:string>=@<mount:id>]...
    [--boot-log @<boot-log:id>]
    [--nested-virtualization=false]
     | [`VMConfiguration.init(cpus:memoryInBytes:interfaces:mountsByID:bootLog:nestedVirtualization:)`](https://apple.github.io/containerization/documentation/containerization/vmconfiguration/init(cpus:memoryinbytes:interfaces:mountsbyid:bootlog:nestedvirtualization:)) |
+
+## Standard VM Config
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:standard-vm-config:create <standard-vm-config:name>
    @<vm-config:id>
     | [`StandardVMConfig.init(configuration:)`](https://apple.github.io/containerization/documentation/containerization/standardvmconfig/init(configuration:)) |
+
+## VMM
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:vmm:create <vmm:name>
    --kernel @<kernel:id>
    --initial-filesystem @<mount:id>
    [--rosetta=false]
    [--nested-virtualization=false]
     | [`VZVirtualMachineManager.init(kernel:initialFilesystem:rosetta:nestedVirtualization:group:logger:)`](https://apple.github.io/containerization/documentation/containerization/vzvirtualmachinemanager/init(kernel:initialfilesystem:rosetta:nestedvirtualization:group:logger:)) |
+| 
    ghostbox cn:vmm:create-instance @<vmm:id>
    @<standard-vm-config:id>
     | [`VZVirtualMachineManager.create(config:)`](https://apple.github.io/containerization/documentation/containerization/vzvirtualmachinemanager/create(config:)) |
+
+## VM Instance
+
+| Ghostbox Signature | Apple API |
+|---|---|
+| 
    ghostbox cn:vm-instance:state @<vm-instance:id>
     | [`VirtualMachineInstance.state`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/state) |
+| 
    ghostbox cn:vm-instance:mounts @<vm-instance:id>
     | [`VirtualMachineInstance.mounts`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/mounts) |
+| 
    ghostbox cn:vm-instance:virtiofs-layout @<vm-instance:id>
     | [`VirtualMachineInstance.virtiofsLayout`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/virtiofslayout) |
+| 
    ghostbox cn:vm-instance:start @<vm-instance:id>
     | [`VirtualMachineInstance.start()`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/start()) |
+| 
    ghostbox cn:vm-instance:stop @<vm-instance:id>
     | [`VirtualMachineInstance.stop()`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/stop()) |
+| 
    ghostbox cn:vm-instance:pause @<vm-instance:id>
     | [`VirtualMachineInstance.pause()`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/pause()) |
+| 
    ghostbox cn:vm-instance:resume @<vm-instance:id>
     | [`VirtualMachineInstance.resume()`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/resume()) |
+| 
    ghostbox cn:vm-instance:dial @<vm-instance:id>
    <port:uint32>
     | [`VirtualMachineInstance.dial(_:)`](https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/dial(_:)) |
diff --git a/docs/ghostbox-volumes.md b/docs/ghostbox-volumes.md
new file mode 100644
index 0000000..0fa931b
--- /dev/null
+++ b/docs/ghostbox-volumes.md
@@ -0,0 +1,43 @@
+# Ghostbox Persistent Volumes
+
+Ghostbox named volumes are sparse ext4 disk images stored inside the owning VM
+bundle. They survive container deletion, Ghostbox session cleanup, and VM
+restarts. The outer-host backing path is trusted runtime state and is never
+accepted from or returned to the guest.
+
+## Lifecycle
+
+```sh
+volume=$(ghostbox cr:volume:create app-data --size 8589934592)
+ghostbox cr:volume:list
+ghostbox cr:volume:inspect "$volume"
+mount=$(ghostbox cr:volume:mount "$volume" app-data --destination /var/lib/app)
+```
+
+The mount command returns a normal `@mount/NAME` reference backed by
+`Containerization.Mount.block(format:source:destination:options:)`. Include that
+reference and every reference returned by `ghostbox cn:container:default-mounts`
+when supplying `--mounts` to a manager create operation. Supplying `--mounts`
+replaces the complete mount set; it does not append to the defaults.
+
+Delete the mount reference before deleting the volume:
+
+```sh
+ghostbox cn:mount:delete "$mount"
+ghostbox cr:volume:delete "$volume"
+```
+
+Deletion fails while a named-volume mount reference exists. A volume can have
+only one such reference at a time. Do not attach the same block-backed mount to
+multiple live container VMs concurrently.
+
+## Limits
+
+- Names begin with a letter or digit and otherwise use letters, digits, `.`,
+  `_`, or `-`.
+- Sizes range from 1 MiB through 1 TiB; the default is 8 GiB.
+- Each VM can store at most 128 named volumes.
+- `inspect` reports the name, ext4 format, logical size, and creation date. It
+  omits the outer-host image path.
+- `ghostbox cn:mount:source @mount/NAME` returns the opaque `@volume/NAME` source
+  for managed volume mounts.
diff --git a/examples/ghostbox/README.md b/examples/ghostbox/README.md
new file mode 100644
index 0000000..f2a0b72
--- /dev/null
+++ b/examples/ghostbox/README.md
@@ -0,0 +1,97 @@
+# Ghostbox Container Examples
+
+These scripts compose Ghostbox's source-shaped lifecycle methods into behavior
+similar to `docker run --rm`. They do not add a `run` operation: allocation,
+creation, start, wait, stop, and deletion remain separate calls.
+
+Run them inside a GhostVM guest with Host-backed Containers enabled. Install
+Apple container's recommended Linux kernel on the outer host through Ghostbox:
+
+```sh
+ghostbox cn:kernel:install-recommended
+```
+
+The operation performs Apple's digest-verified download on the outer host and
+returns `@kernel/default`. `setup-manager.sh` runs it automatically and reuses an
+already-installed recommended kernel.
+
+## One-Time Manager Setup
+
+Create a reusable manager backed by the host's default kernel and image store:
+
+```sh
+./setup-manager.sh
+```
+
+The script prints `@manager/ephemeral`. Its default init image is pinned by
+manifest digest so an older tag-cache entry cannot silently supply incompatible
+guest enforcement. Override the names or pinned init image with `MANAGER_NAME`
+and `INITFS_REFERENCE`.
+
+## Non-Interactive
+
+Run Alpine's default example command:
+
+```sh
+./ephemeral-container.sh
+```
+
+Run a command and propagate its exit status:
+
+```sh
+./ephemeral-container.sh docker.io/library/alpine:latest \
+    /bin/sh -c 'printf "container says hello\\n"; exit 7'
+```
+
+## Interactive PTY
+
+```sh
+./ephemeral-terminal.sh docker.io/library/alpine:latest /bin/sh
+```
+
+The terminal script waits until raw-mode setup and the first resize reach the
+host before it starts the container. It watches the workload cgroup and closes
+the PTY proxy when the final process exits, allowing Apple's process wait to
+finish draining terminal I/O. Both scripts use traps to stop and delete the
+allocated container, delete its process configuration, and close all I/O
+proxies on success, failure, or a termination signal. Pulled images remain in
+the host cache.
+
+Container networking defaults to `false`, so the basic examples do not require
+a vmnet network. Set `CONTAINER_NETWORKING=true` when the manager was created
+with a suitable network.
+
+Use another manager or resource limits through environment variables:
+
+```sh
+MANAGER=@manager/build CONTAINER_CPUS=2 CONTAINER_MEMORY=1073741824 \
+    ./ephemeral-container.sh docker.io/library/alpine:latest uname -a
+```
+
+## Resource Cleanup
+
+Remove reusable host references when they are no longer needed:
+
+```sh
+ghostbox cn:process-config:delete @process-config/example
+ghostbox cn:dns:delete @dns/example
+ghostbox cn:network:delete @network/example
+ghostbox cn:manager:close @manager/ephemeral
+```
+
+Release every network-allocated interface before deleting its network. Delete
+all managed containers before closing their manager. Cached images can be
+removed separately with `ghostbox cn:image-store:delete @image-store/default REFERENCE`.
+
+## Persistent Volumes
+
+Run a two-container write/read lifecycle against one named ext4 volume:
+
+```sh
+./persistent-volume.sh
+```
+
+The script creates the volume and a block-mount reference, supplies the default
+container mounts plus that reference, verifies data from a second container,
+then removes the mount and volume. Named volumes are stored with the VM and
+normally remain until explicitly deleted.
diff --git a/examples/ghostbox/ephemeral-container.sh b/examples/ghostbox/ephemeral-container.sh
new file mode 100755
index 0000000..9d60c63
--- /dev/null
+++ b/examples/ghostbox/ephemeral-container.sh
@@ -0,0 +1,74 @@
+#!/bin/sh
+set -eu
+
+usage() {
+    status=${1:-64}
+    echo "usage: $0 [IMAGE [COMMAND [ARG ...]]]" >&2
+    echo "environment: GHOSTBOX, MANAGER, CONTAINER_CPUS, CONTAINER_MEMORY, CONTAINER_NETWORKING" >&2
+    exit "$status"
+}
+
+case ${1:-} in
+    -h|--help) usage 0 ;;
+esac
+
+GHOSTBOX=${GHOSTBOX:-ghostbox}
+MANAGER=${MANAGER:-@manager/ephemeral}
+CONTAINER_NETWORKING=${CONTAINER_NETWORKING:-false}
+IMAGE=${1:-docker.io/library/alpine:latest}
+if [ "$#" -gt 0 ]; then shift; fi
+if [ "$#" -eq 0 ]; then
+    # Expanded by the container's shell, not this script.
+    set -- /bin/sh -c 'echo "hello from $(uname -s) $(uname -m)"'
+fi
+
+name="ephemeral-$(date +%s)-$$"
+container="@container/$name"
+stdout="@writer/$name-stdout"
+stderr="@writer/$name-stderr"
+process="@process-config/$name-process"
+stdout_pid=
+stderr_pid=
+
+cleanup() {
+    status=$?
+    trap - EXIT HUP INT TERM
+    "$GHOSTBOX" cn:container:stop "$container" >/dev/null 2>&1 || true
+    "$GHOSTBOX" cn:writer:close "$stdout" >/dev/null 2>&1 || true
+    "$GHOSTBOX" cn:writer:close "$stderr" >/dev/null 2>&1 || true
+    if [ -n "$stdout_pid" ]; then wait "$stdout_pid" 2>/dev/null || true; fi
+    if [ -n "$stderr_pid" ]; then wait "$stderr_pid" 2>/dev/null || true; fi
+    "$GHOSTBOX" cn:manager:delete "$MANAGER" "$container" >/dev/null 2>&1 || true
+    "$GHOSTBOX" cn:process-config:delete "$process" >/dev/null 2>&1 || true
+    exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+"$GHOSTBOX" cn:writer:create "$name-stdout" >/dev/null
+"$GHOSTBOX" cn:writer:create "$name-stderr" >/dev/null
+process=$("$GHOSTBOX" cn:process-config:create "$name-process" \
+    --stdout "$stdout" --stderr "$stderr" -- "$@")
+
+set -- cn:manager:create-container "$MANAGER" "$name" \
+    --reference "$IMAGE" --process "$process" --networking "$CONTAINER_NETWORKING"
+if [ -n "${CONTAINER_CPUS:-}" ]; then
+    set -- "$@" --cpus "$CONTAINER_CPUS"
+fi
+if [ -n "${CONTAINER_MEMORY:-}" ]; then
+    set -- "$@" --memory "$CONTAINER_MEMORY"
+fi
+"$GHOSTBOX" "$@" >/dev/null
+
+"$GHOSTBOX" cn:writer:attach "$stdout" &
+stdout_pid=$!
+"$GHOSTBOX" cn:writer:attach "$stderr" >&2 &
+stderr_pid=$!
+
+"$GHOSTBOX" cn:container:create "$container"
+"$GHOSTBOX" cn:container:start "$container"
+status_json=$("$GHOSTBOX" cn:container:wait "$container")
+exit_code=$(printf '%s' "$status_json" | plutil -extract exitCode raw -o - -)
+exit "$exit_code"
diff --git a/examples/ghostbox/ephemeral-terminal.sh b/examples/ghostbox/ephemeral-terminal.sh
new file mode 100755
index 0000000..c5246e8
--- /dev/null
+++ b/examples/ghostbox/ephemeral-terminal.sh
@@ -0,0 +1,87 @@
+#!/bin/sh
+set -eu
+
+usage() {
+    status=${1:-64}
+    echo "usage: $0 [IMAGE [COMMAND [ARG ...]]]" >&2
+    echo "environment: GHOSTBOX, MANAGER, CONTAINER_CPUS, CONTAINER_MEMORY, CONTAINER_NETWORKING" >&2
+    exit "$status"
+}
+
+case ${1:-} in
+    -h|--help) usage 0 ;;
+esac
+
+if [ ! -t 0 ] || [ ! -t 1 ]; then
+    echo "$0: an interactive terminal is required" >&2
+    exit 125
+fi
+
+GHOSTBOX=${GHOSTBOX:-ghostbox}
+MANAGER=${MANAGER:-@manager/ephemeral}
+CONTAINER_NETWORKING=${CONTAINER_NETWORKING:-false}
+IMAGE=${1:-docker.io/library/alpine:latest}
+if [ "$#" -gt 0 ]; then shift; fi
+if [ "$#" -eq 0 ]; then set -- /bin/sh; fi
+
+name="terminal-$(date +%s)-$$"
+container="@container/$name"
+terminal="@terminal/$name"
+process="@process-config/$name-process"
+controller_pid=
+
+cleanup() {
+    status=$?
+    trap - EXIT HUP INT TERM
+    if [ -n "$controller_pid" ]; then kill "$controller_pid" 2>/dev/null || true; fi
+    "$GHOSTBOX" cn:terminal:close "$terminal" >/dev/null 2>&1 || true
+    if [ -n "$controller_pid" ]; then wait "$controller_pid" 2>/dev/null || true; fi
+    "$GHOSTBOX" cn:container:stop "$container" >/dev/null 2>&1 || true
+    "$GHOSTBOX" cn:manager:delete "$MANAGER" "$container" >/dev/null 2>&1 || true
+    "$GHOSTBOX" cn:process-config:delete "$process" >/dev/null 2>&1 || true
+    exit "$status"
+}
+
+controller_cleanup() {
+    "$GHOSTBOX" cn:terminal:close "$terminal" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+"$GHOSTBOX" cn:terminal:create "$name" >/dev/null
+process=$("$GHOSTBOX" cn:process-config:create "$name-process" --terminal true -- "$@")
+"$GHOSTBOX" cn:process-config:set-terminal-io "$process" "$terminal"
+
+set -- cn:manager:create-container "$MANAGER" "$name" \
+    --reference "$IMAGE" --process "$process" --networking "$CONTAINER_NETWORKING"
+if [ -n "${CONTAINER_CPUS:-}" ]; then
+    set -- "$@" --cpus "$CONTAINER_CPUS"
+fi
+if [ -n "${CONTAINER_MEMORY:-}" ]; then
+    set -- "$@" --memory "$CONTAINER_MEMORY"
+fi
+"$GHOSTBOX" "$@" >/dev/null
+
+controller() {
+    trap controller_cleanup EXIT
+    "$GHOSTBOX" cn:terminal:wait-attached "$terminal"
+    "$GHOSTBOX" cn:container:create "$container"
+    "$GHOSTBOX" cn:container:start "$container"
+
+    status_json=$("$GHOSTBOX" cn:container:wait "$container")
+    exit_code=$(printf '%s' "$status_json" | plutil -extract exitCode raw -o - -)
+    return "$exit_code"
+}
+
+controller &
+controller_pid=$!
+"$GHOSTBOX" cn:terminal:attach "$terminal" --resize-target "$container"
+
+set +e
+wait "$controller_pid"
+exit_code=$?
+set -e
+controller_pid=
+exit "$exit_code"
diff --git a/examples/ghostbox/persistent-volume.sh b/examples/ghostbox/persistent-volume.sh
new file mode 100755
index 0000000..b6021de
--- /dev/null
+++ b/examples/ghostbox/persistent-volume.sh
@@ -0,0 +1,66 @@
+#!/bin/sh
+set -eu
+
+GHOSTBOX=${GHOSTBOX:-ghostbox}
+MANAGER=${MANAGER:-@manager/ephemeral}
+IMAGE=${IMAGE:-docker.io/library/alpine:latest}
+
+name="volume-test-$(date +%s)-$$"
+volume="@volume/$name"
+mount="@mount/$name"
+container=
+process=
+
+cleanup() {
+    status=$?
+    trap - EXIT HUP INT TERM
+    if [ -n "$container" ]; then
+        "$GHOSTBOX" cn:container:stop "$container" >/dev/null 2>&1 || true
+        "$GHOSTBOX" cn:manager:delete "$MANAGER" "$container" >/dev/null 2>&1 || true
+    fi
+    if [ -n "$process" ]; then
+        "$GHOSTBOX" cn:process-config:delete "$process" >/dev/null 2>&1 || true
+    fi
+    "$GHOSTBOX" cn:mount:delete "$mount" >/dev/null 2>&1 || true
+    "$GHOSTBOX" cr:volume:delete "$volume" >/dev/null 2>&1 || true
+    exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
+"$GHOSTBOX" cr:volume:create "$name" --size 67108864 >/dev/null
+"$GHOSTBOX" cr:volume:mount "$volume" "$name" --destination /data >/dev/null
+
+run_container() {
+    run_name=$1
+    command=$2
+    process="@process-config/$run_name-process"
+    container="@container/$run_name"
+    "$GHOSTBOX" cn:process-config:create "$run_name-process" -- /bin/sh -c "$command" >/dev/null
+
+    set -- cn:manager:create-container "$MANAGER" "$run_name" \
+        --reference "$IMAGE" --process "$process" --networking false
+    for default_mount in $("$GHOSTBOX" cn:container:default-mounts); do
+        set -- "$@" --mounts "$default_mount"
+    done
+    set -- "$@" --mounts "$mount"
+    "$GHOSTBOX" "$@" >/dev/null
+    "$GHOSTBOX" cn:container:create "$container"
+    "$GHOSTBOX" cn:container:start "$container"
+    status_json=$("$GHOSTBOX" cn:container:wait "$container")
+    exit_code=$(printf '%s' "$status_json" | plutil -extract exitCode raw -o - -)
+    [ "$exit_code" -eq 0 ]
+    "$GHOSTBOX" cn:manager:delete "$MANAGER" "$container" >/dev/null
+    "$GHOSTBOX" cn:process-config:delete "$process" >/dev/null
+    container=
+    process=
+}
+
+run_container "$name-write" 'printf persistent > /data/marker'
+run_container "$name-read" 'test "$(cat /data/marker)" = persistent'
+
+"$GHOSTBOX" cn:mount:delete "$mount"
+"$GHOSTBOX" cr:volume:delete "$volume"
+echo "persistent volume lifecycle passed"
diff --git a/examples/ghostbox/setup-manager.sh b/examples/ghostbox/setup-manager.sh
new file mode 100755
index 0000000..e44c7d8
--- /dev/null
+++ b/examples/ghostbox/setup-manager.sh
@@ -0,0 +1,14 @@
+#!/bin/sh
+set -eu
+
+GHOSTBOX=${GHOSTBOX:-ghostbox}
+MANAGER_NAME=${MANAGER_NAME:-ephemeral}
+INITFS_REFERENCE=${INITFS_REFERENCE:-ghcr.io/apple/containerization/vminit@sha256:a69ff331d77997042afc3c7389969be176dfb657ec9ed46366c0e057ec40a297}
+
+kernel=$("$GHOSTBOX" cn:kernel:install-recommended)
+image_store=$("$GHOSTBOX" cn:image-store:default)
+
+"$GHOSTBOX" cn:manager:create-from-reference "$MANAGER_NAME" \
+    --kernel "$kernel" \
+    --initfs-reference "$INITFS_REFERENCE" \
+    --image-store "$image_store"
diff --git a/macOS/GhostFile/DMG_README.txt b/macOS/GhostFile/DMG_README.txt
new file mode 100644
index 0000000..5ad4473
--- /dev/null
+++ b/macOS/GhostFile/DMG_README.txt
@@ -0,0 +1,12 @@
+GhostFile
+=========
+
+Installation
+------------
+
+1. Drag GhostFile.app to the Applications folder.
+2. Open GhostFile from Applications.
+3. If macOS asks, enable GhostFileFS under:
+   System Settings > General > Login Items & Extensions > File System Extensions.
+
+GhostFile requires macOS 26 or later.
diff --git a/macOS/GhostFile/DeveloperIDExportOptions.plist b/macOS/GhostFile/DeveloperIDExportOptions.plist
new file mode 100644
index 0000000..07f49e3
--- /dev/null
+++ b/macOS/GhostFile/DeveloperIDExportOptions.plist
@@ -0,0 +1,16 @@
+
+
+
+
+    destination
+    export
+    method
+    developer-id
+    signingStyle
+    automatic
+    stripSwiftSymbols
+    
+    teamID
+    3FGZQE8AW3
+
+
diff --git a/macOS/GhostFile/DeveloperIDUploadOptions.plist b/macOS/GhostFile/DeveloperIDUploadOptions.plist
new file mode 100644
index 0000000..a9ffa25
--- /dev/null
+++ b/macOS/GhostFile/DeveloperIDUploadOptions.plist
@@ -0,0 +1,16 @@
+
+
+
+
+	destination
+	upload
+	method
+	developer-id
+	signingStyle
+	automatic
+	stripSwiftSymbols
+	
+	teamID
+	3FGZQE8AW3
+
+
diff --git a/macOS/GhostFile/GhostFile.icon/Assets/GhostFile.png b/macOS/GhostFile/GhostFile.icon/Assets/GhostFile.png
new file mode 100644
index 0000000..7b9531a
Binary files /dev/null and b/macOS/GhostFile/GhostFile.icon/Assets/GhostFile.png differ
diff --git a/macOS/GhostFile/GhostFile.icon/icon.json b/macOS/GhostFile/GhostFile.icon/icon.json
new file mode 100644
index 0000000..f27bfef
--- /dev/null
+++ b/macOS/GhostFile/GhostFile.icon/icon.json
@@ -0,0 +1,38 @@
+{
+  "fill" : {
+    "automatic-gradient" : "extended-srgb:0.04706,0.03529,0.23529,1.00000"
+  },
+  "groups" : [
+    {
+      "layers" : [
+        {
+          "glass" : false,
+          "hidden" : false,
+          "image-name" : "GhostFile.png",
+          "name" : "GhostFile",
+          "position" : {
+            "scale" : 1,
+            "translation-in-points" : [
+              0,
+              0
+            ]
+          }
+        }
+      ],
+      "shadow" : {
+        "kind" : "neutral",
+        "opacity" : 0
+      },
+      "translucency" : {
+        "enabled" : false,
+        "value" : 0.5
+      }
+    }
+  ],
+  "supported-platforms" : {
+    "circles" : [
+      "watchOS"
+    ],
+    "squares" : "shared"
+  }
+}
\ No newline at end of file
diff --git a/macOS/GhostFile/GhostFileApp.swift b/macOS/GhostFile/GhostFileApp.swift
new file mode 100644
index 0000000..b9f35da
--- /dev/null
+++ b/macOS/GhostFile/GhostFileApp.swift
@@ -0,0 +1,50 @@
+import AppKit
+import SwiftUI
+
+@main
+struct GhostFileApp: App {
+    @StateObject private var library = GhostFileLibrary()
+    @StateObject private var mountLibrary = GhostFileMountLibrary()
+
+    init() {
+        // SwiftUI does not consistently publish Icon Composer app icons to the
+        // live Dock process. Resolve the compiled bundle icon through macOS so
+        // the Dock uses the same platform-rendered asset as Finder.
+        NSApplication.shared.applicationIconImage = NSWorkspace.shared.icon(
+            forFile: Bundle.main.bundlePath
+        )
+    }
+
+    var body: some Scene {
+        WindowGroup("GhostFile") {
+            GhostFileContentView()
+                .environmentObject(library)
+                .environmentObject(mountLibrary)
+                .frame(minWidth: 760, minHeight: 420)
+        }
+        .defaultSize(width: 940, height: 560)
+
+        WindowGroup("GhostFile Details", for: GhostFileItemID.self) { $itemID in
+            if let itemID {
+                GhostFileDetailView(itemID: itemID)
+                    .environmentObject(library)
+                    .environmentObject(mountLibrary)
+                    .frame(minWidth: 560, minHeight: 520)
+            }
+        }
+        .defaultSize(width: 620, height: 650)
+
+        WindowGroup("Discovered Share", for: DiscoveredGhostFileShare.self) { $share in
+            if let share {
+                GhostFileDiscoveredDetailView(share: share)
+                    .environmentObject(mountLibrary)
+                    .frame(minWidth: 520, minHeight: 420)
+            }
+        }
+        .defaultSize(width: 580, height: 500)
+
+        Settings {
+            GhostFileSettingsView()
+        }
+    }
+}
diff --git a/macOS/GhostFile/GhostFileContentView.swift b/macOS/GhostFile/GhostFileContentView.swift
new file mode 100644
index 0000000..9d526ca
--- /dev/null
+++ b/macOS/GhostFile/GhostFileContentView.swift
@@ -0,0 +1,2197 @@
+import AppKit
+import SwiftUI
+
+enum GhostFileItemID: Hashable, Codable {
+    case share(UUID)
+    case mount(UUID)
+    case discovered(UUID)
+}
+
+private struct GhostFileRowItem: Identifiable, Hashable {
+    enum Kind { case share, mount }
+    enum Status: Hashable {
+        case online
+        case starting
+        case stopped
+        case mounted
+        case degraded
+        case error(String)
+        case offline
+        case failed(String)
+
+        var isActive: Bool {
+            switch self {
+            case .online, .starting, .mounted, .degraded, .error, .offline: true
+            case .stopped, .failed: false
+            }
+        }
+
+        var label: String {
+            switch self {
+            case .online: "Online"
+            case .starting: "Starting"
+            case .stopped: "Stopped"
+            case .mounted: "Mounted"
+            case .degraded: "Degraded"
+            case .error: "Error"
+            case .offline: "Offline"
+            case .failed: "Error"
+            }
+        }
+    }
+
+    let id: GhostFileItemID
+    let kind: Kind
+    let name: String
+    let location: String
+    let detail: String?
+    let status: Status
+    let readOnly: Bool
+}
+
+struct GhostFileContentView: View {
+    @Environment(\.openWindow) private var openWindow
+    @Environment(\.openSettings) private var openSettings
+    @Environment(\.scenePhase) private var scenePhase
+    @EnvironmentObject private var library: GhostFileLibrary
+    @EnvironmentObject private var mountLibrary: GhostFileMountLibrary
+    @StateObject private var discovery = GhostFileDiscovery()
+    @AppStorage("ghostfile.sharesExpanded") private var sharesExpanded = true
+    @AppStorage("ghostfile.mountsExpanded") private var mountsExpanded = true
+    @AppStorage("ghostfile.discoverExpanded") private var discoverExpanded = true
+    @AppStorage("ghostfile.discoverSelfShares") private var discoverSelfShares = false
+    @State private var selection: Set = []
+    @State private var focusedItemID: GhostFileItemID?
+    @State private var selectionAnchorID: GhostFileItemID?
+    @State private var pendingDeletion: Set = []
+    @State private var showingAddMount = false
+    @State private var addMountSelectionID: UUID?
+    @State private var completedExtensionStartupScan = false
+    @State private var showingExtensionAssistant = false
+    @FocusState private var tableHasFocus: Bool
+
+    var body: some View {
+        VStack(spacing: 0) {
+            appHeader
+            Divider()
+
+            if let message = library.generalError ?? mountLibrary.generalError {
+                errorBanner(message)
+                Divider()
+            }
+
+            ScrollView {
+                LazyVStack(spacing: 0) {
+                    GhostFileSection(
+                        title: "Shares",
+                        count: shareCount,
+                        emptyMessage: "No shares yet. Use + to add a folder.",
+                        items: shareItems,
+                        selectionOrder: visibleItemIDs,
+                        actionItems: visibleItems,
+                        expanded: $sharesExpanded,
+                        selection: $selection,
+                        focusedItemID: $focusedItemID,
+                        selectionAnchorID: $selectionAnchorID,
+                        focusTable: { tableHasFocus = true },
+                        openDetails: openDetails,
+                        start: start,
+                        stop: stop,
+                        reveal: reveal,
+                        setReadOnly: { library.setReadOnly($1, for: $0) },
+                        requestDelete: { pendingDeletion = Set($0.map(\.id)) }
+                    )
+                    Divider()
+                    GhostFileSection(
+                        title: "Mounts",
+                        count: mountCount,
+                        emptyMessage: "No mounts yet. Use + to add a connection.",
+                        items: mountItems,
+                        selectionOrder: visibleItemIDs,
+                        actionItems: visibleItems,
+                        expanded: $mountsExpanded,
+                        selection: $selection,
+                        focusedItemID: $focusedItemID,
+                        selectionAnchorID: $selectionAnchorID,
+                        focusTable: { tableHasFocus = true },
+                        openDetails: openDetails,
+                        start: start,
+                        stop: stop,
+                        reveal: reveal,
+                        setReadOnly: { library.setReadOnly($1, for: $0) },
+                        requestDelete: { pendingDeletion = Set($0.map(\.id)) }
+                    )
+                    Divider()
+                    GhostFileDiscoverSection(
+                        shares: visibleDiscoveredShares,
+                        isSearching: discovery.isSearching,
+                        selectionOrder: visibleItemIDs,
+                        expanded: $discoverExpanded,
+                        selection: $selection,
+                        focusedItemID: $focusedItemID,
+                        selectionAnchorID: $selectionAnchorID,
+                        focusTable: { tableHasFocus = true },
+                        openDetails: { openWindow(value: $0) },
+                        addMount: { share in
+                            addMountSelectionID = share.id
+                            showingAddMount = true
+                        }
+                    )
+                }
+            }
+            .background(Color(nsColor: .controlBackgroundColor).opacity(0.25))
+            .focusable()
+            .focused($tableHasFocus)
+            .focusEffectDisabled()
+            .onKeyPress(keys: [.upArrow, .downArrow]) { press in
+                moveSelection(
+                    by: press.key == .upArrow ? -1 : 1,
+                    extending: press.modifiers.contains(.shift)
+                )
+                return .handled
+            }
+            .onKeyPress(KeyEquivalent("a"), phases: .down) { press in
+                guard press.modifiers.contains(.command) else { return .ignored }
+                selectAllVisibleItems()
+                return .handled
+            }
+            .onAppear { tableHasFocus = true }
+        }
+        .alert(deleteAlertTitle, isPresented: deleteAlertIsPresented) {
+            Button("Cancel", role: .cancel) { pendingDeletion = [] }
+            Button("Delete", role: .destructive) {
+                let deletion = pendingDeletion
+                let shareIDs = Set(deletion.compactMap { id -> UUID? in
+                    guard case .share(let shareID) = id else { return nil }
+                    return shareID
+                })
+                let mountIDs = Set(deletion.compactMap { id -> UUID? in
+                    guard case .mount(let mountID) = id else { return nil }
+                    return mountID
+                })
+                library.delete(shareIDs)
+                Task {
+                    await mountLibrary.delete(mountIDs)
+                    selection.subtract(deletion)
+                    pendingDeletion = []
+                }
+            }
+        } message: {
+            Text("This removes the saved configuration. It does not delete any source files.")
+        }
+        .sheet(isPresented: $showingAddMount) {
+            GhostFileAddMountView(
+                discovery: discovery,
+                initialShareID: addMountSelectionID,
+                localShareIDs: localShareIDs,
+                discoverSelfShares: discoverSelfShares
+            )
+                .id(addMountSelectionID)
+                .environmentObject(mountLibrary)
+        }
+        .sheet(isPresented: $showingExtensionAssistant) {
+            GhostFileExtensionAssistantView(manager: mountLibrary.manager)
+        }
+        .task {
+            updateDiscoveryForDisclosure()
+            await mountLibrary.refreshExtensionStatus()
+            guard !Task.isCancelled else { return }
+            completedExtensionStartupScan = true
+            showingExtensionAssistant = mountLibrary.manager.extensionHealth.requiresAttention
+        }
+        .task {
+            await mountLibrary.monitorHealth()
+        }
+        .onChange(of: discoverExpanded) { _, _ in
+            updateDiscoveryForDisclosure()
+        }
+        .onChange(of: scenePhase) { _, phase in
+            guard phase == .active, completedExtensionStartupScan else { return }
+            Task { await mountLibrary.refreshExtensionStatus() }
+        }
+        .onDisappear {
+            discovery.stop()
+        }
+    }
+
+    private var shareItems: [GhostFileRowItem] {
+        library.shares.map { share in
+            let folder = library.folderURL(for: share.id)
+            return GhostFileRowItem(
+                id: .share(share.id),
+                kind: .share,
+                name: share.name,
+                location: abbreviatedPath(folder),
+                detail: library.shareURL(for: share.id)?.absoluteString,
+                status: rowStatus(library.status(for: share.id)),
+                readOnly: share.readOnly
+            )
+        }
+    }
+
+    private var localShareIDs: Set {
+        Set(library.shares.map(\.id))
+    }
+
+    private var visibleDiscoveredShares: [DiscoveredGhostFileShare] {
+        GhostFileDiscoveryVisibility.visibleShares(
+            from: discovery.shares,
+            localShareIDs: localShareIDs,
+            discoverSelfShares: discoverSelfShares
+        )
+    }
+
+    private func updateDiscoveryForDisclosure() {
+        if discoverExpanded {
+            discovery.start()
+        } else {
+            discovery.stop()
+        }
+    }
+
+    private var visibleItems: [GhostFileRowItem] {
+        (sharesExpanded ? shareItems : []) + (mountsExpanded ? mountItems : [])
+    }
+
+    private var visibleItemIDs: [GhostFileItemID] {
+        visibleItems.map(\.id) + (discoverExpanded
+            ? visibleDiscoveredShares.map { .discovered($0.id) }
+            : [])
+    }
+
+    private var shareCount: String {
+        guard !shareItems.isEmpty else { return "0 configured" }
+        let online = shareItems.filter { $0.status == .online }.count
+        return "\(online) of \(shareItems.count) online"
+    }
+
+    private var mountItems: [GhostFileRowItem] {
+        mountLibrary.mounts.map { mount in
+            GhostFileRowItem(
+                id: .mount(mount.id),
+                kind: .mount,
+                name: mount.name,
+                location: URL(string: mount.sourceURL)?.host ?? mount.sourceURL,
+                detail: mountLibrary.requestedMountPoint(for: mount.id)?.path,
+                status: rowStatus(mountLibrary.status(for: mount.id)),
+                readOnly: mount.readOnly
+            )
+        }
+    }
+
+    private var mountCount: String {
+        guard !mountItems.isEmpty else { return "0 configured" }
+        let mounted = mountItems.filter { $0.status.isActive }.count
+        return "\(mounted) of \(mountItems.count) mounted"
+    }
+
+    private var appHeader: some View {
+        HStack(spacing: 16) {
+            VStack(alignment: .leading, spacing: 2) {
+                Text("GhostFile").font(.title2.weight(.semibold))
+                Text("Local shares and mounted folders")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+            if !completedExtensionStartupScan || mountLibrary.manager.extensionHealth == .checking {
+                ProgressView()
+                    .controlSize(.small)
+                    .help("Checking file system extension")
+            } else if mountLibrary.manager.extensionHealth.requiresAttention {
+                Button { showingExtensionAssistant = true } label: {
+                    Image(systemName: "exclamationmark.triangle.fill")
+                        .foregroundStyle(.orange)
+                }
+                .buttonStyle(.borderless)
+                .help("File system extension needs attention")
+            }
+            Menu {
+                Button("Add Share") {
+                    if let share = library.addShareUsingPanel() {
+                        openWindow(value: GhostFileItemID.share(share.id))
+                    }
+                }
+                Button("Add Mount") {
+                    addMountSelectionID = nil
+                    showingAddMount = true
+                }
+            } label: {
+                Image(systemName: "plus")
+                    .frame(width: 14, height: 14)
+            }
+            .menuIndicator(.hidden)
+            .menuStyle(.button)
+            .buttonStyle(.bordered)
+            .controlSize(.regular)
+            .help("Add")
+
+            Button { openSettings() } label: { Image(systemName: "gearshape") }
+                .buttonStyle(.borderless)
+                .help("Settings")
+        }
+        .padding(.horizontal, 18)
+        .padding(.vertical, 12)
+    }
+
+    private func errorBanner(_ message: String) -> some View {
+        HStack(spacing: 8) {
+            Image(systemName: "exclamationmark.triangle.fill")
+                .foregroundStyle(.orange)
+            Text(message)
+                .font(.callout)
+                .lineLimit(2)
+            Spacer()
+            Button {
+                library.generalError = nil
+                mountLibrary.generalError = nil
+            } label: {
+                Image(systemName: "xmark")
+            }
+            .buttonStyle(.borderless)
+            .help("Dismiss")
+        }
+        .padding(.horizontal, 18)
+        .padding(.vertical, 9)
+        .background(Color.orange.opacity(0.08))
+    }
+
+    private func openDetails(_ item: GhostFileRowItem) {
+        openWindow(value: item.id)
+    }
+
+    private func start(_ items: [GhostFileRowItem]) {
+        var mountIDs: [UUID] = []
+        for item in items {
+            switch item.id {
+            case .share(let id):
+                library.start(id)
+            case .mount(let id):
+                mountIDs.append(id)
+            case .discovered:
+                break
+            }
+        }
+        Task {
+            for id in mountIDs {
+                await mountLibrary.mount(id)
+            }
+        }
+    }
+
+    private func stop(_ items: [GhostFileRowItem]) {
+        var mountIDs: [UUID] = []
+        for item in items {
+            switch item.id {
+            case .share(let id):
+                library.stop(id)
+            case .mount(let id):
+                mountIDs.append(id)
+            case .discovered:
+                break
+            }
+        }
+        Task {
+            for id in mountIDs {
+                await mountLibrary.unmount(id)
+            }
+        }
+    }
+
+    private func reveal(_ items: [GhostFileRowItem]) {
+        for item in items {
+            switch item.id {
+            case .share(let id): library.reveal(id)
+            case .mount(let id): mountLibrary.reveal(id)
+            case .discovered: break
+            }
+        }
+    }
+
+    private func moveSelection(by offset: Int, extending: Bool) {
+        guard !visibleItemIDs.isEmpty else { return }
+        let currentIndex = focusedItemID.flatMap { id in
+            visibleItemIDs.firstIndex(of: id)
+        }
+        let fallbackIndex = offset > 0 ? -1 : visibleItemIDs.count
+        let destinationIndex = min(
+            max((currentIndex ?? fallbackIndex) + offset, 0),
+            visibleItemIDs.count - 1
+        )
+        let destinationID = visibleItemIDs[destinationIndex]
+
+        if extending {
+            let anchorID = selectionAnchorID ?? focusedItemID ?? destinationID
+            selectionAnchorID = anchorID
+            selection = rangeSelection(from: anchorID, through: destinationID)
+        } else {
+            selection = [destinationID]
+            selectionAnchorID = destinationID
+        }
+        focusedItemID = destinationID
+    }
+
+    private func rangeSelection(
+        from anchorID: GhostFileItemID,
+        through destinationID: GhostFileItemID
+    ) -> Set {
+        guard let anchorIndex = visibleItemIDs.firstIndex(of: anchorID),
+              let destinationIndex = visibleItemIDs.firstIndex(of: destinationID) else {
+            return [destinationID]
+        }
+        let bounds = min(anchorIndex, destinationIndex)...max(anchorIndex, destinationIndex)
+        return Set(visibleItemIDs[bounds])
+    }
+
+    private func selectAllVisibleItems() {
+        selection = Set(visibleItemIDs)
+        if focusedItemID == nil || !selection.contains(focusedItemID!) {
+            focusedItemID = visibleItemIDs.first
+        }
+        selectionAnchorID = visibleItemIDs.first
+    }
+
+    private func abbreviatedPath(_ url: URL?) -> String {
+        guard let url else { return "Folder unavailable" }
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        return url.path.hasPrefix(home)
+            ? "~" + url.path.dropFirst(home.count)
+            : url.path
+    }
+
+    private func rowStatus(_ status: GhostFileShareStatus) -> GhostFileRowItem.Status {
+        switch status {
+        case .stopped: .stopped
+        case .starting: .starting
+        case .online: .online
+        case .failed(let message): .failed(message)
+        }
+    }
+
+    private func rowStatus(_ status: GhostFileSavedMountStatus) -> GhostFileRowItem.Status {
+        switch status {
+        case .stopped: .stopped
+        case .mounting: .starting
+        case .mounted: .mounted
+        case .online: .online
+        case .degraded: .degraded
+        case .error(_, let message): .error(message)
+        case .offline: .offline
+        case .failed(let message): .failed(message)
+        }
+    }
+
+    private var deleteAlertIsPresented: Binding {
+        Binding(
+            get: { !pendingDeletion.isEmpty },
+            set: { if !$0 { pendingDeletion = [] } }
+        )
+    }
+
+    private var deleteAlertTitle: String {
+        pendingDeletion.count == 1
+            ? "Delete Item?"
+            : "Delete \(pendingDeletion.count) Items?"
+    }
+}
+
+private struct GhostFileSection: View {
+    let title: String
+    let count: String
+    let emptyMessage: String
+    let items: [GhostFileRowItem]
+    let selectionOrder: [GhostFileItemID]
+    let actionItems: [GhostFileRowItem]
+    @Binding var expanded: Bool
+    @Binding var selection: Set
+    @Binding var focusedItemID: GhostFileItemID?
+    @Binding var selectionAnchorID: GhostFileItemID?
+    let focusTable: () -> Void
+    let openDetails: (GhostFileRowItem) -> Void
+    let start: ([GhostFileRowItem]) -> Void
+    let stop: ([GhostFileRowItem]) -> Void
+    let reveal: ([GhostFileRowItem]) -> Void
+    let setReadOnly: (UUID, Bool) -> Void
+    let requestDelete: ([GhostFileRowItem]) -> Void
+    @State private var pressedItemID: GhostFileItemID?
+
+    var body: some View {
+        VStack(spacing: 0) {
+            sectionHeader
+            if expanded {
+                columnHeader
+                Divider()
+                if items.isEmpty {
+                    HStack {
+                        Text(emptyMessage)
+                            .font(.callout)
+                            .foregroundStyle(.secondary)
+                        Spacer()
+                    }
+                    .padding(.horizontal, 14)
+                    .frame(height: 46)
+                } else {
+                    ForEach(items) { item in
+                        row(item)
+                        if item.id != items.last?.id {
+                            Divider().padding(.leading, 14)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    private var sectionHeader: some View {
+        HStack(spacing: 8) {
+            Image(systemName: expanded ? "chevron.down" : "chevron.right")
+                .font(.caption.weight(.semibold))
+                .frame(width: 12)
+            Text(title.uppercased()).font(.callout.weight(.semibold))
+            Text(count).font(.caption).foregroundStyle(.secondary)
+            Spacer()
+        }
+        .padding(.horizontal, 14)
+        .frame(height: 42)
+        .background(Color(nsColor: .windowBackgroundColor))
+        .contentShape(Rectangle())
+        .onTapGesture {
+            if expanded {
+                let hiddenIDs = Set(items.map(\.id))
+                selection.subtract(hiddenIDs)
+                if let focusedItemID, hiddenIDs.contains(focusedItemID) {
+                    self.focusedItemID = selection.first
+                }
+                if let selectionAnchorID, hiddenIDs.contains(selectionAnchorID) {
+                    self.selectionAnchorID = selection.first
+                }
+            }
+            expanded.toggle()
+        }
+    }
+
+    private var columnHeader: some View {
+        GhostFileColumns(
+            name: { Text("NAME") },
+            location: { Text(title == "Shares" ? "FOLDER" : "SOURCE") },
+            access: { Text("ACCESS") },
+            status: { Text("STATUS") },
+            menu: { Color.clear }
+        )
+        .font(.caption2.weight(.medium))
+        .foregroundStyle(.secondary)
+        .padding(.horizontal, 14)
+        .frame(height: 28)
+        .background(Color(nsColor: .windowBackgroundColor).opacity(0.7))
+    }
+
+    private func row(_ item: GhostFileRowItem) -> some View {
+        GhostFileColumns(
+            name: { Text(item.name).fontWeight(.medium).lineLimit(1) },
+            location: {
+                Text(item.location)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+                    .truncationMode(.middle)
+            },
+            access: {
+                if item.kind == .share {
+                    Toggle("", isOn: Binding(
+                        get: { item.readOnly },
+                        set: { value in
+                            guard case .share(let shareID) = item.id else { return }
+                            setReadOnly(shareID, value)
+                        }
+                    ))
+                        .labelsHidden()
+                        .toggleStyle(.switch)
+                        .controlSize(.mini)
+                        .help(item.readOnly ? "Read only" : "Read & write")
+                } else {
+                    Text(item.readOnly ? "Read only" : "Read & write")
+                        .foregroundStyle(.secondary)
+                }
+            },
+            status: {
+                HStack(spacing: 7) {
+                    Image(systemName: statusSymbol(for: item))
+                        .font(.body)
+                        .foregroundStyle(statusColor(for: item.status))
+                        .frame(width: 19)
+                    Text(item.status.label)
+                        .foregroundStyle(statusTextColor(for: item.status))
+                        .lineLimit(1)
+                }
+                .help(statusHelp(for: item.status))
+            },
+            menu: {
+                Menu {
+                    rowMenuItems(for: item)
+                } label: {
+                    Image(systemName: "ellipsis")
+                        .font(.body.weight(.semibold))
+                        .frame(width: 24, height: 20)
+                }
+                .menuIndicator(.hidden)
+                .menuStyle(.borderlessButton)
+                .fixedSize()
+                .help("More")
+                .accessibilityLabel("More actions for \(item.name)")
+            }
+        )
+        .padding(.horizontal, 14)
+        .frame(height: 46)
+        .background(selection.contains(item.id) ? Color.accentColor.opacity(0.14) : Color.clear)
+        .contentShape(Rectangle())
+        .overlay {
+            GhostFileMouseSelectionProbe(
+                rightClick: { prepareContextSelection(for: item) },
+                doubleClick: {
+                    select(item, modifiers: [])
+                    openDetails(item)
+                }
+            )
+        }
+        .simultaneousGesture(
+            DragGesture(minimumDistance: 0)
+                .onChanged { _ in
+                    guard pressedItemID != item.id else { return }
+                    pressedItemID = item.id
+                    focusTable()
+                    select(item, modifiers: NSEvent.modifierFlags)
+                }
+                .onEnded { _ in pressedItemID = nil }
+        )
+        .contextMenu { rowMenuItems(for: item) }
+    }
+
+    @ViewBuilder
+    private func rowMenuItems(for item: GhostFileRowItem) -> some View {
+        let selectedItems = effectiveSelectedItems(for: item)
+        let revealableItems = selectedItems.filter {
+            $0.kind == .share || $0.status.isActive || $0.detail != nil
+        }
+
+        Button("Open Details") {
+            for selectedItem in selectedItems { openDetails(selectedItem) }
+        }
+        Divider()
+        if selectedItems.contains(where: { $0.kind == .share && !$0.status.isActive }) {
+            Button("Start Sharing") {
+                start(selectedItems.filter { $0.kind == .share && !$0.status.isActive })
+            }
+        }
+        if selectedItems.contains(where: { $0.kind == .share && $0.status.isActive }) {
+            Button("Stop Sharing") {
+                stop(selectedItems.filter { $0.kind == .share && $0.status.isActive })
+            }
+        }
+        if selectedItems.contains(where: { $0.kind == .mount && !$0.status.isActive }) {
+            Button("Mount") {
+                start(selectedItems.filter { $0.kind == .mount && !$0.status.isActive })
+            }
+        }
+        if selectedItems.contains(where: { $0.kind == .mount && $0.status.isActive }) {
+            Button("Unmount") {
+                stop(selectedItems.filter { $0.kind == .mount && $0.status.isActive })
+            }
+        }
+        Button("Reveal in Finder") { reveal(revealableItems) }
+            .disabled(revealableItems.isEmpty)
+        Divider()
+        Button(deleteTitle(for: selectedItems.count), role: .destructive) {
+            requestDelete(selectedItems)
+        }
+    }
+
+    private func select(_ item: GhostFileRowItem, modifiers: NSEvent.ModifierFlags) {
+        if modifiers.contains(.shift) {
+            let anchorID = selectionAnchorID ?? focusedItemID ?? item.id
+            selectionAnchorID = anchorID
+            selection = rangeSelection(from: anchorID, through: item.id)
+        } else if modifiers.contains(.command) {
+            if selection.contains(item.id) {
+                selection.remove(item.id)
+            } else {
+                selection.insert(item.id)
+            }
+            selectionAnchorID = item.id
+        } else if !(selection.count > 1 && selection.contains(item.id)) {
+            selection = [item.id]
+            selectionAnchorID = item.id
+        }
+        focusedItemID = item.id
+    }
+
+    private func rangeSelection(
+        from anchorID: GhostFileItemID,
+        through destinationID: GhostFileItemID
+    ) -> Set {
+        guard let anchorIndex = selectionOrder.firstIndex(of: anchorID),
+              let destinationIndex = selectionOrder.firstIndex(of: destinationID) else {
+            return [destinationID]
+        }
+        let bounds = min(anchorIndex, destinationIndex)...max(anchorIndex, destinationIndex)
+        return Set(selectionOrder[bounds])
+    }
+
+    private func effectiveSelectedItems(for clickedItem: GhostFileRowItem) -> [GhostFileRowItem] {
+        let effectiveIDs = selection.contains(clickedItem.id) ? selection : [clickedItem.id]
+        return actionItems.filter { effectiveIDs.contains($0.id) }
+    }
+
+    private func prepareContextSelection(for item: GhostFileRowItem) {
+        guard !selection.contains(item.id) else { return }
+        selection = [item.id]
+        focusedItemID = item.id
+        selectionAnchorID = item.id
+        focusTable()
+    }
+
+    private func deleteTitle(for count: Int) -> String {
+        count == 1 ? "Delete…" : "Delete \(count) Items…"
+    }
+
+    private func statusSymbol(for item: GhostFileRowItem) -> String {
+        switch (item.kind, item.status) {
+        case (.share, .online): "folder.fill.badge.person.crop"
+        case (.share, .starting): "folder.badge.clock"
+        case (.share, .stopped): "folder"
+        case (.share, .mounted): "folder.fill.badge.person.crop"
+        case (.share, .degraded): "folder.badge.questionmark"
+        case (.share, .error): "folder.fill.badge.xmark"
+        case (.share, .offline): "folder"
+        case (.share, .failed): "folder.fill.badge.xmark"
+        case (.mount, .online): "externaldrive.fill.badge.checkmark"
+        case (.mount, .starting): "externaldrive.badge.timemachine"
+        case (.mount, .stopped): "externaldrive.fill.badge.wifi"
+        case (.mount, .mounted): "externaldrive.connected.to.line.below.fill"
+        case (.mount, .degraded): "externaldrive.fill.badge.wifi"
+        case (.mount, .error): "externaldrive.fill.badge.xmark"
+        case (.mount, .offline): "externaldrive.fill"
+        case (.mount, .failed): "externaldrive.fill.badge.xmark"
+        }
+    }
+
+    private func statusColor(for status: GhostFileRowItem.Status) -> Color {
+        switch status {
+        case .online, .mounted: .green
+        case .starting: .blue
+        case .stopped: .secondary
+        case .degraded: .orange
+        case .error, .failed: .red
+        case .offline: .secondary
+        }
+    }
+
+    private func statusTextColor(for status: GhostFileRowItem.Status) -> Color {
+        if case .degraded = status { return .orange }
+        if case .error = status { return .red }
+        if case .failed = status { return .red }
+        return .secondary
+    }
+
+    private func statusHelp(for status: GhostFileRowItem.Status) -> String {
+        if case .error(let message) = status { return message }
+        if case .failed(let message) = status { return message }
+        return status.label
+    }
+}
+
+private struct GhostFileDiscoverSection: View {
+    let shares: [DiscoveredGhostFileShare]
+    let isSearching: Bool
+    let selectionOrder: [GhostFileItemID]
+    @Binding var expanded: Bool
+    @Binding var selection: Set
+    @Binding var focusedItemID: GhostFileItemID?
+    @Binding var selectionAnchorID: GhostFileItemID?
+    let focusTable: () -> Void
+    let openDetails: (DiscoveredGhostFileShare) -> Void
+    let addMount: (DiscoveredGhostFileShare) -> Void
+    @State private var pressedShareID: UUID?
+
+    var body: some View {
+        VStack(spacing: 0) {
+            sectionHeader
+            if expanded {
+                columnHeader
+                Divider()
+                if shares.isEmpty {
+                    HStack {
+                        if isSearching {
+                            ProgressView().controlSize(.small)
+                        }
+                        Text(isSearching
+                            ? "Looking for nearby GhostFile shares…"
+                            : "No nearby GhostFile shares found.")
+                            .font(.callout)
+                            .foregroundStyle(.secondary)
+                        Spacer()
+                    }
+                    .padding(.horizontal, 14)
+                    .frame(height: 46)
+                } else {
+                    ForEach(shares) { share in
+                        row(share)
+                        if share.id != shares.last?.id {
+                            Divider().padding(.leading, 14)
+                        }
+                    }
+                }
+            }
+        }
+        .onChange(of: shares.map(\.id)) { _, availableIDs in
+            let availableItemIDs = Set(availableIDs.map { GhostFileItemID.discovered($0) })
+            let removedItemIDs = selection.filter { itemID in
+                guard case .discovered = itemID else { return false }
+                return !availableItemIDs.contains(itemID)
+            }
+            guard !removedItemIDs.isEmpty else { return }
+            selection.subtract(removedItemIDs)
+            if let focusedItemID, removedItemIDs.contains(focusedItemID) {
+                self.focusedItemID = selection.first
+            }
+            if let selectionAnchorID, removedItemIDs.contains(selectionAnchorID) {
+                self.selectionAnchorID = selection.first
+            }
+        }
+    }
+
+    private var sectionHeader: some View {
+        HStack(spacing: 8) {
+            Image(systemName: expanded ? "chevron.down" : "chevron.right")
+                .font(.caption.weight(.semibold))
+                .frame(width: 12)
+            Text("DISCOVER").font(.callout.weight(.semibold))
+            Text(discoveryCount).font(.caption).foregroundStyle(.secondary)
+            Spacer()
+        }
+        .padding(.horizontal, 14)
+        .frame(height: 42)
+        .background(Color(nsColor: .windowBackgroundColor))
+        .contentShape(Rectangle())
+        .onTapGesture {
+            if expanded {
+                let hiddenIDs = Set(shares.map { GhostFileItemID.discovered($0.id) })
+                selection.subtract(hiddenIDs)
+                if let focusedItemID, hiddenIDs.contains(focusedItemID) {
+                    self.focusedItemID = selection.first
+                }
+                if let selectionAnchorID, hiddenIDs.contains(selectionAnchorID) {
+                    self.selectionAnchorID = selection.first
+                }
+            }
+            expanded.toggle()
+        }
+    }
+
+    private var discoveryCount: String {
+        switch shares.count {
+        case 0: isSearching ? "searching" : "0 nearby"
+        case 1: "1 nearby"
+        default: "\(shares.count) nearby"
+        }
+    }
+
+    private var columnHeader: some View {
+        GhostFileDiscoverColumns(
+            name: { Text("NAME") },
+            host: { Text("HOST") },
+            service: { Text("SERVICE") },
+            port: { Text("PORT") },
+            menu: { Color.clear }
+        )
+        .font(.caption2.weight(.medium))
+        .foregroundStyle(.secondary)
+        .padding(.horizontal, 14)
+        .frame(height: 28)
+        .background(Color(nsColor: .windowBackgroundColor).opacity(0.7))
+    }
+
+    private func row(_ share: DiscoveredGhostFileShare) -> some View {
+        let itemID = GhostFileItemID.discovered(share.id)
+        return GhostFileDiscoverColumns(
+            name: {
+                HStack(spacing: 7) {
+                    Image(systemName: "dot.radiowaves.left.and.right")
+                        .foregroundStyle(.green)
+                        .frame(width: 19)
+                    Text(share.name).fontWeight(.medium).lineLimit(1)
+                }
+            },
+            host: {
+                Text(share.host)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+                    .truncationMode(.middle)
+            },
+            service: {
+                Text(share.serviceType)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+            },
+            port: {
+                Text(String(share.port))
+                    .foregroundStyle(.secondary)
+                    .monospacedDigit()
+            },
+            menu: {
+                Menu {
+                    menuItems(for: share)
+                } label: {
+                    Image(systemName: "ellipsis")
+                        .font(.body.weight(.semibold))
+                        .frame(width: 24, height: 20)
+                }
+                .menuIndicator(.hidden)
+                .menuStyle(.borderlessButton)
+                .fixedSize()
+                .help("More")
+                .accessibilityLabel("More actions for \(share.name)")
+            }
+        )
+        .padding(.horizontal, 14)
+        .frame(height: 46)
+        .background(selection.contains(itemID) ? Color.accentColor.opacity(0.14) : Color.clear)
+        .contentShape(Rectangle())
+        .overlay {
+            GhostFileMouseSelectionProbe(
+                rightClick: { prepareContextSelection(for: share) },
+                doubleClick: {
+                    select(share, modifiers: [])
+                    openDetails(share)
+                }
+            )
+        }
+        .simultaneousGesture(
+            DragGesture(minimumDistance: 0)
+                .onChanged { _ in
+                    guard pressedShareID != share.id else { return }
+                    pressedShareID = share.id
+                    focusTable()
+                    select(share, modifiers: NSEvent.modifierFlags)
+                }
+                .onEnded { _ in pressedShareID = nil }
+        )
+        .contextMenu { menuItems(for: share) }
+    }
+
+    @ViewBuilder
+    private func menuItems(for share: DiscoveredGhostFileShare) -> some View {
+        let selectedShares = effectiveSelectedShares(for: share)
+        Button("Open Details") {
+            for selectedShare in selectedShares { openDetails(selectedShare) }
+        }
+        Divider()
+        Button("Add Mount…") {
+            if let selectedShare = selectedShares.first { addMount(selectedShare) }
+        }
+        .disabled(selectedShares.count != 1)
+    }
+
+    private func select(
+        _ share: DiscoveredGhostFileShare,
+        modifiers: NSEvent.ModifierFlags
+    ) {
+        let itemID = GhostFileItemID.discovered(share.id)
+        if modifiers.contains(.shift) {
+            let anchorID = selectionAnchorID ?? focusedItemID ?? itemID
+            selectionAnchorID = anchorID
+            selection = rangeSelection(from: anchorID, through: itemID)
+        } else if modifiers.contains(.command) {
+            if selection.contains(itemID) {
+                selection.remove(itemID)
+            } else {
+                selection.insert(itemID)
+            }
+            selectionAnchorID = itemID
+        } else if !(selection.count > 1 && selection.contains(itemID)) {
+            selection = [itemID]
+            selectionAnchorID = itemID
+        }
+        focusedItemID = itemID
+    }
+
+    private func rangeSelection(
+        from anchorID: GhostFileItemID,
+        through destinationID: GhostFileItemID
+    ) -> Set {
+        guard let anchorIndex = selectionOrder.firstIndex(of: anchorID),
+              let destinationIndex = selectionOrder.firstIndex(of: destinationID) else {
+            return [destinationID]
+        }
+        let bounds = min(anchorIndex, destinationIndex)...max(anchorIndex, destinationIndex)
+        return Set(selectionOrder[bounds])
+    }
+
+    private func effectiveSelectedShares(
+        for clickedShare: DiscoveredGhostFileShare
+    ) -> [DiscoveredGhostFileShare] {
+        let clickedID = GhostFileItemID.discovered(clickedShare.id)
+        let effectiveIDs = selection.contains(clickedID) ? selection : [clickedID]
+        return shares.filter { effectiveIDs.contains(.discovered($0.id)) }
+    }
+
+    private func prepareContextSelection(for share: DiscoveredGhostFileShare) {
+        let itemID = GhostFileItemID.discovered(share.id)
+        guard !selection.contains(itemID) else { return }
+        selection = [itemID]
+        focusedItemID = itemID
+        selectionAnchorID = itemID
+        focusTable()
+    }
+}
+
+private struct GhostFileMouseSelectionProbe: NSViewRepresentable {
+    let rightClick: () -> Void
+    let doubleClick: () -> Void
+
+    func makeNSView(context: Context) -> ProbeView {
+        let view = ProbeView()
+        view.rightClick = rightClick
+        view.doubleClick = doubleClick
+        return view
+    }
+
+    func updateNSView(_ nsView: ProbeView, context: Context) {
+        nsView.rightClick = rightClick
+        nsView.doubleClick = doubleClick
+    }
+
+    final class ProbeView: NSView {
+        var rightClick: (() -> Void)?
+        var doubleClick: (() -> Void)?
+        private var lastHandledRightClickEventNumber: Int?
+        private var lastHandledDoubleClickEventNumber: Int?
+
+        override func hitTest(_ point: NSPoint) -> NSView? {
+            guard let event = NSApp.currentEvent else { return nil }
+            if event.type == .rightMouseDown,
+               lastHandledRightClickEventNumber != event.eventNumber {
+                lastHandledRightClickEventNumber = event.eventNumber
+                rightClick?()
+            } else if event.type == .leftMouseDown,
+                      event.clickCount == 2,
+                      lastHandledDoubleClickEventNumber != event.eventNumber {
+                lastHandledDoubleClickEventNumber = event.eventNumber
+                doubleClick?()
+            }
+            return nil
+        }
+    }
+}
+
+private struct GhostFileColumns: View {
+    @ViewBuilder let name: () -> Name
+    @ViewBuilder let location: () -> Location
+    @ViewBuilder let access: () -> Access
+    @ViewBuilder let status: () -> Status
+    @ViewBuilder let menu: () -> MenuContent
+
+    var body: some View {
+        HStack(spacing: 12) {
+            name().frame(minWidth: 150, maxWidth: .infinity, alignment: .leading)
+            location().frame(minWidth: 190, maxWidth: .infinity, alignment: .leading)
+            access().frame(width: 108, alignment: .leading)
+            status().frame(width: 132, alignment: .leading)
+            menu().frame(width: 30, alignment: .center)
+        }
+    }
+}
+
+private struct GhostFileDiscoverColumns: View {
+    @ViewBuilder let name: () -> Name
+    @ViewBuilder let host: () -> Host
+    @ViewBuilder let service: () -> Service
+    @ViewBuilder let port: () -> Port
+    @ViewBuilder let menu: () -> MenuContent
+
+    var body: some View {
+        HStack(spacing: 12) {
+            name().frame(minWidth: 180, maxWidth: .infinity, alignment: .leading)
+            host().frame(minWidth: 180, maxWidth: .infinity, alignment: .leading)
+            service().frame(width: 130, alignment: .leading)
+            port().frame(width: 70, alignment: .leading)
+            menu().frame(width: 30, alignment: .center)
+        }
+    }
+}
+
+struct GhostFileDiscoveredDetailView: View {
+    @EnvironmentObject private var mountLibrary: GhostFileMountLibrary
+    let share: DiscoveredGhostFileShare
+    @State private var showingAddMount = false
+
+    var body: some View {
+        VStack(spacing: 0) {
+            HStack(spacing: 12) {
+                Image(systemName: "dot.radiowaves.left.and.right")
+                    .font(.title2)
+                    .foregroundStyle(.green)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(share.name).font(.title2.weight(.semibold))
+                    Text("Available nearby")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+                Button("Add Mount…") { showingAddMount = true }
+                    .buttonStyle(.borderedProminent)
+            }
+            .padding(18)
+            Divider()
+            Form {
+                Section("Service") {
+                    LabeledContent("Host", value: share.host)
+                    LabeledContent("Type", value: share.serviceType)
+                    LabeledContent("Port", value: String(share.port))
+                    LabeledContent("Transport", value: share.transport)
+                }
+                Section("Share") {
+                    LabeledContent("Identifier", value: share.id.uuidString.lowercased())
+                    LabeledContent("Access", value: share.readOnly ? "Read only" : "Read & write")
+                    LabeledContent("URL") {
+                        Text(share.url?.absoluteString ?? "Unavailable")
+                            .foregroundStyle(.secondary)
+                            .lineLimit(2)
+                            .truncationMode(.middle)
+                    }
+                }
+                Section("Security") {
+                    Label(
+                        "This identity came from unauthenticated local-network discovery.",
+                        systemImage: "exclamationmark.shield"
+                    )
+                    .foregroundStyle(.orange)
+                    LabeledContent("Public-key fingerprint") {
+                        Text(share.publicKeyPin)
+                            .font(.system(.caption, design: .monospaced))
+                            .textSelection(.enabled)
+                    }
+                    Text("Compare this fingerprint with the sharing Mac before entering an access key.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+            }
+            .formStyle(.grouped)
+        }
+        .sheet(isPresented: $showingAddMount) {
+            GhostFileAddMountView(initialShare: share)
+                .environmentObject(mountLibrary)
+        }
+    }
+}
+
+struct GhostFileDetailView: View {
+    @EnvironmentObject private var library: GhostFileLibrary
+    @EnvironmentObject private var mountLibrary: GhostFileMountLibrary
+    let itemID: GhostFileItemID
+
+    var body: some View {
+        switch itemID {
+        case .share(let id):
+            if let share = library.share(withID: id) {
+                GhostFileShareDetailEditor(share: share)
+            } else {
+                ContentUnavailableView("Share Not Found", systemImage: "folder.badge.questionmark")
+            }
+        case .mount(let id):
+            if let mount = mountLibrary.mount(withID: id) {
+                GhostFileMountDetailEditor(mount: mount)
+            } else {
+                ContentUnavailableView("Mount Not Found", systemImage: "externaldrive.badge.questionmark")
+            }
+        case .discovered:
+            ContentUnavailableView(
+                "Discovered Share Not Found",
+                systemImage: "dot.radiowaves.left.and.right"
+            )
+        }
+    }
+}
+
+private struct GhostFileShareDetailEditor: View {
+    private struct Draft: Equatable {
+        let name: String
+        let portText: String
+        let accessKey: String
+        let replacementFolder: URL?
+    }
+
+    @EnvironmentObject private var library: GhostFileLibrary
+    let share: SavedGhostFileShare
+    @State private var name: String
+    @State private var portText: String
+    @State private var readOnly: Bool
+    @State private var accessKey = ""
+    @State private var replacementFolder: URL?
+    @State private var editorError: String?
+    @State private var didLoadAccessKey = false
+    @State private var lastSavedDraft: Draft?
+    @State private var autosaveTask: Task?
+    @State private var publicKeyPin: String?
+    @State private var showingIdentityRotationConfirmation = false
+
+    init(share: SavedGhostFileShare) {
+        self.share = share
+        _name = State(initialValue: share.name)
+        _portText = State(initialValue: String(share.preferredPort))
+        _readOnly = State(initialValue: share.readOnly)
+    }
+
+    var body: some View {
+        let status = library.status(for: share.id)
+        VStack(spacing: 0) {
+            HStack(spacing: 12) {
+                Image(systemName: "folder.badge.person.crop")
+                    .font(.title2)
+                    .foregroundStyle(.tint)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(name).font(.title2.weight(.semibold))
+                    Text(statusLabel(status))
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+                Button(isActive(status) ? "Stop" : "Start") {
+                    if isActive(status) {
+                        _ = flushAutosave()
+                        library.stop(share.id)
+                    } else if flushAutosave() {
+                        library.start(share.id)
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .tint(isActive(status) ? .red : .green)
+                .controlSize(.large)
+            }
+            .padding(18)
+
+            Divider()
+
+            Form {
+                Section("Folder") {
+                    LabeledContent("Source") {
+                        HStack {
+                            Text(displayedFolder?.path ?? "Folder unavailable")
+                                .foregroundStyle(.secondary)
+                                .lineLimit(1)
+                                .truncationMode(.middle)
+                            Button("Reveal") { library.reveal(share.id) }
+                                .disabled(replacementFolder != nil)
+                            Button("Change…") { chooseReplacementFolder() }
+                        }
+                    }
+                }
+                Section("Connection") {
+                    TextField("Share name", text: $name)
+                        .onSubmit { _ = flushAutosave() }
+                    LabeledContent(
+                        "Share URL",
+                        value: library.shareURL(for: share.id)?.absoluteString ?? "Available when online"
+                    )
+                    LabeledContent("Public-key fingerprint") {
+                        Text(publicKeyPin ?? "Unavailable")
+                            .font(.system(.caption, design: .monospaced))
+                            .foregroundStyle(publicKeyPin == nil ? .secondary : .primary)
+                            .textSelection(.enabled)
+                    }
+                    TextField("Preferred port", text: $portText)
+                        .onSubmit { _ = flushAutosave() }
+                    HStack {
+                        SecureField("Access key", text: $accessKey)
+                            .onSubmit { _ = flushAutosave() }
+                        Button("Copy") {
+                            NSPasteboard.general.clearContents()
+                            NSPasteboard.general.setString(accessKey, forType: .string)
+                        }
+                        Button("Regenerate") {
+                            accessKey = UUID().uuidString.lowercased()
+                        }
+                    }
+                    Button("Rotate Share Identity…", role: .destructive) {
+                        showingIdentityRotationConfirmation = true
+                    }
+                    .disabled(isActive(status))
+                }
+                Section("Access") {
+                    Toggle("Read only", isOn: Binding(
+                        get: { readOnly },
+                        set: { value in
+                            library.setReadOnly(value, for: share.id)
+                            readOnly = library.share(withID: share.id)?.readOnly ?? readOnly
+                        }
+                    ))
+                    Text("Changes apply immediately to current and new client connections.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Section("Activity") {
+                    LabeledContent("Requests", value: String(library.requestCount(for: share.id)))
+                }
+                if case .failed(let message) = status {
+                    Section("Error") {
+                        Text(message).foregroundStyle(.red)
+                    }
+                }
+                if let editorError {
+                    Section {
+                        Text(editorError).foregroundStyle(.red)
+                    }
+                }
+            }
+            .formStyle(.grouped)
+        }
+        .task { loadAccessKeyIfNeeded() }
+        .confirmationDialog(
+            "Rotate this share’s TLS identity?",
+            isPresented: $showingIdentityRotationConfirmation,
+            titleVisibility: .visible
+        ) {
+            Button("Rotate Identity", role: .destructive) {
+                library.rotateTLSIdentity(for: share.id)
+                loadPublicKeyPin()
+            }
+        } message: {
+            Text("Existing links and saved mounts will no longer trust this share. Send clients the new link before reconnecting.")
+        }
+        .onChange(of: name) { _, _ in scheduleAutosave() }
+        .onChange(of: portText) { _, _ in scheduleAutosave() }
+        .onChange(of: accessKey) { _, _ in scheduleAutosave() }
+        .onDisappear { _ = flushAutosave() }
+    }
+
+    private func isActive(_ status: GhostFileShareStatus) -> Bool {
+        status == .online || status == .starting
+    }
+
+    private func statusLabel(_ status: GhostFileShareStatus) -> String {
+        switch status {
+        case .stopped: "Stopped"
+        case .starting: "Starting"
+        case .online: "Online"
+        case .failed: "Failed"
+        }
+    }
+
+    private var displayedFolder: URL? {
+        replacementFolder ?? library.folderURL(for: share.id)
+    }
+
+    private var parsedPort: UInt16? {
+        UInt16(portText.trimmingCharacters(in: .whitespacesAndNewlines))
+    }
+
+    private var draft: Draft {
+        Draft(
+            name: name,
+            portText: portText,
+            accessKey: accessKey,
+            replacementFolder: replacementFolder
+        )
+    }
+
+    private func scheduleAutosave(delay: Duration = .milliseconds(400)) {
+        guard didLoadAccessKey, draft != lastSavedDraft else { return }
+        autosaveTask?.cancel()
+        autosaveTask = Task { @MainActor in
+            try? await Task.sleep(for: delay)
+            guard !Task.isCancelled else { return }
+            _ = save()
+            autosaveTask = nil
+        }
+    }
+
+    @discardableResult
+    private func flushAutosave() -> Bool {
+        autosaveTask?.cancel()
+        autosaveTask = nil
+        guard didLoadAccessKey else { return false }
+        guard draft != lastSavedDraft else { return true }
+        return save()
+    }
+
+    @discardableResult
+    private func save() -> Bool {
+        guard let preferredPort = parsedPort else {
+            editorError = "The port must be between 0 and 65535. Use 0 to choose automatically."
+            return false
+        }
+        do {
+            try library.updateShare(
+                share.id,
+                name: name,
+                preferredPort: preferredPort,
+                accessKey: accessKey,
+                folderURL: replacementFolder
+            )
+            replacementFolder = nil
+            editorError = nil
+            lastSavedDraft = draft
+            return true
+        } catch {
+            editorError = error.localizedDescription
+            return false
+        }
+    }
+
+    private func loadAccessKeyIfNeeded() {
+        guard !didLoadAccessKey else { return }
+        didLoadAccessKey = true
+        do {
+            accessKey = try library.accessKey(for: share.id)
+            loadPublicKeyPin()
+            lastSavedDraft = draft
+        } catch {
+            editorError = error.localizedDescription
+        }
+    }
+
+    private func loadPublicKeyPin() {
+        publicKeyPin = try? library.publicKeyPin(for: share.id)
+    }
+
+    private func chooseReplacementFolder() {
+        let panel = NSOpenPanel()
+        panel.title = "Choose a new folder for “\(share.name)”"
+        panel.prompt = "Choose Folder"
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = displayedFolder
+        guard panel.runModal() == .OK else { return }
+        replacementFolder = panel.url
+        scheduleAutosave(delay: .zero)
+    }
+}
+
+private struct GhostFileExtensionAssistantView: View {
+    @Environment(\.dismiss) private var dismiss
+    @ObservedObject var manager: GhostFileMountManager
+
+    var body: some View {
+        VStack(spacing: 0) {
+            VStack(spacing: 14) {
+                statusSymbol
+                Text(title)
+                    .font(.title2.weight(.semibold))
+                Text(detail)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+                    .fixedSize(horizontal: false, vertical: true)
+                    .frame(maxWidth: 440)
+            }
+            .padding(.horizontal, 32)
+            .padding(.top, 30)
+            .padding(.bottom, 24)
+
+            Divider()
+
+            VStack(alignment: .leading, spacing: 12) {
+                helperRow(
+                    symbol: "shippingbox.fill",
+                    title: "Embedded with GhostFile",
+                    detail: "The file system module is installed and repaired as part of the app."
+                )
+                helperRow(
+                    symbol: "checkmark.shield.fill",
+                    title: "Approval stays with you",
+                    detail: "macOS may require you to enable GhostFileFS in System Settings. GhostFile will never bypass that approval."
+                )
+            }
+            .padding(24)
+
+            Divider()
+
+            HStack {
+                if manager.extensionHealth.requiresAttention {
+                    Button("Later") { dismiss() }
+                }
+                Spacer()
+                Button("Scan Again") {
+                    Task { await manager.refreshExtensionStatus() }
+                }
+                .disabled(manager.isWorking || manager.extensionHealth == .checking)
+
+                primaryAction
+            }
+            .padding(18)
+        }
+        .frame(width: 540)
+        .interactiveDismissDisabled(manager.isWorking)
+    }
+
+    @ViewBuilder
+    private var statusSymbol: some View {
+        if manager.isWorking || manager.extensionHealth == .checking {
+            ProgressView()
+                .controlSize(.large)
+                .frame(width: 52, height: 52)
+        } else {
+            Image(systemName: symbolName)
+                .font(.system(size: 38, weight: .semibold))
+                .foregroundStyle(symbolColor)
+                .frame(width: 52, height: 52)
+        }
+    }
+
+    @ViewBuilder
+    private var primaryAction: some View {
+        switch manager.extensionHealth {
+        case .ready:
+            Button("Done") { dismiss() }
+                .buttonStyle(.borderedProminent)
+        case .needsApplicationInstall, .missingEmbeddedExtension:
+            Button("Open Applications") {
+                NSWorkspace.shared.open(URL(fileURLWithPath: "/Applications", isDirectory: true))
+            }
+            .buttonStyle(.borderedProminent)
+        case .notRegistered, .duplicateRegistrations, .disabled:
+            if manager.extensionRepairAvailable {
+                Button(manager.isWorking ? "Repairing…" : "Install / Repair Extension") {
+                    Task { await manager.repairExtensionRegistration() }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(manager.isWorking || !manager.mountedShares.isEmpty)
+            } else {
+                Button("Open File System Settings") { manager.openExtensionSettings() }
+                    .buttonStyle(.borderedProminent)
+            }
+        case .scanFailed:
+            Button("Open File System Settings") { manager.openExtensionSettings() }
+                .buttonStyle(.borderedProminent)
+        case .checking:
+            EmptyView()
+        }
+    }
+
+    private var title: String {
+        if manager.isWorking { return "Repairing GhostFileFS…" }
+        switch manager.extensionHealth {
+        case .checking: return "Checking GhostFileFS…"
+        case .ready: return "GhostFileFS Is Ready"
+        case .needsApplicationInstall: return "Move GhostFile to Applications"
+        case .missingEmbeddedExtension: return "GhostFileFS Is Missing"
+        case .notRegistered: return "Install GhostFileFS"
+        case .duplicateRegistrations: return "Repair GhostFileFS"
+        case .disabled: return "Enable GhostFileFS"
+        case .scanFailed: return "Unable to Check GhostFileFS"
+        }
+    }
+
+    private var detail: String {
+        if manager.isWorking {
+            return "GhostFile is verifying the app and rebuilding the macOS extension registration."
+        }
+        if manager.extensionRepairAvailable, !manager.mountedShares.isEmpty {
+            return "Unmount all GhostFile volumes before repairing the file system extension."
+        }
+        if let statusDetail = manager.extensionStatusDetail { return statusDetail }
+        switch manager.extensionHealth {
+        case .checking: return "Scanning macOS file system extension registration."
+        case .ready: return "The embedded extension is registered, enabled, and ready to mount shares."
+        case .needsApplicationInstall: return "Drag GhostFile into Applications, then open that installed copy."
+        case .missingEmbeddedExtension: return "Reinstall GhostFile from the disk image to restore its embedded extension."
+        case .notRegistered: return "macOS has not registered the extension bundled with this app."
+        case .duplicateRegistrations: return "More than one copy is registered, so macOS may launch the wrong one."
+        case .disabled: return "Repair registration, then approve GhostFileFS in System Settings if macOS asks."
+        case .scanFailed(let message): return message
+        }
+    }
+
+    private var symbolName: String {
+        switch manager.extensionHealth {
+        case .ready: "checkmark.circle.fill"
+        case .needsApplicationInstall: "arrow.down.app.fill"
+        case .missingEmbeddedExtension: "xmark.app.fill"
+        case .notRegistered: "externaldrive.badge.plus"
+        case .duplicateRegistrations: "wrench.and.screwdriver.fill"
+        case .disabled: "externaldrive.fill.badge.exclamationmark"
+        case .scanFailed: "exclamationmark.triangle.fill"
+        case .checking: "externaldrive.fill"
+        }
+    }
+
+    private var symbolColor: Color {
+        manager.extensionHealth == .ready ? .green : .orange
+    }
+
+    private func helperRow(symbol: String, title: String, detail: String) -> some View {
+        HStack(alignment: .top, spacing: 12) {
+            Image(systemName: symbol)
+                .foregroundStyle(.secondary)
+                .frame(width: 22)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(title).fontWeight(.medium)
+                Text(detail)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+}
+
+struct GhostFileSettingsView: View {
+    @AppStorage("ghostfile.discoverSelfShares") private var discoverSelfShares = false
+
+    var body: some View {
+        Form {
+            Section("Discover") {
+                Toggle("Discover Self-Shares", isOn: $discoverSelfShares)
+                Text("Show shares hosted by this Mac alongside nearby shares in Discover.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+        .formStyle(.grouped)
+        .frame(width: 460, height: 170)
+    }
+}
+
+private struct GhostFileAddMountView: View {
+    @Environment(\.dismiss) private var dismiss
+    @EnvironmentObject private var mountLibrary: GhostFileMountLibrary
+    @ObservedObject var discovery: GhostFileDiscovery
+    let localShareIDs: Set
+    let discoverSelfShares: Bool
+    let fixedInitialShare: DiscoveredGhostFileShare?
+    @State private var selectedShareID: UUID?
+    @State private var name = "GhostFile Share"
+    @State private var sourceURL = ""
+    @State private var accessKey = ""
+    @State private var mountPoint: URL?
+    @State private var readOnly = true
+    @State private var errorMessage: String?
+    @State private var isSavingAndMounting = false
+    @State private var confirmedDiscoveredIdentity = false
+
+    init(
+        discovery: GhostFileDiscovery,
+        initialShareID: UUID? = nil,
+        localShareIDs: Set = [],
+        discoverSelfShares: Bool = false
+    ) {
+        self.discovery = discovery
+        self.localShareIDs = localShareIDs
+        self.discoverSelfShares = discoverSelfShares
+        self.fixedInitialShare = nil
+        _selectedShareID = State(initialValue: initialShareID)
+        let shares = GhostFileDiscoveryVisibility.visibleShares(
+            from: discovery.shares,
+            localShareIDs: localShareIDs,
+            discoverSelfShares: discoverSelfShares
+        )
+        if let share = shares.first(where: { $0.id == initialShareID }) {
+            _name = State(initialValue: share.name)
+            _sourceURL = State(initialValue: share.url?.absoluteString ?? "")
+            _readOnly = State(initialValue: share.readOnly)
+        }
+    }
+
+    init(initialShare: DiscoveredGhostFileShare) {
+        self.discovery = GhostFileDiscovery()
+        self.localShareIDs = []
+        self.discoverSelfShares = true
+        self.fixedInitialShare = initialShare
+        _selectedShareID = State(initialValue: initialShare.id)
+        _name = State(initialValue: initialShare.name)
+        _sourceURL = State(initialValue: initialShare.url?.absoluteString ?? "")
+        _readOnly = State(initialValue: initialShare.readOnly)
+    }
+
+    private var nearbyShares: [DiscoveredGhostFileShare] {
+        let discoveredShares = GhostFileDiscoveryVisibility.visibleShares(
+            from: discovery.shares,
+            localShareIDs: localShareIDs,
+            discoverSelfShares: discoverSelfShares
+        )
+        guard let fixedInitialShare else { return discoveredShares }
+        return [fixedInitialShare] + discoveredShares.filter { $0.id != fixedInitialShare.id }
+    }
+
+    var body: some View {
+        VStack(spacing: 0) {
+            HStack {
+                VStack(alignment: .leading, spacing: 2) {
+                    Text("Add Mount").font(.title2.weight(.semibold))
+                    Text("Save a remote GhostFile share as a mountable volume.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+            }
+            .padding(18)
+            Divider()
+
+            ScrollView {
+                VStack(alignment: .leading, spacing: 24) {
+                    if !nearbyShares.isEmpty {
+                        mountFormSection("Nearby Shares") {
+                            mountFormRow("Share") {
+                                Picker("Share", selection: $selectedShareID) {
+                                    Text("Choose a nearby share…").tag(UUID?.none)
+                                    ForEach(nearbyShares) { share in
+                                        Text("\(share.name) — \(share.host)").tag(Optional(share.id))
+                                    }
+                                }
+                                .labelsHidden()
+                                .onChange(of: selectedShareID) { _, id in
+                                    guard let share = nearbyShares.first(where: { $0.id == id }) else { return }
+                                    name = share.name
+                                    sourceURL = share.url?.absoluteString ?? ""
+                                    readOnly = share.readOnly
+                                    confirmedDiscoveredIdentity = false
+                                }
+                            }
+                        }
+                    }
+
+                    mountFormSection(
+                        "Connection",
+                        statusIsSatisfied: hasAccessKey,
+                        missingLabel: "Access key required",
+                        missingSymbol: "xmark.circle.fill",
+                        missingColor: .red
+                    ) {
+                        mountFormRow("Volume name") {
+                            TextField("Volume name", text: $name)
+                                .labelsHidden()
+                                .multilineTextAlignment(.trailing)
+                        }
+                        Divider()
+                        mountFormRow("Share URL") {
+                            TextField(
+                                "Share URL",
+                                text: $sourceURL,
+                                prompt: Text("ghostfile://host/v1/shares/…")
+                            )
+                            .labelsHidden()
+                            .multilineTextAlignment(.trailing)
+                        }
+                        Divider()
+                        mountFormRow("Access key") {
+                            SecureField("", text: $accessKey, prompt: Text("Enter access key"))
+                                .textFieldStyle(.roundedBorder)
+                                .accessibilityLabel("Access key")
+                        }
+                    }
+
+                    if let discoveredShare = selectedDiscoveredShare {
+                        mountFormSection(
+                            "Verify Identity",
+                            statusIsSatisfied: confirmedDiscoveredIdentity,
+                            missingLabel: "Fingerprint verification required",
+                            missingSymbol: "exclamationmark.triangle.fill",
+                            missingColor: .orange
+                        ) {
+                            Label(
+                                "Nearby discovery is not an authenticated source of identity.",
+                                systemImage: "exclamationmark.shield"
+                            )
+                            .foregroundStyle(.orange)
+                            .frame(maxWidth: .infinity, alignment: .leading)
+                            .padding(.horizontal, 12)
+                            .padding(.vertical, 11)
+                            Divider()
+                            mountFormRow("Fingerprint") {
+                                Text(discoveredShare.publicKeyPin)
+                                    .font(.system(.caption, design: .monospaced))
+                                    .lineLimit(1)
+                                    .truncationMode(.middle)
+                                    .textSelection(.enabled)
+                            }
+                            Divider()
+                            mountFormRow("Verify fingerprint") {
+                                Toggle(
+                                    "I verified it with the person sharing the folder",
+                                    isOn: $confirmedDiscoveredIdentity
+                                )
+                                .toggleStyle(.checkbox)
+                                .frame(maxWidth: .infinity, alignment: .leading)
+                            }
+                        }
+                    }
+
+                    mountFormSection("Mount Point") {
+                        mountFormRow("Location") {
+                            HStack {
+                                Text(mountPoint?.path ?? "Automatic — ~/GhostFiles")
+                                    .foregroundStyle(mountPoint == nil ? .secondary : .primary)
+                                    .lineLimit(1)
+                                    .truncationMode(.middle)
+                                if mountPoint != nil {
+                                    Button("Use Automatic") { mountPoint = nil }
+                                }
+                                Button("Choose…") { chooseMountPoint() }
+                            }
+                        }
+                    }
+
+                    mountFormSection("Access") {
+                        mountFormRow("Mode") {
+                            Text(readOnly ? "Read only" : "Read & write")
+                                .foregroundStyle(.secondary)
+                        }
+                        Divider()
+                        Text("The share controls this mode. Reconnect to pick up later changes.")
+                            .font(.caption)
+                            .foregroundStyle(.secondary)
+                            .frame(maxWidth: .infinity, alignment: .leading)
+                            .padding(.horizontal, 12)
+                            .padding(.vertical, 10)
+                    }
+
+                    if mountLibrary.manager.extensionEnabled == false {
+                        mountFormSection("File System Extension") {
+                            VStack(alignment: .leading, spacing: 10) {
+                                Label(
+                                    mountLibrary.manager.extensionStatusDetail
+                                        ?? "Enable GhostFileFS before mounting.",
+                                    systemImage: "exclamationmark.triangle.fill"
+                                )
+                                .foregroundStyle(.orange)
+                                if mountLibrary.manager.extensionRepairAvailable {
+                                    Button(mountLibrary.manager.isWorking ? "Repairing…" : "Install / Repair Extension…") {
+                                        Task { await mountLibrary.manager.repairExtensionRegistration() }
+                                    }
+                                    .disabled(
+                                        mountLibrary.manager.isWorking
+                                            || !mountLibrary.manager.mountedShares.isEmpty
+                                    )
+                                }
+                                Button("Open File System Extensions…") {
+                                    mountLibrary.manager.openExtensionSettings()
+                                }
+                            }
+                            .frame(maxWidth: .infinity, alignment: .leading)
+                            .padding(12)
+                        }
+                    }
+
+                    if let errorMessage {
+                        HStack(alignment: .top, spacing: 10) {
+                            Text(errorMessage)
+                                .foregroundStyle(.red)
+                                .frame(maxWidth: .infinity, alignment: .leading)
+                                .padding(12)
+                                .background(mountFormCardBackground)
+                            Color.clear.frame(width: 18, height: 18)
+                        }
+                    }
+                }
+                .padding(.horizontal, 20)
+                .padding(.vertical, 18)
+            }
+
+            Divider()
+            HStack {
+                Button("Cancel") { dismiss() }
+                Spacer()
+                Button("Save") { save(mountAfterSaving: false) }
+                    .disabled(!canSave || isSavingAndMounting)
+                Button("Save & Mount") { save(mountAfterSaving: true) }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(!canSave || isSavingAndMounting)
+            }
+            .padding(18)
+        }
+        .frame(width: 620, height: selectedDiscoveredShare == nil ? 590 : 700)
+    }
+
+    private var selectedDiscoveredShare: DiscoveredGhostFileShare? {
+        nearbyShares.first { $0.id == selectedShareID }
+    }
+
+    private var hasAccessKey: Bool {
+        !accessKey.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    }
+
+    private var mountFormCardBackground: some View {
+        RoundedRectangle(cornerRadius: 10, style: .continuous)
+            .fill(Color.primary.opacity(0.055))
+    }
+
+    private func mountFormRow(
+        _ label: String,
+        @ViewBuilder content: () -> Content
+    ) -> some View {
+        HStack(spacing: 12) {
+            Text(label)
+                .frame(width: 140, alignment: .leading)
+            content()
+                .frame(maxWidth: .infinity, alignment: .trailing)
+        }
+        .frame(minHeight: 44)
+        .padding(.horizontal, 12)
+    }
+
+    private func mountFormSection(
+        _ title: String,
+        statusIsSatisfied: Bool? = nil,
+        missingLabel: String = "",
+        missingSymbol: String = "xmark.circle.fill",
+        missingColor: Color = .red,
+        @ViewBuilder content: () -> Content
+    ) -> some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text(title)
+                .font(.headline)
+
+            HStack(alignment: .bottom, spacing: 10) {
+                VStack(alignment: .leading, spacing: 0) {
+                    content()
+                }
+                .frame(maxWidth: .infinity, alignment: .leading)
+                .background(mountFormCardBackground)
+
+                Group {
+                    if let statusIsSatisfied {
+                        requirementStatus(
+                            isSatisfied: statusIsSatisfied,
+                            missingLabel: missingLabel,
+                            missingSymbol: missingSymbol,
+                            missingColor: missingColor
+                        )
+                    } else {
+                        Color.clear
+                            .frame(width: 18, height: 18)
+                    }
+                }
+                .frame(width: 18, height: 44, alignment: .center)
+            }
+        }
+    }
+
+    private func requirementStatus(
+        isSatisfied: Bool,
+        missingLabel: String,
+        missingSymbol: String,
+        missingColor: Color
+    ) -> some View {
+        Image(systemName: isSatisfied ? "checkmark.circle.fill" : missingSymbol)
+        .font(.caption.weight(.semibold))
+        .foregroundStyle(isSatisfied ? Color.green : missingColor)
+        .frame(width: 18, height: 18)
+        .contentShape(Rectangle())
+        .help(isSatisfied ? "Complete" : missingLabel)
+        .accessibilityLabel(isSatisfied ? "Complete" : missingLabel)
+    }
+
+    private var canSave: Bool {
+        !name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            && !sourceURL.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            && hasAccessKey
+            && (selectedDiscoveredShare == nil || confirmedDiscoveredIdentity)
+    }
+
+    private func save(mountAfterSaving: Bool) {
+        do {
+            let mount = try mountLibrary.addMount(
+                name: name,
+                sourceURL: sourceURL,
+                accessKey: accessKey,
+                mountPoint: mountPoint,
+                readOnly: readOnly
+            )
+            if mountAfterSaving {
+                isSavingAndMounting = true
+                Task {
+                    await mountLibrary.mount(mount.id)
+                    isSavingAndMounting = false
+                    dismiss()
+                }
+            } else {
+                dismiss()
+            }
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    private func chooseMountPoint() {
+        let panel = NSOpenPanel()
+        panel.title = "Choose an empty folder to use as the mount point"
+        panel.prompt = "Choose Mount Point"
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.canCreateDirectories = true
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = mountPoint
+        guard panel.runModal() == .OK else { return }
+        mountPoint = panel.url?.standardizedFileURL
+    }
+}
+
+private struct GhostFileMountDetailEditor: View {
+    @EnvironmentObject private var mountLibrary: GhostFileMountLibrary
+    let mount: SavedGhostFileMount
+    @State private var name: String
+    @State private var sourceURL: String
+    @State private var accessKey = ""
+    @State private var mountPoint: URL?
+    @State private var editorError: String?
+    @State private var didLoad = false
+
+    init(mount: SavedGhostFileMount) {
+        self.mount = mount
+        _name = State(initialValue: mount.name)
+        _sourceURL = State(initialValue: mount.sourceURL)
+    }
+
+    var body: some View {
+        let status = mountLibrary.status(for: mount.id)
+        VStack(spacing: 0) {
+            HStack(spacing: 12) {
+                Image(systemName: "externaldrive.connected.to.line.below")
+                    .font(.title2)
+                    .foregroundStyle(.tint)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text(name).font(.title2.weight(.semibold))
+                    Text(statusLabel(status))
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Spacer()
+                Button("Save Changes") { save() }
+                    .disabled(isActive(status))
+                Button(isActive(status) ? "Unmount" : "Mount") {
+                    Task {
+                        if isActive(status) {
+                            await mountLibrary.unmount(mount.id)
+                        } else if save() {
+                            await mountLibrary.mount(mount.id)
+                        }
+                    }
+                }
+                .buttonStyle(.borderedProminent)
+                .tint(isActive(status) ? .red : .green)
+                .controlSize(.large)
+                .disabled(status == .mounting)
+            }
+            .padding(18)
+            Divider()
+
+            Form {
+                Section("Connection") {
+                    TextField("Volume name", text: $name)
+                        .onSubmit { _ = save() }
+                    TextField("Share URL", text: $sourceURL)
+                        .onSubmit { _ = save() }
+                    SecureField("Access key", text: $accessKey)
+                        .onSubmit { _ = save() }
+                    Text("Connection settings can be edited while unmounted.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                Section("Mount Point") {
+                    LabeledContent("Location") {
+                        HStack {
+                            Text(mountPoint?.path ?? "Automatic — ~/GhostFiles")
+                                .foregroundStyle(.secondary)
+                                .lineLimit(1)
+                                .truncationMode(.middle)
+                            if !isActive(status) {
+                                if mountPoint != nil {
+                                    Button("Use Automatic") { mountPoint = nil }
+                                }
+                                Button("Choose…") { chooseMountPoint() }
+                            }
+                            if status.isMounted {
+                                Button("Reveal") { mountLibrary.reveal(mount.id) }
+                            }
+                        }
+                    }
+                }
+                Section("Access") {
+                    LabeledContent("Mode", value: "Read only")
+                }
+                if case .failed(let message) = status {
+                    Section("Error") {
+                        Text(message).foregroundStyle(.red)
+                    }
+                }
+                if case .error(_, let message) = status {
+                    Section("Error") {
+                        Text(message).foregroundStyle(.red)
+                    }
+                }
+                if let editorError {
+                    Section {
+                        Text(editorError).foregroundStyle(.red)
+                    }
+                }
+            }
+            .formStyle(.grouped)
+            .disabled(isActive(status))
+        }
+        .task { loadIfNeeded() }
+    }
+
+    private var canSave: Bool {
+        !name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            && !sourceURL.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            && !accessKey.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    }
+
+    @discardableResult
+    private func save() -> Bool {
+        do {
+            try mountLibrary.updateMount(
+                mount.id,
+                name: name,
+                sourceURL: sourceURL,
+                accessKey: accessKey,
+                mountPoint: mountPoint
+            )
+            editorError = nil
+            return true
+        } catch {
+            editorError = error.localizedDescription
+            return false
+        }
+    }
+
+    private func loadIfNeeded() {
+        guard !didLoad else { return }
+        didLoad = true
+        mountPoint = mountLibrary.requestedMountPoint(for: mount.id)
+        do {
+            accessKey = try mountLibrary.accessKey(for: mount.id)
+        } catch {
+            editorError = error.localizedDescription
+        }
+    }
+
+    private func chooseMountPoint() {
+        let panel = NSOpenPanel()
+        panel.title = "Choose an empty folder to use as the mount point"
+        panel.prompt = "Choose Mount Point"
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.canCreateDirectories = true
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = mountPoint
+        guard panel.runModal() == .OK else { return }
+        mountPoint = panel.url?.standardizedFileURL
+    }
+
+    private func isActive(_ status: GhostFileSavedMountStatus) -> Bool {
+        status == .mounting || status.isMounted
+    }
+
+    private func statusLabel(_ status: GhostFileSavedMountStatus) -> String {
+        switch status {
+        case .stopped: "Stopped"
+        case .mounting: "Mounting"
+        case .mounted(let url): "Mounted at \(url.path)"
+        case .online(let url): "Online — \(url.path)"
+        case .degraded(let url): "Degraded — \(url.path)"
+        case .error(let url, _): "Error — \(url.path)"
+        case .offline(let url): "Offline — \(url.path)"
+        case .failed: "Error"
+        }
+    }
+}
diff --git a/macOS/GhostFile/GhostFileDiscovery.swift b/macOS/GhostFile/GhostFileDiscovery.swift
new file mode 100644
index 0000000..2b06218
--- /dev/null
+++ b/macOS/GhostFile/GhostFileDiscovery.swift
@@ -0,0 +1,216 @@
+import Foundation
+import GhostFileKit
+
+struct DiscoveredGhostFileShare: Identifiable, Hashable, Codable {
+    let id: UUID
+    let name: String
+    let host: String
+    let port: Int
+    let readOnly: Bool
+    let transport: String
+    let publicKeyPin: String
+
+    var serviceType: String {
+        GhostFileProtocol.bonjourType.trimmingCharacters(in: CharacterSet(charactersIn: "."))
+    }
+
+    var url: URL? {
+        var components = URLComponents()
+        components.scheme = GhostFileProtocol.urlScheme
+        components.host = host
+        components.port = port
+        components.path = GhostFileProtocol.shareBasePath(id: id)
+        components.queryItems = [URLQueryItem(
+            name: GhostFileProtocol.publicKeyPinQueryName,
+            value: publicKeyPin
+        )]
+        return components.url
+    }
+}
+
+enum GhostFileDiscoveryVisibility {
+    static func visibleShares(
+        from discoveredShares: [DiscoveredGhostFileShare],
+        localShareIDs: Set,
+        discoverSelfShares: Bool
+    ) -> [DiscoveredGhostFileShare] {
+        guard !discoverSelfShares else { return discoveredShares }
+        return discoveredShares.filter { !localShareIDs.contains($0.id) }
+    }
+}
+
+@MainActor
+final class GhostFileDiscovery: NSObject, ObservableObject {
+    @Published private(set) var shares: [DiscoveredGhostFileShare] = []
+    @Published private(set) var isSearching = false
+    private let browser = NetServiceBrowser()
+    private var services: [ObjectIdentifier: NetService] = [:]
+    private var shareIDsByService: [ObjectIdentifier: UUID] = [:]
+    private var stoppingServices: Set = []
+    private var lastSeenByService: [ObjectIdentifier: Date] = [:]
+    private var ttlByService: [ObjectIdentifier: TimeInterval] = [:]
+    private var expiryTask: Task?
+
+    override init() {
+        super.init()
+        browser.delegate = self
+        browser.includesPeerToPeer = true
+    }
+
+    func start() {
+        guard !isSearching else { return }
+        isSearching = true
+        browser.searchForServices(
+            ofType: GhostFileProtocol.bonjourType,
+            inDomain: GhostFileProtocol.bonjourDomain
+        )
+        expiryTask = Task { [weak self] in
+            while !Task.isCancelled {
+                try? await Task.sleep(for: GhostFileBonjourLease.sweepInterval)
+                guard !Task.isCancelled else { return }
+                guard let self else { return }
+                self.expireStaleServices()
+            }
+        }
+    }
+
+    func stop() {
+        expiryTask?.cancel()
+        expiryTask = nil
+        browser.stop()
+        for service in services.values {
+            service.stopMonitoring()
+            service.stop()
+        }
+        services.removeAll()
+        shareIDsByService.removeAll()
+        stoppingServices.removeAll()
+        lastSeenByService.removeAll()
+        ttlByService.removeAll()
+        shares.removeAll()
+        isSearching = false
+    }
+
+    private func resolved(_ service: NetService, txtData suppliedTXTData: Data? = nil) {
+        guard isSearching,
+              let hostName = service.hostName,
+              let txtData = suppliedTXTData ?? service.txtRecordData() else { return }
+        let txt = NetService.dictionary(fromTXTRecord: txtData)
+        guard let idData = txt["id"],
+              let idString = String(data: idData, encoding: .utf8),
+              let id = UUID(uuidString: idString) else { return }
+
+        let key = ObjectIdentifier(service)
+        let state = txt["state"].flatMap { String(data: $0, encoding: .utf8) } ?? "ready"
+        if state == "stopping" {
+            if stoppingServices.insert(key).inserted {
+                shareIDsByService[key] = id
+                removeShare(forService: key)
+            }
+            return
+        }
+        stoppingServices.remove(key)
+        shareIDsByService[key] = id
+
+        let mode = txt["mode"].flatMap { String(data: $0, encoding: .utf8) } ?? "ro"
+        let transport = txt["transport"].flatMap { String(data: $0, encoding: .utf8) } ?? GhostFileProtocol.transport
+        let alpn = txt["alpn"].flatMap { String(data: $0, encoding: .utf8) } ?? GhostFileProtocol.alpn
+        guard transport == GhostFileProtocol.transport, alpn == GhostFileProtocol.alpn else { return }
+        guard let pinData = txt["pk"],
+              let publicKeyPin = String(data: pinData, encoding: .utf8),
+              GhostFileProtocol.validPublicKeyPin(publicKeyPin) else { return }
+        lastSeenByService[key] = Date()
+        ttlByService[key] = GhostFileBonjourLease.ttl(from: txt)
+        let host = hostName.hasSuffix(".") ? String(hostName.dropLast()) : hostName
+        let discovered = DiscoveredGhostFileShare(
+            id: id,
+            name: service.name,
+            host: host,
+            port: service.port,
+            readOnly: mode == "ro",
+            transport: transport,
+            publicKeyPin: publicKeyPin
+        )
+        shares.removeAll { $0.id == id }
+        shares.append(discovered)
+        shares.sort { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
+    }
+
+    private func removeShare(forService key: ObjectIdentifier) {
+        guard let shareID = shareIDsByService.removeValue(forKey: key) else { return }
+        lastSeenByService.removeValue(forKey: key)
+        ttlByService.removeValue(forKey: key)
+        guard !shareIDsByService.values.contains(shareID) else { return }
+        shares.removeAll { $0.id == shareID }
+    }
+
+    private func expireStaleServices(now: Date = Date()) {
+        let expired = lastSeenByService.compactMap { key, lastSeen -> ObjectIdentifier? in
+            let ttl = ttlByService[key] ?? GhostFileBonjourLease.legacyTTL
+            return GhostFileBonjourLease.isExpired(lastSeen: lastSeen, ttl: ttl, now: now) ? key : nil
+        }
+        for key in expired {
+            removeShare(forService: key)
+        }
+    }
+}
+
+extension GhostFileDiscovery: NetServiceBrowserDelegate, NetServiceDelegate {
+    nonisolated func netServiceBrowser(
+        _ browser: NetServiceBrowser,
+        didFind service: NetService,
+        moreComing: Bool
+    ) {
+        Task { @MainActor in
+            guard isSearching else { return }
+            let key = ObjectIdentifier(service)
+            services[key] = service
+            service.delegate = self
+            service.includesPeerToPeer = true
+            service.resolve(withTimeout: 5)
+        }
+    }
+
+    nonisolated func netServiceBrowser(
+        _ browser: NetServiceBrowser,
+        didRemove service: NetService,
+        moreComing: Bool
+    ) {
+        Task { @MainActor in
+            guard isSearching else { return }
+            let key = ObjectIdentifier(service)
+            service.stopMonitoring()
+            services.removeValue(forKey: key)
+            stoppingServices.remove(key)
+            lastSeenByService.removeValue(forKey: key)
+            ttlByService.removeValue(forKey: key)
+            removeShare(forService: key)
+        }
+    }
+
+    nonisolated func netServiceDidResolveAddress(_ sender: NetService) {
+        Task { @MainActor in
+            guard isSearching else { return }
+            resolved(sender)
+            sender.startMonitoring()
+        }
+    }
+
+    nonisolated func netService(_ sender: NetService, didUpdateTXTRecord data: Data) {
+        Task { @MainActor in
+            guard isSearching else { return }
+            resolved(sender, txtData: data)
+        }
+    }
+
+    nonisolated func netServiceBrowserDidStopSearch(_ browser: NetServiceBrowser) {
+        Task { @MainActor in isSearching = false }
+    }
+
+    nonisolated func netServiceBrowser(
+        _ browser: NetServiceBrowser,
+        didNotSearch errorDict: [String: NSNumber]
+    ) {
+        Task { @MainActor in isSearching = false }
+    }
+}
diff --git a/macOS/GhostFile/GhostFileMountManager.swift b/macOS/GhostFile/GhostFileMountManager.swift
new file mode 100644
index 0000000..46154c8
--- /dev/null
+++ b/macOS/GhostFile/GhostFileMountManager.swift
@@ -0,0 +1,984 @@
+import AppKit
+import Combine
+import Darwin
+import Foundation
+import FSKit
+import GhostFileKit
+import OSLog
+
+private let ghostFileMountLogger = Logger(
+    subsystem: "org.ghostvm.ghostfile",
+    category: "Mount"
+)
+
+struct MountedGhostFileShare: Identifiable, Equatable {
+    let id: UUID
+    let definitionID: UUID
+    let shareID: UUID
+    let name: String
+    let sourceURL: URL
+    let mountPoint: URL
+    let removesMountPointOnUnmount: Bool
+}
+
+struct SavedGhostFileMount: Identifiable, Codable, Equatable {
+    let id: UUID
+    let shareID: UUID
+    var name: String
+    var sourceURL: String
+    var mountPointBookmark: Data?
+    var readOnly: Bool
+}
+
+enum GhostFileSavedMountStatus: Equatable {
+    case stopped
+    case mounting
+    case mounted(URL)
+    case online(URL)
+    case degraded(URL)
+    case error(URL, String)
+    case offline(URL)
+    case failed(String)
+
+    var isMounted: Bool {
+        switch self {
+        case .mounted, .online, .degraded, .error, .offline: true
+        case .stopped, .mounting, .failed: false
+        }
+    }
+}
+
+enum GhostFileExtensionHealth: Equatable {
+    case checking
+    case ready
+    case needsApplicationInstall
+    case missingEmbeddedExtension
+    case notRegistered
+    case duplicateRegistrations(Int)
+    case disabled
+    case scanFailed(String)
+
+    var requiresAttention: Bool {
+        switch self {
+        case .checking, .ready:
+            false
+        case .needsApplicationInstall, .missingEmbeddedExtension, .notRegistered,
+             .duplicateRegistrations, .disabled, .scanFailed:
+            true
+        }
+    }
+}
+
+protocol GhostFileMountConfigurationStorage {
+    func load() throws -> [SavedGhostFileMount]
+    func save(_ mounts: [SavedGhostFileMount]) throws
+}
+
+struct GhostFileMountJSONStorage: GhostFileMountConfigurationStorage {
+    let fileURL: URL
+
+    static var applicationStorage: Self {
+        let root = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("GhostFile", isDirectory: true)
+        return Self(fileURL: root.appendingPathComponent("mounts.json"))
+    }
+
+    func load() throws -> [SavedGhostFileMount] {
+        guard FileManager.default.fileExists(atPath: fileURL.path) else { return [] }
+        return try JSONDecoder().decode([SavedGhostFileMount].self, from: Data(contentsOf: fileURL))
+    }
+
+    func save(_ mounts: [SavedGhostFileMount]) throws {
+        try FileManager.default.createDirectory(
+            at: fileURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        try JSONEncoder().encode(mounts).write(to: fileURL, options: .atomic)
+    }
+}
+
+@MainActor
+final class GhostFileMountManager: ObservableObject {
+    nonisolated private static let extensionBundleIdentifier = "org.ghostvm.ghostfile.fs"
+
+    @Published private(set) var mountedShares: [MountedGhostFileShare] = []
+    @Published private(set) var extensionEnabled: Bool?
+    @Published private(set) var extensionHealth: GhostFileExtensionHealth = .checking
+    @Published private(set) var extensionRepairAvailable = false
+    @Published private(set) var extensionStatusDetail: String?
+    @Published var errorMessage: String?
+    @Published private(set) var isWorking = false
+
+    func refreshExtensionStatus() async {
+        extensionEnabled = nil
+        extensionHealth = .checking
+        do {
+            let appURL = Bundle.main.bundleURL.resolvingSymlinksInPath().standardizedFileURL
+            let extensionURL = expectedExtensionURL.resolvingSymlinksInPath().standardizedFileURL
+            guard FileManager.default.fileExists(atPath: extensionURL.path) else {
+                extensionEnabled = false
+                extensionRepairAvailable = false
+                extensionHealth = .missingEmbeddedExtension
+                extensionStatusDetail = "This copy of GhostFile does not contain the GhostFileFS module. Reinstall GhostFile from the disk image."
+                return
+            }
+
+            let modules = try await FSClient.shared.installedExtensions
+            let identities = modules.filter {
+                $0.bundleIdentifier == Self.extensionBundleIdentifier
+            }
+            let expectedURL = expectedExtensionURL.resolvingSymlinksInPath().standardizedFileURL
+            let snapshot = await Task.detached(priority: .utility) {
+                Self.registrationSnapshot()
+            }.value
+            let identity = identities.first {
+                $0.url.resolvingSymlinksInPath().standardizedFileURL == expectedURL
+            } ?? identities.first
+            let hasStaleIdentity = identities.contains {
+                $0.url.resolvingSymlinksInPath().standardizedFileURL != expectedURL
+            } || snapshot.urls.contains {
+                $0.resolvingSymlinksInPath().standardizedFileURL != expectedURL
+            }
+
+            guard let identity else {
+                extensionEnabled = false
+                if appURL.path.hasPrefix("/Applications/") {
+                    extensionHealth = .notRegistered
+                    extensionRepairAvailable = true
+                    extensionStatusDetail = "macOS has not registered the embedded GhostFileFS module."
+                } else {
+                    extensionHealth = .needsApplicationInstall
+                    extensionRepairAvailable = false
+                    extensionStatusDetail = "Move GhostFile to Applications before installing its file system extension."
+                }
+                return
+            }
+
+            let selectedCanonicalIdentity = identity.url.resolvingSymlinksInPath().standardizedFileURL == expectedURL
+            // FSClient can temporarily report a cached enabled value after the
+            // FSKit preference has been disabled, so require the on-disk FSKit
+            // state too. The Settings pane doesn't necessarily set PlugInKit's
+            // optional "+" election, so that marker is diagnostic only.
+            extensionEnabled = identity.isEnabled
+                && snapshot.enabledByFSKit
+                && selectedCanonicalIdentity
+                && !hasStaleIdentity
+            extensionRepairAvailable = hasStaleIdentity
+                || !snapshot.enabledByFSKit
+                || (snapshot.enabledByFSKit && !identity.isEnabled)
+
+            if !appURL.path.hasPrefix("/Applications/") {
+                extensionHealth = .needsApplicationInstall
+                extensionRepairAvailable = false
+                extensionStatusDetail = "Move GhostFile to Applications before installing its file system extension."
+            } else if hasStaleIdentity {
+                let staleCount = Set(
+                    (identities.map(\.url) + snapshot.urls)
+                        .map { $0.resolvingSymlinksInPath().standardizedFileURL }
+                        .filter { $0 != expectedURL }
+                ).count
+                extensionHealth = .duplicateRegistrations(staleCount)
+                extensionStatusDetail = "Found \(staleCount) stray GhostFileFS registration\(staleCount == 1 ? "" : "s"). macOS may launch the wrong extension; repair registration before mounting."
+            } else if !snapshot.enabledByFSKit {
+                extensionHealth = .disabled
+                extensionStatusDetail = "The Extensions toggle and FSKit's enabled-module list are out of sync."
+            } else if snapshot.enabledByFSKit && !identity.isEnabled {
+                extensionHealth = .disabled
+                extensionStatusDetail = "FSKit cached a stale disabled state for GhostFileFS."
+            } else {
+                extensionHealth = .ready
+                extensionStatusDetail = nil
+            }
+        } catch {
+            extensionEnabled = false
+            extensionRepairAvailable = false
+            extensionHealth = .scanFailed(error.localizedDescription)
+            extensionStatusDetail = "GhostFile could not inspect the file system extension."
+            errorMessage = "Unable to inspect FSKit extensions: \(error.localizedDescription)"
+        }
+    }
+
+    func repairExtensionRegistration() async {
+        let appURL = Bundle.main.bundleURL.resolvingSymlinksInPath().standardizedFileURL
+        guard appURL.path.hasPrefix("/Applications/") else {
+            extensionHealth = .needsApplicationInstall
+            errorMessage = "Move GhostFile to /Applications before repairing its FSKit registration."
+            return
+        }
+        guard mountedShares.isEmpty else {
+            extensionStatusDetail = "Unmount all GhostFile volumes before repairing the file system extension."
+            return
+        }
+
+        isWorking = true
+        extensionEnabled = nil
+        defer { isWorking = false }
+
+        do {
+            let extensionURL = expectedExtensionURL.resolvingSymlinksInPath().standardizedFileURL
+            try await Task.detached(priority: .userInitiated) {
+                try Self.run(executable: "/usr/bin/codesign", arguments: ["--verify", "--deep", "--strict", appURL.path])
+
+                let snapshot = Self.registrationSnapshot()
+                for staleURL in snapshot.urls where staleURL.resolvingSymlinksInPath().standardizedFileURL != extensionURL {
+                    try? Self.run(executable: "/usr/bin/pluginkit", arguments: ["-r", staleURL.path])
+                    if let staleApp = Self.containingApp(for: staleURL), staleApp != appURL {
+                        try? Self.run(executable: Self.launchServicesRegisterPath, arguments: ["-u", staleApp.path])
+                    }
+                }
+
+                // Recreate the canonical identity too. A stuck Settings switch
+                // can be attached to a stale UUID even when its URL is correct.
+                try? Self.run(executable: "/usr/bin/pluginkit", arguments: ["-r", extensionURL.path])
+                try? Self.run(executable: Self.launchServicesRegisterPath, arguments: ["-u", appURL.path])
+                try Self.run(executable: Self.launchServicesRegisterPath, arguments: ["-f", "-R", "-trusted", appURL.path])
+
+                // FSKit caches module identities in a per-user agent. Restart it
+                // only after LaunchServices has created the replacement UUID.
+                try? Self.run(executable: "/usr/bin/killall", arguments: ["fskit_agent"])
+            }.value
+
+            try? await Task.sleep(for: .seconds(1))
+            await refreshExtensionStatus()
+            if extensionEnabled == true {
+                errorMessage = nil
+            } else {
+                errorMessage = nil
+                extensionStatusDetail = "Registration repaired. Turn on GhostFileFS in System Settings."
+                openExtensionSettings()
+            }
+        } catch {
+            extensionEnabled = false
+            errorMessage = "Unable to repair FSKit registration: \(error.localizedDescription)"
+        }
+    }
+
+    @discardableResult
+    func mount(
+        definitionID: UUID,
+        url: URL,
+        accessKey: String,
+        volumeName: String,
+        requestedMountPoint: URL?
+    ) async -> MountedGhostFileShare? {
+        guard !accessKey.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+            errorMessage = "Enter the share's access key."
+            return nil
+        }
+        guard url.scheme == GhostFileProtocol.urlScheme else {
+            errorMessage = "GhostFile share URLs must use ghostfile://."
+            return nil
+        }
+        guard GhostFileProtocol.peerPin(from: url) != nil else {
+            errorMessage = "The share URL is missing a valid TLS identity pin. Copy a new link from the sharing Mac."
+            return nil
+        }
+        // Do not trust the status captured when the Mount view first appeared.
+        // LaunchServices can discover an Xcode/Downloads copy while the app is
+        // already open, and FSKit may otherwise launch that stale registration.
+        await refreshExtensionStatus()
+        guard extensionEnabled == true else {
+            errorMessage = extensionStatusDetail
+                ?? "Enable the GhostFile file system extension in System Settings first."
+            return nil
+        }
+
+        isWorking = true
+        defer { isWorking = false }
+        do {
+            var resourceComponents = URLComponents(url: url, resolvingAgainstBaseURL: false)
+            var queryItems = resourceComponents?.queryItems ?? []
+            queryItems.removeAll {
+                $0.name == "access_key" || $0.name == GhostFileProtocol.mountInstanceQueryName
+            }
+            let mountInstance = UUID()
+            queryItems.append(URLQueryItem(name: "access_key", value: accessKey))
+            queryItems.append(URLQueryItem(
+                name: GhostFileProtocol.mountInstanceQueryName,
+                value: mountInstance.uuidString.lowercased()
+            ))
+            resourceComponents?.queryItems = queryItems
+            guard let resourceURL = resourceComponents?.url else {
+                throw MountFailure("Invalid share URL")
+            }
+            guard let shareID = shareID(from: resourceURL) else {
+                throw MountFailure("Invalid GhostFile share URL")
+            }
+
+            let mountPoint: URL
+            let removesMountPointOnUnmount: Bool
+            let isAccessingMountPoint = requestedMountPoint?.startAccessingSecurityScopedResource() ?? false
+            defer {
+                if isAccessingMountPoint {
+                    requestedMountPoint?.stopAccessingSecurityScopedResource()
+                }
+            }
+            if let requestedMountPoint {
+                mountPoint = requestedMountPoint.standardizedFileURL
+                try validateUserSelectedMountPoint(mountPoint)
+                removesMountPointOnUnmount = false
+            } else {
+                let mountRoot = FileManager.default.homeDirectoryForCurrentUser
+                    .appendingPathComponent("GhostFiles", isDirectory: true)
+                try FileManager.default.createDirectory(at: mountRoot, withIntermediateDirectories: true)
+                let safeName = sanitizedVolumeName(volumeName)
+                mountPoint = uniqueMountPoint(root: mountRoot, name: safeName)
+                try FileManager.default.createDirectory(at: mountPoint, withIntermediateDirectories: false)
+                removesMountPointOnUnmount = true
+            }
+
+            do {
+                ghostFileMountLogger.info(
+                    "Mount invocation starting share=\(shareID.uuidString.lowercased(), privacy: .public) instance=\(mountInstance.uuidString.lowercased(), privacy: .public) target=\(mountPoint.path, privacy: .private(mask: .hash))"
+                )
+                try await Task.detached(priority: .userInitiated) {
+                    try Self.run(
+                        executable: "/sbin/mount",
+                        arguments: [
+                            "-F", "-t", "ghostfile",
+                            // GhostFileFS negotiates read-only versus writable
+                            // from the share's live capabilities. Forcing
+                            // rdonly here made every volume immutable even
+                            // when the server explicitly allowed writes.
+                            "-o", "nobrowse,nodev,nosuid",
+                            resourceURL.absoluteString,
+                            mountPoint.path,
+                        ],
+                        timeout: 25
+                    )
+                }.value
+                ghostFileMountLogger.info(
+                    "Mount invocation completed share=\(shareID.uuidString.lowercased(), privacy: .public) instance=\(mountInstance.uuidString.lowercased(), privacy: .public)"
+                )
+            } catch {
+                ghostFileMountLogger.error(
+                    "Mount invocation failed share=\(shareID.uuidString.lowercased(), privacy: .public) instance=\(mountInstance.uuidString.lowercased(), privacy: .public) error=\(String(describing: error), privacy: .public)"
+                )
+                try? FileManager.default.removeItem(
+                    at: GhostFileMountHealthStorage.readerURL(for: mountInstance)
+                )
+                if removesMountPointOnUnmount {
+                    try? FileManager.default.removeItem(at: mountPoint)
+                }
+                throw error
+            }
+
+            let mountedShare = MountedGhostFileShare(
+                id: mountInstance,
+                definitionID: definitionID,
+                shareID: shareID,
+                name: volumeName,
+                sourceURL: url,
+                mountPoint: mountPoint,
+                removesMountPointOnUnmount: removesMountPointOnUnmount
+            )
+            mountedShares.append(mountedShare)
+            errorMessage = nil
+            return mountedShare
+        } catch {
+            errorMessage = error.localizedDescription
+            return nil
+        }
+    }
+
+    func unmount(_ mountedShare: MountedGhostFileShare, force: Bool = false) async {
+        isWorking = true
+        defer { isWorking = false }
+        do {
+            do {
+                try await Self.runUnmount(mountedShare.mountPoint, force: force)
+            } catch where !force && Self.isDeviceBusy(error) {
+                // The user explicitly requested an unmount and GhostFile
+                // volumes are network mounts. A forced retry is the
+                // appropriate recovery for a wedged FSKit vnode reference.
+                try await Self.runUnmount(mountedShare.mountPoint, force: true)
+            }
+            if mountedShare.removesMountPointOnUnmount {
+                try? FileManager.default.removeItem(at: mountedShare.mountPoint)
+            }
+            mountedShares.removeAll { $0.id == mountedShare.id }
+            errorMessage = nil
+        } catch {
+            errorMessage = error.localizedDescription
+        }
+    }
+
+    func reveal(_ mountedShare: MountedGhostFileShare) {
+        NSWorkspace.shared.activateFileViewerSelecting([mountedShare.mountPoint])
+    }
+
+    func reconcileMountedShares() -> [MountedGhostFileShare] {
+        let missing = mountedShares.filter { !Self.isMounted(at: $0.mountPoint) }
+        guard !missing.isEmpty else { return [] }
+        let missingIDs = Set(missing.map(\.id))
+        mountedShares.removeAll { missingIDs.contains($0.id) }
+        for mountedShare in missing where mountedShare.removesMountPointOnUnmount {
+            try? FileManager.default.removeItem(at: mountedShare.mountPoint)
+        }
+        return missing
+    }
+
+    private static func runUnmount(_ mountPoint: URL, force: Bool) async throws {
+        try await Task.detached(priority: .userInitiated) {
+            let arguments = force ? ["-f", mountPoint.path] : [mountPoint.path]
+            try Self.run(executable: "/sbin/umount", arguments: arguments, timeout: 10)
+        }.value
+    }
+
+    private nonisolated static func isMounted(at mountPoint: URL) -> Bool {
+        var fileSystems: UnsafeMutablePointer?
+        let count = getmntinfo(&fileSystems, MNT_NOWAIT)
+        guard count > 0, let fileSystems else { return false }
+        let expectedPath = mountPoint.standardizedFileURL.path
+
+        for index in 0.. String in
+                guard let address = bytes.baseAddress else { return "" }
+                return String(cString: address.assumingMemoryBound(to: CChar.self))
+            }
+            if URL(fileURLWithPath: mountedAt).standardizedFileURL.path == expectedPath {
+                return true
+            }
+        }
+        return false
+    }
+
+    private nonisolated static func isDeviceBusy(_ error: Error) -> Bool {
+        let detail = error.localizedDescription.lowercased()
+        return detail.contains("device busy") || detail.contains("resource busy")
+    }
+
+    func openExtensionSettings() {
+        extensionEnabled = nil
+
+        // Newer FSKit runtimes provide this official API. Keep the runtime
+        // check so builds made with the 26.4 SDK use it as soon as it exists.
+        let client = FSClient.shared as NSObject
+        let selector = NSSelectorFromString("openFileSystemExtensionsSettings")
+        if client.responds(to: selector) {
+            typealias OpenSettings = @convention(c) (AnyObject, Selector) -> Bool
+            let implementation = client.method(for: selector)
+            if unsafeBitCast(implementation, to: OpenSettings.self)(client, selector) {
+                return
+            }
+        }
+
+        // Older macOS 26 releases support the Extensions preferences route
+        // with an extension-point filter, which avoids the generic settings
+        // page and opens the FSKit Modules category directly.
+        guard let url = URL(string: "x-apple.systempreferences:com.apple.ExtensionsPreferences?extensionPointIdentifier=com.apple.fskit.fsmodule") else {
+            return
+        }
+        NSWorkspace.shared.open(url)
+    }
+
+    private var expectedExtensionURL: URL {
+        Bundle.main.bundleURL
+            .appendingPathComponent("Contents/Extensions/GhostFileFS.appex", isDirectory: true)
+    }
+
+    private struct RegistrationSnapshot: Sendable {
+        let urls: [URL]
+        let enabledByFSKit: Bool
+    }
+
+    private nonisolated static let launchServicesRegisterPath =
+        "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister"
+
+    private nonisolated static var enabledModulesURL: URL {
+        FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/Group Containers/group.com.apple.fskit.settings/enabledModules.plist")
+    }
+
+    private nonisolated static func registrationSnapshot() -> RegistrationSnapshot {
+        let output = (try? runAndCapture(
+            executable: "/usr/bin/pluginkit",
+            arguments: ["-v", "-m", "-A", "-D", "-p", "com.apple.fskit.fsmodule", "-i", extensionBundleIdentifier]
+        )) ?? ""
+        let matchingLines = output.split(separator: "\n").map(String.init).filter {
+            $0.contains(extensionBundleIdentifier)
+        }
+        let urls = matchingLines.compactMap { line -> URL? in
+            guard let path = line.split(separator: "\t", omittingEmptySubsequences: true).last,
+                  path.hasPrefix("/") else { return nil }
+            return URL(fileURLWithPath: String(path), isDirectory: true)
+        }
+        let enabledModules = (try? Data(contentsOf: enabledModulesURL)).flatMap {
+            try? PropertyListSerialization.propertyList(from: $0, format: nil) as? [String]
+        } ?? []
+        return RegistrationSnapshot(
+            urls: urls,
+            enabledByFSKit: enabledModules.contains(extensionBundleIdentifier)
+        )
+    }
+
+    private nonisolated static func containingApp(for url: URL) -> URL? {
+        var candidate = url
+        while candidate.path != "/" {
+            if candidate.pathExtension == "app" { return candidate }
+            candidate.deleteLastPathComponent()
+        }
+        return nil
+    }
+
+    private func sanitizedVolumeName(_ name: String) -> String {
+        let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
+        let source = trimmed.isEmpty ? "GhostFile Share" : trimmed
+        let sanitized = source.replacingOccurrences(of: "/", with: "-").replacingOccurrences(of: "\0", with: "")
+        return String(sanitized.prefix(80))
+    }
+
+    private func uniqueMountPoint(root: URL, name: String) -> URL {
+        var candidate = root.appendingPathComponent(name, isDirectory: true)
+        var suffix = 2
+        while FileManager.default.fileExists(atPath: candidate.path) {
+            candidate = root.appendingPathComponent("\(name) \(suffix)", isDirectory: true)
+            suffix += 1
+        }
+        return candidate
+    }
+
+    private func validateUserSelectedMountPoint(_ mountPoint: URL) throws {
+        guard mountPoint.isFileURL else {
+            throw MountFailure("The mount point must be a local folder.")
+        }
+
+        var isDirectory: ObjCBool = false
+        guard FileManager.default.fileExists(atPath: mountPoint.path, isDirectory: &isDirectory),
+              isDirectory.boolValue else {
+            throw MountFailure("The selected mount point is not a folder.")
+        }
+
+        let contents = try FileManager.default.contentsOfDirectory(
+            at: mountPoint,
+            includingPropertiesForKeys: nil,
+            options: []
+        )
+        guard contents.isEmpty else {
+            throw MountFailure("The selected mount point must be empty.")
+        }
+    }
+
+    private func shareID(from url: URL) -> UUID? {
+        let parts = url.path.split(separator: "/", omittingEmptySubsequences: true)
+        guard parts.count == 3, parts[0] == "v1", parts[1] == "shares" else { return nil }
+        return UUID(uuidString: String(parts[2]))
+    }
+
+    nonisolated private static func run(
+        executable: String,
+        arguments: [String],
+        timeout: TimeInterval? = nil
+    ) throws {
+        _ = try runAndCapture(executable: executable, arguments: arguments, timeout: timeout)
+    }
+
+    nonisolated private static func runAndCapture(
+        executable: String,
+        arguments: [String],
+        timeout: TimeInterval? = nil
+    ) throws -> String {
+        let process = Process()
+        let output = Pipe()
+        process.executableURL = URL(fileURLWithPath: executable)
+        process.arguments = arguments
+        process.standardOutput = output
+        process.standardError = output
+        let finished = DispatchSemaphore(value: 0)
+        process.terminationHandler = { _ in finished.signal() }
+        try process.run()
+        if let timeout,
+           finished.wait(timeout: .now() + timeout) == .timedOut {
+            process.terminate()
+            if finished.wait(timeout: .now() + 2) == .timedOut {
+                kill(process.processIdentifier, SIGKILL)
+                _ = finished.wait(timeout: .now() + 2)
+            }
+            throw MountFailure("Mount timed out after \(Int(timeout)) seconds. Verify the share is still online and reachable over UDP.")
+        }
+        let data = output.fileHandleForReading.readDataToEndOfFile()
+        if timeout == nil { process.waitUntilExit() }
+        let detail = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard process.terminationStatus == 0 else {
+            throw MountFailure(detail.isEmpty ? "Command exited with status \(process.terminationStatus)" : detail)
+        }
+        return detail
+    }
+
+    private struct MountFailure: LocalizedError {
+        let detail: String
+        init(_ detail: String) { self.detail = detail }
+        var errorDescription: String? { detail }
+    }
+}
+
+@MainActor
+final class GhostFileMountLibrary: ObservableObject {
+    @Published private(set) var mounts: [SavedGhostFileMount]
+    @Published private(set) var errors: [UUID: String] = [:]
+    @Published private(set) var workingMountIDs: Set = []
+    @Published private(set) var healthSnapshots: [UUID: GhostFileMountHealthSnapshot] = [:]
+    @Published var generalError: String?
+
+    let manager: GhostFileMountManager
+    private let configurationStorage: any GhostFileMountConfigurationStorage
+    private let accessKeyStorage: any GhostFileAccessKeyStorage
+    private var runtimeIDs: [UUID: UUID] = [:]
+    private var managerObserver: AnyCancellable?
+
+    init(
+        configurationStorage: any GhostFileMountConfigurationStorage = GhostFileMountJSONStorage.applicationStorage,
+        accessKeyStorage: any GhostFileAccessKeyStorage = GhostFileKeychainAccessKeyStorage(
+            service: "org.ghostvm.ghostfile.mount-access-key"
+        ),
+        manager: GhostFileMountManager? = nil
+    ) {
+        self.configurationStorage = configurationStorage
+        self.accessKeyStorage = accessKeyStorage
+        self.manager = manager ?? GhostFileMountManager()
+        do {
+            mounts = try configurationStorage.load()
+        } catch {
+            mounts = []
+            generalError = "Unable to load saved mounts: \(error.localizedDescription)"
+        }
+        managerObserver = self.manager.objectWillChange.sink { [weak self] _ in
+            Task { @MainActor in self?.objectWillChange.send() }
+        }
+    }
+
+    func mount(withID id: UUID) -> SavedGhostFileMount? {
+        mounts.first { $0.id == id }
+    }
+
+    func accessKey(for mountID: UUID) throws -> String {
+        guard let key = try accessKeyStorage.accessKey(for: mountID), !key.isEmpty else {
+            throw GhostFileMountLibraryError.missingAccessKey
+        }
+        return key
+    }
+
+    func requestedMountPoint(for mountID: UUID) -> URL? {
+        guard let bookmark = mount(withID: mountID)?.mountPointBookmark else { return nil }
+        var stale = false
+        return try? URL(
+            resolvingBookmarkData: bookmark,
+            options: [],
+            relativeTo: nil,
+            bookmarkDataIsStale: &stale
+        )
+    }
+
+    @discardableResult
+    func addMount(
+        name: String,
+        sourceURL: String,
+        accessKey: String,
+        mountPoint: URL? = nil,
+        readOnly: Bool = true
+    ) throws -> SavedGhostFileMount {
+        let trimmedKey = accessKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedKey.isEmpty else { throw GhostFileMountLibraryError.emptyAccessKey }
+        let mount = try validatedMount(
+            id: UUID(),
+            name: name,
+            sourceURL: sourceURL,
+            mountPoint: mountPoint,
+            readOnly: readOnly
+        )
+        try accessKeyStorage.setAccessKey(
+            trimmedKey,
+            for: mount.id
+        )
+        do {
+            var updated = mounts
+            updated.append(mount)
+            try configurationStorage.save(updated)
+            mounts = updated
+            generalError = nil
+            return mount
+        } catch {
+            try? accessKeyStorage.removeAccessKey(for: mount.id)
+            throw error
+        }
+    }
+
+    func updateMount(
+        _ mountID: UUID,
+        name: String,
+        sourceURL: String,
+        accessKey: String,
+        mountPoint: URL?
+    ) throws {
+        guard let index = mounts.firstIndex(where: { $0.id == mountID }) else {
+            throw GhostFileMountLibraryError.mountNotFound
+        }
+        guard runtimeIDs[mountID] == nil else {
+            throw GhostFileMountLibraryError.unmountBeforeEditing
+        }
+        let updatedMount = try validatedMount(
+            id: mountID,
+            name: name,
+            sourceURL: sourceURL,
+            mountPoint: mountPoint,
+            readOnly: mounts[index].readOnly
+        )
+        let trimmedKey = accessKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedKey.isEmpty else { throw GhostFileMountLibraryError.emptyAccessKey }
+        let oldMounts = mounts
+        let oldKey = try accessKeyStorage.accessKey(for: mountID)
+        do {
+            try accessKeyStorage.setAccessKey(trimmedKey, for: mountID)
+            var updated = mounts
+            updated[index] = updatedMount
+            try configurationStorage.save(updated)
+            mounts = updated
+            errors[mountID] = nil
+            generalError = nil
+        } catch {
+            mounts = oldMounts
+            if let oldKey {
+                try? accessKeyStorage.setAccessKey(oldKey, for: mountID)
+            } else {
+                try? accessKeyStorage.removeAccessKey(for: mountID)
+            }
+            throw error
+        }
+    }
+
+    func status(for mountID: UUID) -> GhostFileSavedMountStatus {
+        if workingMountIDs.contains(mountID) { return .mounting }
+        if let runtimeID = runtimeIDs[mountID] {
+            if let runtime = manager.mountedShares.first(where: { $0.id == runtimeID }) {
+                if let snapshot = healthSnapshots[mountID] {
+                    switch snapshot.state {
+                    case .online: return .online(runtime.mountPoint)
+                    case .degraded: return .degraded(runtime.mountPoint)
+                    case .error:
+                        return .error(runtime.mountPoint, snapshot.detail ?? "A filesystem operation failed")
+                    case .offline: return .offline(runtime.mountPoint)
+                    }
+                }
+                return .mounted(runtime.mountPoint)
+            }
+            runtimeIDs[mountID] = nil
+            healthSnapshots[mountID] = nil
+        }
+        if let error = errors[mountID] { return .failed(error) }
+        return .stopped
+    }
+
+    func refreshExtensionStatus() async {
+        await manager.refreshExtensionStatus()
+    }
+
+    func monitorHealth() async {
+        while !Task.isCancelled {
+            await refreshHealthSnapshots()
+            do {
+                try await Task.sleep(for: .seconds(1))
+            } catch {
+                return
+            }
+        }
+    }
+
+    func mount(_ mountID: UUID) async {
+        _ = status(for: mountID)
+        guard !workingMountIDs.contains(mountID),
+              runtimeIDs[mountID] == nil,
+              let mount = mount(withID: mountID) else { return }
+        workingMountIDs.insert(mountID)
+        errors[mountID] = nil
+        defer { workingMountIDs.remove(mountID) }
+        do {
+            guard let sourceURL = URL(string: mount.sourceURL) else {
+                throw GhostFileMountLibraryError.invalidURL
+            }
+            let key = try accessKey(for: mountID)
+            let runtime = await manager.mount(
+                definitionID: mountID,
+                url: sourceURL,
+                accessKey: key,
+                volumeName: mount.name,
+                requestedMountPoint: requestedMountPoint(for: mountID)
+            )
+            guard let runtime else {
+                throw GhostFileMountLibraryError.runtimeFailure(
+                    manager.errorMessage ?? "The mount did not complete."
+                )
+            }
+            runtimeIDs[mountID] = runtime.id
+            errors[mountID] = nil
+            await refreshHealthSnapshots()
+        } catch {
+            errors[mountID] = error.localizedDescription
+        }
+    }
+
+    func unmount(_ mountID: UUID) async {
+        guard !workingMountIDs.contains(mountID),
+              let runtimeID = runtimeIDs[mountID],
+              let runtime = manager.mountedShares.first(where: { $0.id == runtimeID }) else {
+            runtimeIDs[mountID] = nil
+            healthSnapshots[mountID] = nil
+            return
+        }
+        workingMountIDs.insert(mountID)
+        defer { workingMountIDs.remove(mountID) }
+        await manager.unmount(runtime)
+        if manager.mountedShares.contains(where: { $0.id == runtimeID }) {
+            errors[mountID] = manager.errorMessage ?? "Unable to unmount."
+        } else {
+            runtimeIDs[mountID] = nil
+            healthSnapshots[mountID] = nil
+            errors[mountID] = nil
+        }
+    }
+
+    func reveal(_ mountID: UUID) {
+        if let runtimeID = runtimeIDs[mountID],
+           let runtime = manager.mountedShares.first(where: { $0.id == runtimeID }) {
+            manager.reveal(runtime)
+        } else if let mountPoint = requestedMountPoint(for: mountID) {
+            NSWorkspace.shared.activateFileViewerSelecting([mountPoint])
+        }
+    }
+
+    func delete(_ mountIDs: Set) async {
+        guard !mountIDs.isEmpty else { return }
+        for mountID in mountIDs { await unmount(mountID) }
+        let stillMounted = mountIDs.filter { runtimeIDs[$0] != nil }
+        guard stillMounted.isEmpty else {
+            generalError = "Unmount the selected volumes before deleting them."
+            return
+        }
+        let original = mounts
+        let updated = mounts.filter { !mountIDs.contains($0.id) }
+        do {
+            try configurationStorage.save(updated)
+            mounts = updated
+            for id in mountIDs {
+                try? accessKeyStorage.removeAccessKey(for: id)
+                healthSnapshots[id] = nil
+                errors[id] = nil
+            }
+            generalError = nil
+        } catch {
+            mounts = original
+            generalError = "Unable to delete the mount: \(error.localizedDescription)"
+        }
+    }
+
+    private func validatedMount(
+        id: UUID,
+        name: String,
+        sourceURL: String,
+        mountPoint: URL?,
+        readOnly: Bool
+    ) throws -> SavedGhostFileMount {
+        let trimmedName = name.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedURL = sourceURL.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedName.isEmpty else { throw GhostFileMountLibraryError.emptyName }
+        guard let url = URL(string: trimmedURL), url.scheme == GhostFileProtocol.urlScheme else {
+            throw GhostFileMountLibraryError.invalidURL
+        }
+        guard GhostFileProtocol.peerPin(from: url) != nil else {
+            throw GhostFileMountLibraryError.missingPeerIdentity
+        }
+        guard let shareID = remoteShareID(from: url),
+              let sanitizedURL = sanitizedSourceURL(url) else {
+            throw GhostFileMountLibraryError.invalidURL
+        }
+        let bookmark = try mountPoint?.bookmarkData(
+            options: [],
+            includingResourceValuesForKeys: nil,
+            relativeTo: nil
+        )
+        return SavedGhostFileMount(
+            id: id,
+            shareID: shareID,
+            name: trimmedName,
+            sourceURL: sanitizedURL.absoluteString,
+            mountPointBookmark: bookmark,
+            readOnly: readOnly
+        )
+    }
+
+    private func refreshHealthSnapshots() async {
+        for missing in manager.reconcileMountedShares() {
+            let mountID = missing.definitionID
+            runtimeIDs[mountID] = nil
+            let detail = healthSnapshots[mountID]?.detail
+                ?? "The mounted volume is no longer registered by macOS."
+            errors[mountID] = detail
+            healthSnapshots[mountID] = nil
+        }
+        let mountedInstances = runtimeIDs
+        let snapshotsByRuntimeID = await Task.detached(priority: .utility) {
+            var result: [UUID: GhostFileMountHealthSnapshot] = [:]
+            for runtimeID in mountedInstances.values {
+                let url = GhostFileMountHealthStorage.readerURL(for: runtimeID)
+                guard let data = try? Data(contentsOf: url),
+                      let snapshot = try? JSONDecoder().decode(
+                        GhostFileMountHealthSnapshot.self,
+                        from: data
+                      ) else { continue }
+                result[runtimeID] = snapshot.degradingIfStale()
+            }
+            return result
+        }.value
+
+        var updated: [UUID: GhostFileMountHealthSnapshot] = [:]
+        for (mountID, runtimeID) in runtimeIDs where mountedInstances[mountID] == runtimeID {
+            if let snapshot = snapshotsByRuntimeID[runtimeID] {
+                updated[mountID] = snapshot
+            }
+        }
+        if healthSnapshots != updated {
+            healthSnapshots = updated
+        }
+    }
+
+    private func remoteShareID(from url: URL) -> UUID? {
+        let parts = url.path.split(separator: "/", omittingEmptySubsequences: true)
+        guard parts.count == 3, parts[0] == "v1", parts[1] == "shares" else { return nil }
+        return UUID(uuidString: String(parts[2]))
+    }
+
+    private func sanitizedSourceURL(_ url: URL) -> URL? {
+        guard var components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {
+            return nil
+        }
+        components.queryItems = (components.queryItems ?? []).filter {
+            $0.name != "access_key" && $0.name != GhostFileProtocol.mountInstanceQueryName
+        }
+        if components.queryItems?.isEmpty == true { components.queryItems = nil }
+        return components.url
+    }
+}
+
+private enum GhostFileMountLibraryError: LocalizedError {
+    case mountNotFound
+    case emptyName
+    case emptyAccessKey
+    case missingAccessKey
+    case missingPeerIdentity
+    case invalidURL
+    case unmountBeforeEditing
+    case runtimeFailure(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .mountNotFound: "The saved mount no longer exists."
+        case .emptyName: "Enter a volume name."
+        case .emptyAccessKey: "Enter an access key."
+        case .missingAccessKey: "The saved access key is missing."
+        case .missingPeerIdentity: "The share URL is missing a valid TLS identity pin. Copy a new link from the sharing Mac."
+        case .invalidURL: "Enter a valid ghostfile:// share URL."
+        case .unmountBeforeEditing: "Unmount this volume before editing its connection settings."
+        case .runtimeFailure(let detail): detail
+        }
+    }
+}
diff --git a/macOS/GhostFile/GhostFileShareController.swift b/macOS/GhostFile/GhostFileShareController.swift
new file mode 100644
index 0000000..8262626
--- /dev/null
+++ b/macOS/GhostFile/GhostFileShareController.swift
@@ -0,0 +1,524 @@
+import AppKit
+import Combine
+import Foundation
+import GhostFileKit
+import Security
+
+struct SavedGhostFileShare: Identifiable, Codable, Equatable {
+    let id: UUID
+    var name: String
+    var folderBookmark: Data
+    var preferredPort: UInt16
+    var readOnly: Bool
+}
+
+enum GhostFileShareStatus: Equatable {
+    case stopped
+    case starting
+    case online
+    case failed(String)
+}
+
+protocol GhostFileShareConfigurationStorage {
+    func load() throws -> [SavedGhostFileShare]
+    func save(_ shares: [SavedGhostFileShare]) throws
+}
+
+struct GhostFileShareJSONStorage: GhostFileShareConfigurationStorage {
+    let fileURL: URL
+
+    static var applicationStorage: Self {
+        let root = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            .appendingPathComponent("GhostFile", isDirectory: true)
+        return Self(fileURL: root.appendingPathComponent("shares.json"))
+    }
+
+    func load() throws -> [SavedGhostFileShare] {
+        guard FileManager.default.fileExists(atPath: fileURL.path) else { return [] }
+        return try JSONDecoder().decode([SavedGhostFileShare].self, from: Data(contentsOf: fileURL))
+    }
+
+    func save(_ shares: [SavedGhostFileShare]) throws {
+        try FileManager.default.createDirectory(
+            at: fileURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        let data = try JSONEncoder().encode(shares)
+        try data.write(to: fileURL, options: .atomic)
+    }
+}
+
+protocol GhostFileAccessKeyStorage {
+    func accessKey(for shareID: UUID) throws -> String?
+    func setAccessKey(_ accessKey: String, for shareID: UUID) throws
+    func removeAccessKey(for shareID: UUID) throws
+}
+
+struct GhostFileKeychainAccessKeyStorage: GhostFileAccessKeyStorage {
+    private let service: String
+
+    init(service: String = "org.ghostvm.ghostfile.share-access-key") {
+        self.service = service
+    }
+
+    func accessKey(for shareID: UUID) throws -> String? {
+        var query = baseQuery(for: shareID)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound { return nil }
+        guard status == errSecSuccess,
+              let data = result as? Data,
+              let value = String(data: data, encoding: .utf8) else {
+            throw GhostFileKeychainError(status: status)
+        }
+        return value
+    }
+
+    func setAccessKey(_ accessKey: String, for shareID: UUID) throws {
+        let query = baseQuery(for: shareID)
+        let attributes = [kSecValueData as String: Data(accessKey.utf8)]
+        let updateStatus = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
+        if updateStatus == errSecSuccess { return }
+        guard updateStatus == errSecItemNotFound else {
+            throw GhostFileKeychainError(status: updateStatus)
+        }
+        var item = query
+        item[kSecValueData as String] = Data(accessKey.utf8)
+        let addStatus = SecItemAdd(item as CFDictionary, nil)
+        guard addStatus == errSecSuccess else {
+            throw GhostFileKeychainError(status: addStatus)
+        }
+    }
+
+    func removeAccessKey(for shareID: UUID) throws {
+        let status = SecItemDelete(baseQuery(for: shareID) as CFDictionary)
+        guard status == errSecSuccess || status == errSecItemNotFound else {
+            throw GhostFileKeychainError(status: status)
+        }
+    }
+
+    private func baseQuery(for shareID: UUID) -> [String: Any] {
+        [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: shareID.uuidString.lowercased(),
+        ]
+    }
+}
+
+protocol GhostFileTLSPrivateKeyStorage {
+    func privateKey(for shareID: UUID) throws -> Data?
+    func setPrivateKey(_ privateKey: Data, for shareID: UUID) throws
+    func removePrivateKey(for shareID: UUID) throws
+}
+
+struct GhostFileKeychainTLSPrivateKeyStorage: GhostFileTLSPrivateKeyStorage {
+    private let service: String
+
+    init(service: String = "org.ghostvm.ghostfile.share-tls-private-key") {
+        self.service = service
+    }
+
+    func privateKey(for shareID: UUID) throws -> Data? {
+        var query = baseQuery(for: shareID)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound { return nil }
+        guard status == errSecSuccess, let data = result as? Data else {
+            throw GhostFileKeychainError(status: status)
+        }
+        return data
+    }
+
+    func setPrivateKey(_ privateKey: Data, for shareID: UUID) throws {
+        let query = baseQuery(for: shareID)
+        let attributes = [kSecValueData as String: privateKey]
+        let updateStatus = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
+        if updateStatus == errSecSuccess { return }
+        guard updateStatus == errSecItemNotFound else {
+            throw GhostFileKeychainError(status: updateStatus)
+        }
+        var item = query
+        item[kSecValueData as String] = privateKey
+        item[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        let addStatus = SecItemAdd(item as CFDictionary, nil)
+        guard addStatus == errSecSuccess else {
+            throw GhostFileKeychainError(status: addStatus)
+        }
+    }
+
+    func removePrivateKey(for shareID: UUID) throws {
+        let status = SecItemDelete(baseQuery(for: shareID) as CFDictionary)
+        guard status == errSecSuccess || status == errSecItemNotFound else {
+            throw GhostFileKeychainError(status: status)
+        }
+    }
+
+    private func baseQuery(for shareID: UUID) -> [String: Any] {
+        [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: shareID.uuidString.lowercased(),
+        ]
+    }
+}
+
+private struct GhostFileKeychainError: LocalizedError {
+    let status: OSStatus
+    var errorDescription: String? {
+        SecCopyErrorMessageString(status, nil) as String?
+            ?? "Keychain error \(status)"
+    }
+}
+
+@MainActor
+protocol GhostFileShareRuntime: AnyObject {
+    var isRunning: Bool { get }
+    var shareURL: URL? { get }
+    var requestCount: Int { get }
+    var objectWillChange: ObservableObjectPublisher { get }
+    func start(preferredPort: UInt16) throws
+    func stop()
+    func setReadOnly(_ readOnly: Bool)
+}
+
+extension GhostFileShareServer: GhostFileShareRuntime {}
+
+@MainActor
+final class GhostFileLibrary: ObservableObject {
+    typealias ServerFactory = @MainActor (
+        SavedGhostFileShare,
+        URL,
+        String,
+        GhostFileTLSIdentity
+    ) -> any GhostFileShareRuntime
+
+    @Published private(set) var shares: [SavedGhostFileShare]
+    @Published private(set) var errors: [UUID: String] = [:]
+    @Published var generalError: String?
+
+    private let configurationStorage: any GhostFileShareConfigurationStorage
+    private let accessKeyStorage: any GhostFileAccessKeyStorage
+    private let tlsPrivateKeyStorage: any GhostFileTLSPrivateKeyStorage
+    private let serverFactory: ServerFactory
+    private var servers: [UUID: any GhostFileShareRuntime] = [:]
+    private var serverObservers: [UUID: AnyCancellable] = [:]
+    private var accessedFolders: [UUID: URL] = [:]
+
+    init(
+        configurationStorage: any GhostFileShareConfigurationStorage = GhostFileShareJSONStorage.applicationStorage,
+        accessKeyStorage: any GhostFileAccessKeyStorage = GhostFileKeychainAccessKeyStorage(),
+        tlsPrivateKeyStorage: any GhostFileTLSPrivateKeyStorage = GhostFileKeychainTLSPrivateKeyStorage(),
+        serverFactory: @escaping ServerFactory = { share, folder, accessKey, identity in
+            GhostFileShareServer(
+                rootURL: folder,
+                shareName: share.name,
+                accessKey: accessKey,
+                shareID: share.id,
+                readOnly: share.readOnly,
+                tlsIdentity: identity
+            )
+        }
+    ) {
+        self.configurationStorage = configurationStorage
+        self.accessKeyStorage = accessKeyStorage
+        self.tlsPrivateKeyStorage = tlsPrivateKeyStorage
+        self.serverFactory = serverFactory
+        do {
+            shares = try configurationStorage.load()
+        } catch {
+            shares = []
+            generalError = "Unable to load saved shares: \(error.localizedDescription)"
+        }
+    }
+
+    @discardableResult
+    func addShareUsingPanel() -> SavedGhostFileShare? {
+        let panel = NSOpenPanel()
+        panel.title = "Choose a folder to share"
+        panel.prompt = "Add Share"
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.allowsMultipleSelection = false
+        guard panel.runModal() == .OK, let folder = panel.url else { return nil }
+        do {
+            let share = try addShare(folderURL: folder)
+            generalError = nil
+            return share
+        } catch {
+            generalError = "Unable to add the share: \(error.localizedDescription)"
+            return nil
+        }
+    }
+
+    @discardableResult
+    func addShare(
+        folderURL: URL,
+        name: String? = nil,
+        preferredPort: UInt16 = 0,
+        accessKey: String = UUID().uuidString.lowercased()
+    ) throws -> SavedGhostFileShare {
+        let trimmedAccessKey = accessKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedAccessKey.isEmpty else { throw GhostFileLibraryError.emptyAccessKey }
+        let bookmark = try folderURL.bookmarkData(
+            options: [],
+            includingResourceValuesForKeys: nil,
+            relativeTo: nil
+        )
+        let trimmedName = name?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let share = SavedGhostFileShare(
+            id: UUID(),
+            name: trimmedName?.isEmpty == false ? trimmedName! : folderURL.lastPathComponent,
+            folderBookmark: bookmark,
+            preferredPort: preferredPort,
+            readOnly: true
+        )
+        let identity = try GhostFileTLSIdentity.make()
+        try tlsPrivateKeyStorage.setPrivateKey(identity.privateKeyRepresentation, for: share.id)
+        do {
+            try accessKeyStorage.setAccessKey(trimmedAccessKey, for: share.id)
+            var updated = shares
+            updated.append(share)
+            try configurationStorage.save(updated)
+            shares = updated
+            return share
+        } catch {
+            try? accessKeyStorage.removeAccessKey(for: share.id)
+            try? tlsPrivateKeyStorage.removePrivateKey(for: share.id)
+            throw error
+        }
+    }
+
+    func share(withID id: UUID) -> SavedGhostFileShare? {
+        shares.first { $0.id == id }
+    }
+
+    func accessKey(for shareID: UUID) throws -> String {
+        guard let accessKey = try accessKeyStorage.accessKey(for: shareID), !accessKey.isEmpty else {
+            throw GhostFileLibraryError.missingAccessKey
+        }
+        return accessKey
+    }
+
+    func publicKeyPin(for shareID: UUID) throws -> String {
+        guard share(withID: shareID) != nil else { throw GhostFileLibraryError.shareNotFound }
+        return try persistentIdentity(for: shareID).publicKeyPin
+    }
+
+    func rotateTLSIdentity(for shareID: UUID) {
+        guard share(withID: shareID) != nil else { return }
+        guard servers[shareID] == nil else {
+            errors[shareID] = "Stop sharing before rotating its TLS identity."
+            return
+        }
+        do {
+            let identity = try GhostFileTLSIdentity.make()
+            try tlsPrivateKeyStorage.setPrivateKey(identity.privateKeyRepresentation, for: shareID)
+            errors[shareID] = nil
+            generalError = nil
+        } catch {
+            errors[shareID] = "Unable to rotate the TLS identity: \(error.localizedDescription)"
+        }
+    }
+
+    func updateShare(
+        _ shareID: UUID,
+        name: String,
+        preferredPort: UInt16,
+        accessKey: String,
+        folderURL: URL? = nil
+    ) throws {
+        guard let index = shares.firstIndex(where: { $0.id == shareID }) else {
+            throw GhostFileLibraryError.shareNotFound
+        }
+        let trimmedName = name.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedAccessKey = accessKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedName.isEmpty else { throw GhostFileLibraryError.emptyName }
+        guard !trimmedAccessKey.isEmpty else { throw GhostFileLibraryError.emptyAccessKey }
+
+        var updatedShare = shares[index]
+        updatedShare.name = trimmedName
+        updatedShare.preferredPort = preferredPort
+        if let folderURL {
+            updatedShare.folderBookmark = try folderURL.bookmarkData(
+                options: [],
+                includingResourceValuesForKeys: nil,
+                relativeTo: nil
+            )
+        }
+
+        let oldShares = shares
+        let oldAccessKey = try accessKeyStorage.accessKey(for: shareID)
+        let wasActive = status(for: shareID) == .online || status(for: shareID) == .starting
+        if wasActive { stop(shareID) }
+        do {
+            try accessKeyStorage.setAccessKey(trimmedAccessKey, for: shareID)
+            var updatedShares = shares
+            updatedShares[index] = updatedShare
+            try configurationStorage.save(updatedShares)
+            shares = updatedShares
+            errors[shareID] = nil
+            generalError = nil
+            if wasActive { start(shareID) }
+        } catch {
+            shares = oldShares
+            if let oldAccessKey {
+                try? accessKeyStorage.setAccessKey(oldAccessKey, for: shareID)
+            } else {
+                try? accessKeyStorage.removeAccessKey(for: shareID)
+            }
+            if wasActive { start(shareID) }
+            throw error
+        }
+    }
+
+    func setReadOnly(_ readOnly: Bool, for shareID: UUID) {
+        guard let index = shares.firstIndex(where: { $0.id == shareID }),
+              shares[index].readOnly != readOnly else { return }
+        let original = shares
+        var updated = shares
+        updated[index].readOnly = readOnly
+        do {
+            try configurationStorage.save(updated)
+            shares = updated
+            servers[shareID]?.setReadOnly(readOnly)
+            errors[shareID] = nil
+            generalError = nil
+        } catch {
+            shares = original
+            generalError = "Unable to change share access: \(error.localizedDescription)"
+        }
+    }
+
+    func folderURL(for shareID: UUID) -> URL? {
+        guard let share = share(withID: shareID) else { return nil }
+        return try? resolveFolder(for: share)
+    }
+
+    func shareURL(for shareID: UUID) -> URL? {
+        servers[shareID]?.shareURL
+    }
+
+    func requestCount(for shareID: UUID) -> Int {
+        servers[shareID]?.requestCount ?? 0
+    }
+
+    func status(for shareID: UUID) -> GhostFileShareStatus {
+        if let error = errors[shareID] { return .failed(error) }
+        guard let server = servers[shareID] else { return .stopped }
+        return server.isRunning ? .online : .starting
+    }
+
+    func start(_ shareID: UUID) {
+        guard servers[shareID] == nil, let share = share(withID: shareID) else { return }
+        do {
+            guard let accessKey = try accessKeyStorage.accessKey(for: shareID), !accessKey.isEmpty else {
+                throw GhostFileLibraryError.missingAccessKey
+            }
+            let folder = try resolveFolder(for: share)
+            let isAccessing = folder.startAccessingSecurityScopedResource()
+            if isAccessing { accessedFolders[shareID] = folder }
+            let identity = try persistentIdentity(for: shareID)
+            let server = serverFactory(share, folder, accessKey, identity)
+            serverObservers[shareID] = server.objectWillChange.sink { [weak self] _ in
+                Task { @MainActor in self?.objectWillChange.send() }
+            }
+            servers[shareID] = server
+            errors[shareID] = nil
+            do {
+                try server.start(preferredPort: share.preferredPort)
+            } catch {
+                servers[shareID] = nil
+                serverObservers[shareID] = nil
+                stopAccessingFolder(for: shareID)
+                throw error
+            }
+            objectWillChange.send()
+        } catch {
+            stopAccessingFolder(for: shareID)
+            errors[shareID] = error.localizedDescription
+        }
+    }
+
+    func stop(_ shareID: UUID) {
+        servers.removeValue(forKey: shareID)?.stop()
+        serverObservers[shareID] = nil
+        stopAccessingFolder(for: shareID)
+        errors[shareID] = nil
+        objectWillChange.send()
+    }
+
+    func reveal(_ shareID: UUID) {
+        guard let folder = folderURL(for: shareID) else { return }
+        NSWorkspace.shared.activateFileViewerSelecting([folder])
+    }
+
+    func delete(_ shareIDs: Set) {
+        guard !shareIDs.isEmpty else { return }
+        for shareID in shareIDs { stop(shareID) }
+        let original = shares
+        let updated = shares.filter { !shareIDs.contains($0.id) }
+        do {
+            try configurationStorage.save(updated)
+            shares = updated
+            for shareID in shareIDs {
+                try? accessKeyStorage.removeAccessKey(for: shareID)
+                try? tlsPrivateKeyStorage.removePrivateKey(for: shareID)
+            }
+            generalError = nil
+        } catch {
+            shares = original
+            generalError = "Unable to delete the share: \(error.localizedDescription)"
+        }
+    }
+
+    private func resolveFolder(for share: SavedGhostFileShare) throws -> URL {
+        var stale = false
+        let folder = try URL(
+            resolvingBookmarkData: share.folderBookmark,
+            options: [],
+            relativeTo: nil,
+            bookmarkDataIsStale: &stale
+        )
+        if stale {
+            throw GhostFileLibraryError.staleFolderPermission
+        }
+        return folder
+    }
+
+    private func persistentIdentity(for shareID: UUID) throws -> GhostFileTLSIdentity {
+        if let storedKey = try tlsPrivateKeyStorage.privateKey(for: shareID) {
+            return try GhostFileTLSIdentity.make(privateKeyRepresentation: storedKey)
+        }
+        // Existing shares are migrated lazily the first time they start.
+        let identity = try GhostFileTLSIdentity.make()
+        try tlsPrivateKeyStorage.setPrivateKey(identity.privateKeyRepresentation, for: shareID)
+        return identity
+    }
+
+    private func stopAccessingFolder(for shareID: UUID) {
+        accessedFolders.removeValue(forKey: shareID)?.stopAccessingSecurityScopedResource()
+    }
+}
+
+private enum GhostFileLibraryError: LocalizedError {
+    case shareNotFound
+    case emptyName
+    case emptyAccessKey
+    case missingAccessKey
+    case staleFolderPermission
+
+    var errorDescription: String? {
+        switch self {
+        case .shareNotFound: "The saved share no longer exists."
+        case .emptyName: "Enter a share name."
+        case .emptyAccessKey: "Enter an access key."
+        case .missingAccessKey: "The saved access key is missing. Delete and add the share again."
+        case .staleFolderPermission: "Choose the shared folder again; its saved permission is stale."
+        }
+    }
+}
diff --git a/macOS/GhostFile/Info.plist b/macOS/GhostFile/Info.plist
new file mode 100644
index 0000000..838f23e
--- /dev/null
+++ b/macOS/GhostFile/Info.plist
@@ -0,0 +1,32 @@
+
+
+
+
+	CFBundleDevelopmentRegion
+	$(DEVELOPMENT_LANGUAGE)
+	CFBundleExecutable
+	$(EXECUTABLE_NAME)
+	CFBundleIdentifier
+	$(PRODUCT_BUNDLE_IDENTIFIER)
+	CFBundleInfoDictionaryVersion
+	6.0
+	CFBundleName
+	GhostFile
+	CFBundlePackageType
+	APPL
+	CFBundleShortVersionString
+	$(MARKETING_VERSION)
+	CFBundleVersion
+	$(CURRENT_PROJECT_VERSION)
+	LSApplicationCategoryType
+	public.app-category.utilities
+	NSBonjourServices
+	
+		_ghostfile._udp
+	
+	NSLocalNetworkUsageDescription
+	GhostFile discovers, shares, and mounts folders on your local network.
+	NSPrincipalClass
+	NSApplication
+
+
diff --git a/macOS/GhostFile/NotarizeOptions.plist b/macOS/GhostFile/NotarizeOptions.plist
new file mode 100644
index 0000000..46c5662
--- /dev/null
+++ b/macOS/GhostFile/NotarizeOptions.plist
@@ -0,0 +1,12 @@
+
+
+
+
+	destination
+	upload
+	method
+	developer-id
+	signingStyle
+	automatic
+
+
diff --git a/macOS/GhostFile/entitlements.plist b/macOS/GhostFile/entitlements.plist
new file mode 100644
index 0000000..0c67376
--- /dev/null
+++ b/macOS/GhostFile/entitlements.plist
@@ -0,0 +1,5 @@
+
+
+
+
+
diff --git a/macOS/GhostFileFS/FileSystemExtension.swift b/macOS/GhostFileFS/FileSystemExtension.swift
new file mode 100644
index 0000000..0b351fd
--- /dev/null
+++ b/macOS/GhostFileFS/FileSystemExtension.swift
@@ -0,0 +1,10 @@
+import ExtensionFoundation
+import FSKit
+import GhostFileKit
+
+@main
+struct GhostFileSystemExtension: UnaryFileSystemExtension {
+    var fileSystem: GhostFileSystem {
+        GhostFileSystem()
+    }
+}
diff --git a/macOS/GhostFileFS/Info.plist b/macOS/GhostFileFS/Info.plist
new file mode 100644
index 0000000..4e2f638
--- /dev/null
+++ b/macOS/GhostFileFS/Info.plist
@@ -0,0 +1,70 @@
+
+
+
+
+	CFBundleDevelopmentRegion
+	$(DEVELOPMENT_LANGUAGE)
+	CFBundleExecutable
+	$(EXECUTABLE_NAME)
+	CFBundleIdentifier
+	$(PRODUCT_BUNDLE_IDENTIFIER)
+	CFBundleInfoDictionaryVersion
+	6.0
+	CFBundleName
+	$(PRODUCT_NAME)
+	CFBundlePackageType
+	XPC!
+	CFBundleShortVersionString
+	$(MARKETING_VERSION)
+	CFBundleVersion
+	$(CURRENT_PROJECT_VERSION)
+	EXAppExtensionAttributes
+	
+		EXExtensionPointIdentifier
+		com.apple.fskit.fsmodule
+		FSActivateOptionSyntax
+		
+			shortOptions
+			g:m:o:u:
+		
+		FSCheckOptionSyntax
+		
+			shortOptions
+			nqy
+		
+		FSFormatOptionSyntax
+		
+			shortOptions
+			v
+		
+		FSMediaTypes
+		
+		FSPersonalities
+		
+			GhostFile
+			
+				FSName
+				ghostfile
+				FSfileObjectsAreCaseSensitive
+				
+			
+		
+		FSRequiresSecurityScopedPathURLResources
+		
+		FSShortName
+		ghostfile
+		FSSupportedSchemes
+		
+			ghostfile
+		
+		FSSupportsBlockResources
+		
+		FSSupportsGenericURLResources
+		
+		FSSupportsPathURLs
+		
+		FSSupportsServerURLs
+		
+	
+
+
diff --git a/macOS/GhostFileFS/entitlements.plist b/macOS/GhostFileFS/entitlements.plist
new file mode 100644
index 0000000..93e61a7
--- /dev/null
+++ b/macOS/GhostFileFS/entitlements.plist
@@ -0,0 +1,12 @@
+
+
+
+
+	com.apple.developer.fskit.fsmodule
+	
+	com.apple.security.app-sandbox
+	
+	com.apple.security.network.client
+	
+
+
diff --git a/macOS/GhostFileKit/GhostFileHTTP3.swift b/macOS/GhostFileKit/GhostFileHTTP3.swift
new file mode 100644
index 0000000..4fe284c
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileHTTP3.swift
@@ -0,0 +1,987 @@
+import Darwin
+import Foundation
+import GhostHTTP3
+import Network
+
+final class GhostFileHTTP3Connection: @unchecked Sendable {
+    static let h3NoError: UInt64 = 0x0100
+    static let h3InternalError: UInt64 = 0x0102
+
+    private static let maximumUDPPayloadSize: Int = {
+        guard let rawValue = ProcessInfo.processInfo.environment["GHOSTFILE_HTTP3_UDP_PAYLOAD_SIZE"],
+              let value = Int(rawValue), (1_200...65_527).contains(value) else {
+            return 1_350
+        }
+        return value
+    }()
+    private static let diagnosticsEnabled =
+        ProcessInfo.processInfo.environment["GHOSTFILE_HTTP3_DIAGNOSTICS"] == "1"
+
+    enum Role {
+        case client(serverName: String)
+        case server(certificatePath: String, privateKeyPath: String)
+    }
+
+    enum Event {
+        case headers(streamID: UInt64, fields: [(String, String)], hasBody: Bool)
+        case data(streamID: UInt64)
+        case finished(streamID: UInt64)
+        case reset(streamID: UInt64)
+    }
+
+    enum ConnectionError: LocalizedError {
+        case configuration(String)
+        case connection(String)
+        case http3(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .configuration(let message), .connection(let message), .http3(let message):
+                return message
+            }
+        }
+    }
+
+    private let role: Role
+    private let quicConfiguration: OpaquePointer
+    private let http3Configuration: OpaquePointer
+    private var quicConnection: OpaquePointer?
+    private var http3Connection: OpaquePointer?
+    private var currentEvent: OpaquePointer?
+    // Reuse one receive buffer per QUIC connection. Every caller confines a
+    // GhostFileHTTP3Connection to its connection actor, so this storage is
+    // never accessed concurrently.
+    private var receiveScratchBuffer = Data(count: 64 * 1024)
+    private var pendingRequestBodies: [UInt64: PendingHTTP3RequestBody] = [:]
+    private var pendingResponses: [UInt64: PendingHTTP3Response] = [:]
+    private var peerTerminatedResponseStreamIDs: [UInt64] = []
+    private var failedResponseStreamIDs: [UInt64] = []
+    private var localAddress = sockaddr_in()
+    private var peerAddress = sockaddr_in()
+    private let diagnosticRole: String
+    private var diagnosticStartedAt = DispatchTime.now().uptimeNanoseconds
+    private var diagnosticPumpCalls = 0
+    private var diagnosticStreamVisits = 0
+    private var diagnosticBodyAttempts = 0
+    private var diagnosticBodyBlocked = 0
+    private var diagnosticBodyAcceptedBytes = 0
+    private var diagnosticNextDatagramCalls = 0
+    private var diagnosticDatagrams = 0
+    private var diagnosticDatagramBytes = 0
+    private var diagnosticSendDone = 0
+    private var diagnosticFuturePacingPackets = 0
+    private var diagnosticFuturePacingNanoseconds: UInt64 = 0
+    private var diagnosticMaximumPacingNanoseconds: UInt64 = 0
+    private var diagnosticBatches = 0
+    private var diagnosticBatchPackets = 0
+    private var diagnosticProduceNanoseconds: UInt64 = 0
+    private var diagnosticNetworkNanoseconds: UInt64 = 0
+
+    init(role: Role) throws {
+        self.role = role
+        switch role {
+        case .client: diagnosticRole = "client"
+        case .server: diagnosticRole = "server"
+        }
+        guard let quicConfiguration = quiche_config_new(UInt32(QUICHE_PROTOCOL_VERSION)) else {
+            throw ConnectionError.configuration("Unable to create the QUIC configuration")
+        }
+        self.quicConfiguration = quicConfiguration
+        guard let http3Configuration = quiche_h3_config_new() else {
+            quiche_config_free(quicConfiguration)
+            throw ConnectionError.configuration("Unable to create the HTTP/3 configuration")
+        }
+        self.http3Configuration = http3Configuration
+
+        let alpn = [UInt8](QUICHE_H3_APPLICATION_PROTOCOL.utf8)
+        guard quiche_config_set_application_protos(quicConfiguration, alpn, alpn.count) == 0 else {
+            throw ConnectionError.configuration("Unable to configure the HTTP/3 ALPN")
+        }
+        quiche_config_set_max_idle_timeout(quicConfiguration, 60_000)
+        quiche_config_set_max_recv_udp_payload_size(quicConfiguration, Self.maximumUDPPayloadSize)
+        quiche_config_set_max_send_udp_payload_size(quicConfiguration, Self.maximumUDPPayloadSize)
+        // Start application traffic at QUIC's guaranteed 1200-byte datagram
+        // size and probe upward before using the configured maximum. Without
+        // DPLPMTUD, a path that carries the 1200-byte handshake but drops our
+        // former 1350-byte data packets becomes a permanent MTU black hole.
+        // This is common across VM bridges, VPNs, and IPv6 paths.
+        quiche_config_discover_pmtu(quicConfiguration, true)
+        quiche_config_set_initial_max_data(quicConfiguration, 64 * 1024 * 1024)
+        quiche_config_set_initial_max_stream_data_bidi_local(quicConfiguration, 2 * 1024 * 1024)
+        quiche_config_set_initial_max_stream_data_bidi_remote(quicConfiguration, 2 * 1024 * 1024)
+        quiche_config_set_initial_max_stream_data_uni(quicConfiguration, 2 * 1024 * 1024)
+        // Each GhostFile content response is capped at 1 MiB. Keep the maximum
+        // number of concurrent request streams aligned with the 64 MiB
+        // connection window so application-side response buffering is bounded.
+        quiche_config_set_initial_max_streams_bidi(quicConfiguration, 64)
+        quiche_config_set_initial_max_streams_uni(quicConfiguration, 16)
+        quiche_config_set_disable_active_migration(quicConfiguration, true)
+        quiche_h3_config_set_qpack_max_table_capacity(http3Configuration, 4_096)
+        quiche_h3_config_set_qpack_blocked_streams(http3Configuration, 100)
+
+        Self.fillAddress(&localAddress, port: 41_000)
+        Self.fillAddress(&peerAddress, port: 41_001)
+
+        switch role {
+        case .client(let serverName):
+            quiche_config_verify_peer(quicConfiguration, false)
+            var sourceID = [UInt8](repeating: 0, count: 16)
+            arc4random_buf(&sourceID, sourceID.count)
+            quicConnection = withAddresses { local, localLength, peer, peerLength in
+                sourceID.withUnsafeBufferPointer { sourceID in
+                    serverName.withCString { serverName in
+                        quiche_connect(
+                            serverName,
+                            sourceID.baseAddress,
+                            sourceID.count,
+                            local,
+                            localLength,
+                            peer,
+                            peerLength,
+                            quicConfiguration
+                        )
+                    }
+                }
+            }
+            guard quicConnection != nil else {
+                throw ConnectionError.connection("Unable to create the client QUIC connection")
+            }
+
+        case .server(let certificatePath, let privateKeyPath):
+            guard quiche_config_load_cert_chain_from_pem_file(quicConfiguration, certificatePath) == 0 else {
+                throw ConnectionError.configuration("Unable to load the GhostFile TLS certificate")
+            }
+            guard quiche_config_load_priv_key_from_pem_file(quicConfiguration, privateKeyPath) == 0 else {
+                throw ConnectionError.configuration("Unable to load the GhostFile TLS private key")
+            }
+            swap(&localAddress, &peerAddress)
+        }
+    }
+
+    deinit {
+        if let currentEvent { quiche_h3_event_free(currentEvent) }
+        if let http3Connection { quiche_h3_conn_free(http3Connection) }
+        if let quicConnection { quiche_conn_free(quicConnection) }
+        quiche_h3_config_free(http3Configuration)
+        quiche_config_free(quicConfiguration)
+    }
+
+    var isEstablished: Bool {
+        guard let quicConnection else { return false }
+        return quiche_conn_is_established(quicConnection)
+    }
+
+    var isClosed: Bool {
+        guard let quicConnection else { return false }
+        return quiche_conn_is_closed(quicConnection)
+    }
+
+    var isClosedOrDraining: Bool {
+        guard let quicConnection else { return false }
+        return quiche_conn_is_closed(quicConnection) || quiche_conn_is_draining(quicConnection)
+    }
+
+    var peerConnectionError: (isApplication: Bool, code: UInt64, reason: String)? {
+        guard let quicConnection else { return nil }
+        var isApplication = false
+        var code: UInt64 = 0
+        var reasonPointer: UnsafePointer?
+        var reasonLength = 0
+        guard quiche_conn_peer_error(
+            quicConnection,
+            &isApplication,
+            &code,
+            &reasonPointer,
+            &reasonLength
+        ) else {
+            return nil
+        }
+        let reason = reasonPointer.map {
+            String(decoding: UnsafeBufferPointer(start: $0, count: reasonLength), as: UTF8.self)
+        } ?? ""
+        return (isApplication, code, reason)
+    }
+
+    var timeoutNanoseconds: UInt64? {
+        guard let quicConnection else { return nil }
+        let value = quiche_conn_timeout_as_nanos(quicConnection)
+        return value == UInt64.max ? nil : value
+    }
+
+    var availableRequestStreamCount: UInt64 {
+        guard let quicConnection else { return 0 }
+        return quiche_conn_peer_streams_left_bidi(quicConnection)
+    }
+
+    func handleTimeout() {
+        guard let quicConnection else { return }
+        quiche_conn_on_timeout(quicConnection)
+    }
+
+    func close(
+        applicationErrorCode: UInt64 = GhostFileHTTP3Connection.h3NoError,
+        reason: String = "share-stopped"
+    ) throws {
+        guard let quicConnection, !isClosedOrDraining else { return }
+        let reasonBytes = Array(reason.utf8)
+        let result = reasonBytes.withUnsafeBufferPointer { bytes in
+            quiche_conn_close(
+                quicConnection,
+                true,
+                applicationErrorCode,
+                bytes.baseAddress,
+                bytes.count
+            )
+        }
+        guard result == 0 else {
+            throw ConnectionError.connection("Unable to close the QUIC connection (\(result))")
+        }
+    }
+
+    func receive(_ datagram: Data) throws {
+        if quicConnection == nil {
+            try acceptInitial(datagram)
+        }
+        guard let quicConnection else {
+            throw ConnectionError.connection("The server did not accept the QUIC connection")
+        }
+        var mutableDatagram = datagram
+        let result = withAddresses { local, localLength, peer, peerLength -> Int in
+            var receiveInfo = quiche_recv_info(
+                from: UnsafeMutablePointer(mutating: peer),
+                from_len: peerLength,
+                to: UnsafeMutablePointer(mutating: local),
+                to_len: localLength
+            )
+            return mutableDatagram.withUnsafeMutableBytes { bytes in
+                Int(quiche_conn_recv(
+                    quicConnection,
+                    bytes.bindMemory(to: UInt8.self).baseAddress,
+                    bytes.count,
+                    &receiveInfo
+                ))
+            }
+        }
+        guard result >= 0 else {
+            throw ConnectionError.connection("QUIC rejected a UDP datagram (\(result))")
+        }
+        try createHTTP3ConnectionIfReady()
+        try pumpResponseBodies()
+    }
+
+    func nextScheduledDatagram() throws -> GhostFileScheduledDatagram? {
+        guard let quicConnection else { return nil }
+        if Self.diagnosticsEnabled { diagnosticNextDatagramCalls += 1 }
+        try pumpResponseBodies()
+        var output = Data(count: Self.maximumUDPPayloadSize)
+        var sendInfo = quiche_send_info()
+        let length = output.withUnsafeMutableBytes { bytes in
+            Int(quiche_conn_send(
+                quicConnection,
+                bytes.bindMemory(to: UInt8.self).baseAddress,
+                bytes.count,
+                &sendInfo
+            ))
+        }
+        if length == Int(QUICHE_ERR_DONE.rawValue) {
+            if Self.diagnosticsEnabled { diagnosticSendDone += 1 }
+            return nil
+        }
+        guard length > 0 else {
+            throw ConnectionError.connection("QUIC could not produce a UDP datagram (\(length))")
+        }
+        output.count = length
+        let nowNanoseconds = ghostFileMonotonicNanoseconds()
+        let rawSendNanoseconds = Int64(sendInfo.at.tv_sec) * 1_000_000_000
+            + Int64(sendInfo.at.tv_nsec)
+        let sendNanoseconds = rawSendNanoseconds > 0 ? UInt64(rawSendNanoseconds) : nowNanoseconds
+        if Self.diagnosticsEnabled {
+            diagnosticDatagrams += 1
+            diagnosticDatagramBytes += length
+            if sendNanoseconds > nowNanoseconds {
+                let delay = sendNanoseconds - nowNanoseconds
+                diagnosticFuturePacingPackets += 1
+                diagnosticFuturePacingNanoseconds += delay
+                diagnosticMaximumPacingNanoseconds = max(diagnosticMaximumPacingNanoseconds, delay)
+            }
+        }
+        return GhostFileScheduledDatagram(data: output, sendAtNanoseconds: sendNanoseconds)
+    }
+
+    // The in-memory protocol tests intentionally deliver datagrams without a
+    // wall clock. Production Network.framework callers use the scheduled API.
+    func nextDatagram() throws -> Data? {
+        try nextScheduledDatagram()?.data
+    }
+
+    func recordSendBatch(packetCount: Int, produceNanoseconds: UInt64, networkNanoseconds: UInt64) {
+        guard Self.diagnosticsEnabled else { return }
+        diagnosticBatches += 1
+        diagnosticBatchPackets += packetCount
+        diagnosticProduceNanoseconds += produceNanoseconds
+        diagnosticNetworkNanoseconds += networkNanoseconds
+
+        let now = DispatchTime.now().uptimeNanoseconds
+        guard now - diagnosticStartedAt >= 500_000_000, let quicConnection else { return }
+        var stats = quiche_stats()
+        quiche_conn_stats(quicConnection, &stats)
+        var path = quiche_path_stats()
+        let pathResult = quiche_conn_path_stats(quicConnection, 0, &path)
+        let elapsedMilliseconds = Double(now - diagnosticStartedAt) / 1_000_000
+        let averagePacingMicroseconds = diagnosticFuturePacingPackets == 0 ? 0 :
+            Double(diagnosticFuturePacingNanoseconds) / Double(diagnosticFuturePacingPackets) / 1_000
+        let message = String(format:
+            "GHOSTFILE_H3_DIAG role=%@ interval_ms=%.1f payload=%d batches=%d batch_packets=%d produce_ms=%.3f nw_wait_ms=%.3f datagrams=%d datagram_bytes=%d next_calls=%d send_done=%d pump_calls=%d stream_visits=%d body_attempts=%d body_blocked=%d body_accepted=%d pacing_future=%d pacing_avg_us=%.1f pacing_max_us=%.1f quic_sent=%zu quic_lost=%zu quic_retrans=%zu quic_lost_bytes=%llu flow_blocked=%llu stream_blocked=%llu path_ok=%d rtt_us=%.1f cwnd=%zu delivery_Bps=%llu pmtu=%zu",
+            diagnosticRole,
+            elapsedMilliseconds,
+            Self.maximumUDPPayloadSize,
+            diagnosticBatches,
+            diagnosticBatchPackets,
+            Double(diagnosticProduceNanoseconds) / 1_000_000,
+            Double(diagnosticNetworkNanoseconds) / 1_000_000,
+            diagnosticDatagrams,
+            diagnosticDatagramBytes,
+            diagnosticNextDatagramCalls,
+            diagnosticSendDone,
+            diagnosticPumpCalls,
+            diagnosticStreamVisits,
+            diagnosticBodyAttempts,
+            diagnosticBodyBlocked,
+            diagnosticBodyAcceptedBytes,
+            diagnosticFuturePacingPackets,
+            averagePacingMicroseconds,
+            Double(diagnosticMaximumPacingNanoseconds) / 1_000,
+            stats.sent,
+            stats.lost,
+            stats.retrans,
+            stats.lost_bytes,
+            stats.data_blocked_sent_count,
+            stats.stream_data_blocked_sent_count,
+            pathResult,
+            Double(path.rtt) / 1_000,
+            path.cwnd,
+            path.delivery_rate,
+            path.pmtu
+        )
+        NSLog("%@", message)
+        diagnosticStartedAt = now
+        diagnosticPumpCalls = 0
+        diagnosticStreamVisits = 0
+        diagnosticBodyAttempts = 0
+        diagnosticBodyBlocked = 0
+        diagnosticBodyAcceptedBytes = 0
+        diagnosticNextDatagramCalls = 0
+        diagnosticDatagrams = 0
+        diagnosticDatagramBytes = 0
+        diagnosticSendDone = 0
+        diagnosticFuturePacingPackets = 0
+        diagnosticFuturePacingNanoseconds = 0
+        diagnosticMaximumPacingNanoseconds = 0
+        diagnosticBatches = 0
+        diagnosticBatchPackets = 0
+        diagnosticProduceNanoseconds = 0
+        diagnosticNetworkNanoseconds = 0
+    }
+
+    func peerCertificateDER() -> Data? {
+        guard let quicConnection else { return nil }
+        var pointer: UnsafePointer?
+        var length = 0
+        quiche_conn_peer_cert(quicConnection, &pointer, &length)
+        guard let pointer, length > 0 else { return nil }
+        return Data(bytes: pointer, count: length)
+    }
+
+    func sendRequest(headers: [(String, String)], body: Data = Data()) throws -> UInt64 {
+        try createHTTP3ConnectionIfReady()
+        guard let quicConnection, let http3Connection else {
+            throw ConnectionError.http3("The HTTP/3 handshake is not complete")
+        }
+        let managedHeaders = ManagedHTTP3Headers(headers)
+        let streamID = managedHeaders.withUnsafeHeaders { headers, count in
+            quiche_h3_send_request(http3Connection, quicConnection, headers, count, body.isEmpty)
+        }
+        guard streamID >= 0 else {
+            throw ConnectionError.http3("Unable to open an HTTP/3 request stream (\(streamID))")
+        }
+        if !body.isEmpty {
+            let requestStreamID = UInt64(streamID)
+            pendingRequestBodies[requestStreamID] = PendingHTTP3RequestBody(data: body)
+            try pumpRequestBodies()
+        }
+        return UInt64(streamID)
+    }
+
+    func cancelRequest(streamID: UInt64, errorCode: UInt64 = 0x010c) {
+        pendingRequestBodies.removeValue(forKey: streamID)
+        guard let quicConnection else { return }
+        _ = quiche_conn_stream_shutdown(
+            quicConnection,
+            streamID,
+            QUICHE_SHUTDOWN_READ,
+            errorCode
+        )
+        _ = quiche_conn_stream_shutdown(
+            quicConnection,
+            streamID,
+            QUICHE_SHUTDOWN_WRITE,
+            errorCode
+        )
+    }
+
+    func sendResponse(streamID: UInt64, headers: [(String, String)], body: Data) throws {
+        try beginResponse(streamID: streamID, headers: headers, contentLength: body.count)
+        guard !body.isEmpty else { return }
+        try appendResponseBody(streamID: streamID, data: body, isFinal: true)
+    }
+
+    func beginResponse(streamID: UInt64, headers: [(String, String)], contentLength: Int) throws {
+        guard quicConnection != nil, http3Connection != nil else {
+            throw ConnectionError.http3("The HTTP/3 connection is not ready")
+        }
+        guard contentLength >= 0, pendingResponses[streamID] == nil else {
+            throw ConnectionError.http3("Invalid or duplicate HTTP/3 response")
+        }
+        pendingResponses[streamID] = PendingHTTP3Response(
+            headers: headers,
+            expectedBodyLength: contentLength
+        )
+        try pumpResponses()
+    }
+
+    func appendResponseBody(streamID: UInt64, data: Data, isFinal: Bool) throws {
+        guard var pending = pendingResponses[streamID] else {
+            throw ConnectionError.http3("No pending HTTP/3 response for stream \(streamID)")
+        }
+        guard !pending.inputFinished,
+              pending.receivedBodyLength <= pending.expectedBodyLength - data.count else {
+            throw ConnectionError.http3("HTTP/3 response body exceeded its declared length")
+        }
+        pending.append(data)
+        if isFinal {
+            guard pending.receivedBodyLength == pending.expectedBodyLength else {
+                throw ConnectionError.http3("Incomplete HTTP/3 response body")
+            }
+            pending.inputFinished = true
+        }
+        pendingResponses[streamID] = pending
+        try pumpResponses()
+    }
+
+    func abandonResponse(streamID: UInt64) {
+        pendingResponses.removeValue(forKey: streamID)
+    }
+
+    func resetResponse(streamID: UInt64, errorCode: UInt64 = 0x010c) {
+        pendingResponses.removeValue(forKey: streamID)
+        guard let quicConnection else { return }
+        _ = quiche_conn_stream_shutdown(
+            quicConnection,
+            streamID,
+            QUICHE_SHUTDOWN_WRITE,
+            errorCode
+        )
+    }
+
+    func takePeerTerminatedResponseStreamIDs() -> [UInt64] {
+        defer { peerTerminatedResponseStreamIDs.removeAll(keepingCapacity: true) }
+        return peerTerminatedResponseStreamIDs
+    }
+
+    func takeFailedResponseStreamIDs() -> [UInt64] {
+        defer { failedResponseStreamIDs.removeAll(keepingCapacity: true) }
+        return failedResponseStreamIDs
+    }
+
+    func peerStoppedReceivingResponse(streamID: UInt64) -> Bool {
+        guard let quicConnection else { return false }
+        return quiche_conn_stream_capacity(quicConnection, streamID) ==
+            Int(QUICHE_ERR_STREAM_STOPPED.rawValue)
+    }
+
+    func pollEvent() throws -> Event? {
+        if let currentEvent {
+            quiche_h3_event_free(currentEvent)
+            self.currentEvent = nil
+        }
+        guard let quicConnection, let http3Connection else { return nil }
+        var event: OpaquePointer?
+        let streamID = quiche_h3_conn_poll(http3Connection, quicConnection, &event)
+        if streamID == Int64(QUICHE_H3_ERR_DONE.rawValue) { return nil }
+        guard streamID >= 0, let event else {
+            throw ConnectionError.http3("Unable to poll HTTP/3 events (\(streamID))")
+        }
+        currentEvent = event
+        switch quiche_h3_event_type(event) {
+        case QUICHE_H3_EVENT_HEADERS:
+            let box = HeaderCollectionBox()
+            let context = Unmanaged.passUnretained(box).toOpaque()
+            guard quiche_h3_event_for_each_header(event, ghostFileHTTP3CollectHeader, context) == 0 else {
+                throw ConnectionError.http3("Received malformed HTTP/3 headers")
+            }
+            return .headers(
+                streamID: UInt64(streamID),
+                fields: box.fields,
+                hasBody: quiche_h3_event_headers_has_more_frames(event)
+            )
+        case QUICHE_H3_EVENT_DATA:
+            return .data(streamID: UInt64(streamID))
+        case QUICHE_H3_EVENT_FINISHED:
+            return .finished(streamID: UInt64(streamID))
+        case QUICHE_H3_EVENT_RESET:
+            return .reset(streamID: UInt64(streamID))
+        default:
+            return nil
+        }
+    }
+
+    func receiveBody(streamID: UInt64, into destination: inout Data) throws {
+        try drainReceivedBody(streamID: streamID) { bytes in
+            guard let baseAddress = bytes.baseAddress, !bytes.isEmpty else { return }
+            destination.append(baseAddress.assumingMemoryBound(to: UInt8.self), count: bytes.count)
+        }
+    }
+
+    func discardReceivedBody(streamID: UInt64) throws {
+        try drainReceivedBody(streamID: streamID) { _ in }
+    }
+
+    private func drainReceivedBody(
+        streamID: UInt64,
+        consume: (UnsafeRawBufferPointer) -> Void
+    ) throws {
+        guard let quicConnection, let http3Connection else { return }
+        while true {
+            let count = receiveScratchBuffer.withUnsafeMutableBytes { bytes -> Int in
+                let count = Int(quiche_h3_recv_body(
+                    http3Connection,
+                    quicConnection,
+                    streamID,
+                    bytes.bindMemory(to: UInt8.self).baseAddress,
+                    bytes.count
+                ))
+                if count > 0 {
+                    consume(UnsafeRawBufferPointer(start: bytes.baseAddress, count: count))
+                }
+                return count
+            }
+            if count == Int(QUICHE_H3_ERR_DONE.rawValue) { break }
+            guard count >= 0 else {
+                throw ConnectionError.http3("Unable to receive an HTTP/3 body (\(count))")
+            }
+        }
+    }
+
+    private func acceptInitial(_ datagram: Data) throws {
+        guard case .server = role else { return }
+        var version: UInt32 = 0
+        var packetType: UInt8 = 0
+        var sourceID = [UInt8](repeating: 0, count: Int(QUICHE_MAX_CONN_ID_LEN))
+        var destinationID = [UInt8](repeating: 0, count: Int(QUICHE_MAX_CONN_ID_LEN))
+        var token = [UInt8](repeating: 0, count: 256)
+        var sourceIDLength = sourceID.count
+        var destinationIDLength = destinationID.count
+        var tokenLength = token.count
+        let parsed = datagram.withUnsafeBytes { datagramBytes in
+            sourceID.withUnsafeMutableBufferPointer { sourceID in
+                destinationID.withUnsafeMutableBufferPointer { destinationID in
+                    token.withUnsafeMutableBufferPointer { token in
+                        quiche_header_info(
+                            datagramBytes.bindMemory(to: UInt8.self).baseAddress,
+                            datagramBytes.count,
+                            16,
+                            &version,
+                            &packetType,
+                            sourceID.baseAddress,
+                            &sourceIDLength,
+                            destinationID.baseAddress,
+                            &destinationIDLength,
+                            token.baseAddress,
+                            &tokenLength
+                        )
+                    }
+                }
+            }
+        }
+        guard parsed == 0, quiche_version_is_supported(version) else {
+            throw ConnectionError.connection("Received an unsupported QUIC Initial packet")
+        }
+        var serverID = [UInt8](repeating: 0, count: 16)
+        arc4random_buf(&serverID, serverID.count)
+        quicConnection = withAddresses { local, localLength, peer, peerLength in
+            serverID.withUnsafeBufferPointer { serverID in
+                destinationID.withUnsafeBufferPointer { destinationID in
+                    quiche_accept(
+                        serverID.baseAddress,
+                        serverID.count,
+                        destinationID.baseAddress,
+                        destinationIDLength,
+                        local,
+                        localLength,
+                        peer,
+                        peerLength,
+                        quicConfiguration
+                    )
+                }
+            }
+        }
+    }
+
+    private func createHTTP3ConnectionIfReady() throws {
+        guard http3Connection == nil,
+              let quicConnection,
+              quiche_conn_is_established(quicConnection) else { return }
+        guard let connection = quiche_h3_conn_new_with_transport(quicConnection, http3Configuration) else {
+            throw ConnectionError.http3("Unable to create the HTTP/3 connection")
+        }
+        http3Connection = connection
+    }
+
+    private func pumpResponseBodies() throws {
+        try pumpRequestBodies()
+        try pumpResponses()
+    }
+
+    private func pumpRequestBodies() throws {
+        guard let quicConnection, let http3Connection, !pendingRequestBodies.isEmpty else { return }
+        for streamID in Array(pendingRequestBodies.keys) {
+            guard var pending = pendingRequestBodies[streamID] else { continue }
+            while pending.offset < pending.data.count {
+                let offeredLength = min(16 * 1024, pending.data.count - pending.offset)
+                let isFinal = pending.offset + offeredLength == pending.data.count
+                let sent = pending.data.withUnsafeBytes { bytes -> Int in
+                    let base = bytes.bindMemory(to: UInt8.self).baseAddress?.advanced(by: pending.offset)
+                    return Int(quiche_h3_send_body(
+                        http3Connection,
+                        quicConnection,
+                        streamID,
+                        base,
+                        offeredLength,
+                        isFinal
+                    ))
+                }
+                if sent == Int(QUICHE_H3_ERR_DONE.rawValue) ||
+                    sent == Int(QUICHE_H3_ERR_STREAM_BLOCKED.rawValue) {
+                    break
+                }
+                if Self.isPeerTerminatedStreamError(sent) {
+                    pendingRequestBodies.removeValue(forKey: streamID)
+                    break
+                }
+                guard sent > 0 else {
+                    pendingRequestBodies.removeValue(forKey: streamID)
+                    throw ConnectionError.http3(
+                        "Unable to continue HTTP/3 request body for stream \(streamID) (\(sent))"
+                    )
+                }
+                pending.offset += sent
+            }
+            if pendingRequestBodies[streamID] == nil { continue }
+            if pending.offset == pending.data.count {
+                pendingRequestBodies.removeValue(forKey: streamID)
+            } else {
+                pendingRequestBodies[streamID] = pending
+            }
+        }
+    }
+
+    private func pumpResponses() throws {
+        guard let quicConnection, let http3Connection, !pendingResponses.isEmpty else { return }
+        if Self.diagnosticsEnabled { diagnosticPumpCalls += 1 }
+        for streamID in Array(pendingResponses.keys) {
+            if Self.diagnosticsEnabled { diagnosticStreamVisits += 1 }
+            guard var pending = pendingResponses[streamID] else { continue }
+            if !pending.headersSent {
+                let managedHeaders = ManagedHTTP3Headers(pending.headers)
+                let result = managedHeaders.withUnsafeHeaders { headers, count in
+                    quiche_h3_send_response(
+                        http3Connection,
+                        quicConnection,
+                        streamID,
+                        headers,
+                        count,
+                        pending.expectedBodyLength == 0
+                    )
+                }
+                if result == Int32(QUICHE_H3_ERR_STREAM_BLOCKED.rawValue) ||
+                    result == Int32(QUICHE_H3_ERR_DONE.rawValue) {
+                    pendingResponses[streamID] = pending
+                    continue
+                }
+                if Self.isPeerTerminatedStreamError(Int(result)) {
+                    pendingResponses.removeValue(forKey: streamID)
+                    peerTerminatedResponseStreamIDs.append(streamID)
+                    continue
+                }
+                guard result == 0 else {
+                    pendingResponses.removeValue(forKey: streamID)
+                    failedResponseStreamIDs.append(streamID)
+                    continue
+                }
+                pending.headersSent = true
+                if pending.expectedBodyLength == 0 {
+                    pendingResponses.removeValue(forKey: streamID)
+                    continue
+                }
+            }
+            while let chunk = pending.currentChunk {
+                let offeredLength = min(16 * 1024, chunk.count - pending.chunkOffset)
+                let isFinal = pending.inputFinished &&
+                    pending.sentBodyLength + offeredLength == pending.expectedBodyLength
+                let sent = chunk.withUnsafeBytes { bytes -> Int in
+                    let base = bytes.bindMemory(to: UInt8.self).baseAddress?.advanced(by: pending.chunkOffset)
+                    return Int(quiche_h3_send_body(
+                        http3Connection,
+                        quicConnection,
+                        streamID,
+                        base,
+                        offeredLength,
+                        isFinal
+                    ))
+                }
+                if Self.diagnosticsEnabled {
+                    diagnosticBodyAttempts += 1
+                    if sent == Int(QUICHE_H3_ERR_DONE.rawValue) ||
+                        sent == Int(QUICHE_H3_ERR_STREAM_BLOCKED.rawValue) {
+                        diagnosticBodyBlocked += 1
+                    } else if sent > 0 {
+                        diagnosticBodyAcceptedBytes += sent
+                    }
+                }
+                if sent == Int(QUICHE_H3_ERR_DONE.rawValue) ||
+                    sent == Int(QUICHE_H3_ERR_STREAM_BLOCKED.rawValue) { break }
+                if Self.isPeerTerminatedStreamError(sent) {
+                    pendingResponses.removeValue(forKey: streamID)
+                    peerTerminatedResponseStreamIDs.append(streamID)
+                    break
+                }
+                guard sent > 0 else {
+                    pendingResponses.removeValue(forKey: streamID)
+                    failedResponseStreamIDs.append(streamID)
+                    break
+                }
+                pending.consume(sent)
+            }
+            if pendingResponses[streamID] == nil {
+                continue
+            } else if pending.inputFinished && pending.sentBodyLength == pending.expectedBodyLength {
+                pendingResponses.removeValue(forKey: streamID)
+            } else {
+                pendingResponses[streamID] = pending
+            }
+        }
+    }
+
+    private static func isPeerTerminatedStreamError(_ value: Int) -> Bool {
+        value == Int(QUICHE_H3_ERR_REQUEST_CANCELLED.rawValue) ||
+            value == Int(QUICHE_H3_TRANSPORT_ERR_STREAM_STOPPED.rawValue) ||
+            value == Int(QUICHE_H3_TRANSPORT_ERR_STREAM_RESET.rawValue) ||
+            value == Int(QUICHE_H3_TRANSPORT_ERR_INVALID_STREAM_STATE.rawValue) ||
+            value == Int(QUICHE_H3_TRANSPORT_ERR_FINAL_SIZE.rawValue)
+    }
+
+    private func withAddresses(
+        _ body: (UnsafePointer, socklen_t, UnsafePointer, socklen_t) throws -> T
+    ) rethrows -> T {
+        try withUnsafePointer(to: &localAddress) { local in
+            try withUnsafePointer(to: &peerAddress) { peer in
+                try local.withMemoryRebound(to: sockaddr.self, capacity: 1) { local in
+                    try peer.withMemoryRebound(to: sockaddr.self, capacity: 1) { peer in
+                        try body(local, socklen_t(MemoryLayout.size), peer, socklen_t(MemoryLayout.size))
+                    }
+                }
+            }
+        }
+    }
+
+    private static func fillAddress(_ address: inout sockaddr_in, port: UInt16) {
+        address = sockaddr_in()
+        address.sin_len = UInt8(MemoryLayout.size)
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = port.bigEndian
+        address.sin_addr = in_addr(s_addr: INADDR_LOOPBACK.bigEndian)
+    }
+}
+
+struct GhostFileScheduledDatagram: Sendable {
+    let data: Data
+    let sendAtNanoseconds: UInt64
+}
+
+func ghostFileMonotonicNanoseconds() -> UInt64 {
+    var now = timespec()
+    clock_gettime(CLOCK_MONOTONIC, &now)
+    return UInt64(now.tv_sec) * 1_000_000_000 + UInt64(now.tv_nsec)
+}
+
+private struct PendingHTTP3Response {
+    let headers: [(String, String)]
+    let expectedBodyLength: Int
+    var headersSent = false
+    var chunks: [Data] = []
+    var chunkIndex = 0
+    var chunkOffset = 0
+    var receivedBodyLength = 0
+    var sentBodyLength = 0
+    var inputFinished: Bool
+
+    init(headers: [(String, String)], expectedBodyLength: Int) {
+        self.headers = headers
+        self.expectedBodyLength = expectedBodyLength
+        self.inputFinished = expectedBodyLength == 0
+    }
+
+    var currentChunk: Data? {
+        chunkIndex < chunks.count ? chunks[chunkIndex] : nil
+    }
+
+    mutating func append(_ data: Data) {
+        guard !data.isEmpty else { return }
+        chunks.append(data)
+        receivedBodyLength += data.count
+    }
+
+    mutating func consume(_ count: Int) {
+        chunkOffset += count
+        sentBodyLength += count
+        guard let chunk = currentChunk, chunkOffset == chunk.count else { return }
+        chunkIndex += 1
+        chunkOffset = 0
+        if chunkIndex >= 8, chunkIndex * 2 >= chunks.count {
+            chunks.removeFirst(chunkIndex)
+            chunkIndex = 0
+        }
+    }
+}
+
+private struct PendingHTTP3RequestBody {
+    let data: Data
+    var offset = 0
+}
+
+private final class HeaderCollectionBox {
+    var fields: [(String, String)] = []
+}
+
+private func ghostFileHTTP3CollectHeader(
+    _ name: UnsafeMutablePointer?,
+    _ nameLength: Int,
+    _ value: UnsafeMutablePointer?,
+    _ valueLength: Int,
+    _ context: UnsafeMutableRawPointer?
+) -> Int32 {
+    guard let name, let value, let context,
+          let headerName = String(bytes: UnsafeBufferPointer(start: name, count: nameLength), encoding: .utf8),
+          let headerValue = String(bytes: UnsafeBufferPointer(start: value, count: valueLength), encoding: .utf8) else {
+        return -1
+    }
+    Unmanaged.fromOpaque(context).takeUnretainedValue().fields.append((headerName, headerValue))
+    return 0
+}
+
+private final class ManagedHTTP3Headers {
+    private var names: [UnsafeMutablePointer] = []
+    private var values: [UnsafeMutablePointer] = []
+    private var headers: [quiche_h3_header] = []
+
+    init(_ fields: [(String, String)]) {
+        names.reserveCapacity(fields.count)
+        values.reserveCapacity(fields.count)
+        headers.reserveCapacity(fields.count)
+        for (name, value) in fields {
+            let nameBytes = Array(name.utf8)
+            let valueBytes = Array(value.utf8)
+            let namePointer = UnsafeMutablePointer.allocate(capacity: max(1, nameBytes.count))
+            let valuePointer = UnsafeMutablePointer.allocate(capacity: max(1, valueBytes.count))
+            if !nameBytes.isEmpty { namePointer.initialize(from: nameBytes, count: nameBytes.count) }
+            if !valueBytes.isEmpty { valuePointer.initialize(from: valueBytes, count: valueBytes.count) }
+            names.append(namePointer)
+            values.append(valuePointer)
+            headers.append(quiche_h3_header(
+                name: UnsafePointer(namePointer),
+                name_len: nameBytes.count,
+                value: UnsafePointer(valuePointer),
+                value_len: valueBytes.count
+            ))
+        }
+    }
+
+    deinit {
+        for pointer in names { pointer.deallocate() }
+        for pointer in values { pointer.deallocate() }
+    }
+
+    func withUnsafeHeaders(_ body: (UnsafePointer?, Int) -> T) -> T {
+        headers.withUnsafeBufferPointer { body($0.baseAddress, $0.count) }
+    }
+}
+
+enum GhostFileNetworkDatagram {
+    // Amortize Network.framework callback and actor-hop overhead while keeping
+    // both the send queue and the receive window explicitly bounded.
+    static let maximumSendBatchCount: Int = {
+        guard let rawValue = ProcessInfo.processInfo.environment["GHOSTFILE_HTTP3_SEND_BATCH_COUNT"],
+              let value = Int(rawValue), (1...1_024).contains(value) else {
+            // Sixteen packets keeps Network.framework submissions bounded
+            // without sacrificing loopback throughput. The former 64-packet
+            // default produced avoidable ~86 KiB UDP bursts on real links.
+            return 16
+        }
+        return value
+    }()
+    static let maximumReceiveCount = 64
+}
+
+extension NWConnection {
+    func sendGhostFileDatagrams(_ datagrams: [Data]) async throws {
+        guard !datagrams.isEmpty else { return }
+
+        try await withCheckedThrowingContinuation { continuation in
+            let completion = GhostFileDatagramBatchCompletion(
+                count: datagrams.count,
+                continuation: continuation
+            )
+            batch {
+                for datagram in datagrams {
+                    send(content: datagram, completion: .contentProcessed { error in
+                        completion.completed(error: error)
+                    })
+                }
+            }
+        }
+    }
+}
+
+private final class GhostFileDatagramBatchCompletion: @unchecked Sendable {
+    private let lock = NSLock()
+    private var remaining: Int
+    private var continuation: CheckedContinuation?
+
+    init(count: Int, continuation: CheckedContinuation) {
+        remaining = count
+        self.continuation = continuation
+    }
+
+    func completed(error: NWError?) {
+        var continuationToResume: CheckedContinuation?
+        var completionError: Error?
+        lock.lock()
+        remaining -= 1
+        if let error, continuation != nil {
+            continuationToResume = continuation
+            continuation = nil
+            completionError = error
+        } else if remaining == 0, continuation != nil {
+            continuationToResume = continuation
+            continuation = nil
+        }
+        lock.unlock()
+
+        guard let continuationToResume else { return }
+        if let completionError {
+            continuationToResume.resume(throwing: completionError)
+        } else {
+            continuationToResume.resume()
+        }
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileHTTP3ShareServer.swift b/macOS/GhostFileKit/GhostFileHTTP3ShareServer.swift
new file mode 100644
index 0000000..f6c8e9c
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileHTTP3ShareServer.swift
@@ -0,0 +1,1408 @@
+import Darwin
+import Combine
+import Dispatch
+import Foundation
+import GhostHTTP
+#if !GHOSTFILEKIT_BUILD
+import GhostFileKit
+#endif
+import Network
+import OSLog
+
+private let ghostFileHTTP3ServerLogger = Logger(
+    subsystem: "org.ghostvm.ghostfile",
+    category: "HTTP3Server"
+)
+
+private let ghostFileServerProcessLogIdentity: String = {
+    let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "unknown"
+    let build = Bundle.main.object(forInfoDictionaryKey: "CFBundleVersion") as? String ?? "unknown"
+    return "version=\(version) build=\(build) pid=\(ProcessInfo.processInfo.processIdentifier)"
+}()
+
+private func ghostFileServerElapsedMilliseconds(since startedAt: UInt64) -> UInt64 {
+    let now = DispatchTime.now().uptimeNanoseconds
+    return now >= startedAt ? (now - startedAt) / 1_000_000 : 0
+}
+
+public enum GhostFileShareVisibility: Equatable, Sendable {
+    case localNetwork
+    case loopbackOnly
+}
+
+@MainActor
+public final class GhostFileShareServer: ObservableObject {
+    typealias RequestDelay = @Sendable (GhostFileHTTPRequest) async -> Void
+
+    @Published public private(set) var isRunning = false
+    @Published public private(set) var port: UInt16 = 0
+    @Published public private(set) var requestCount = 0
+
+    public let shareID: UUID
+    public let shareName: String
+    private let accessKey: String
+    private let provider: any GhostFileProvider
+    private let rootDescription: String
+    private var readOnly: Bool
+    private let tlsIdentity: GhostFileTLSIdentity?
+    private let visibility: GhostFileShareVisibility
+    private let advertisesBonjour: Bool
+
+    private let requestDelay: RequestDelay
+    private var publicKeyPin = ""
+    private var listener: NWListener?
+    private var portTask: Task?
+    private var heartbeatTask: Task?
+    private var stopTask: Task?
+    private var netService: NetService?
+    private var bonjourResolver: GhostFileBonjourSelfResolver?
+    @Published private var resolvedShareHost: String?
+    private var identityDirectory: URL?
+    private var sessions: [UUID: GhostFileHTTP3ServerSession] = [:]
+    private var router: GhostFileShareRouter?
+    private var bonjourValues: [String: String] = [:]
+    private var bonjourHeartbeat: UInt64 = 0
+    private var isStopping = false
+
+    public convenience init(
+        rootURL: URL,
+        shareName: String,
+        accessKey: String,
+        shareID: UUID = UUID(),
+        readOnly: Bool = true,
+        tlsIdentity: GhostFileTLSIdentity? = nil,
+        visibility: GhostFileShareVisibility = .localNetwork,
+        advertisesBonjour: Bool = true
+    ) {
+        self.init(
+            provider: LocalFolderProvider(rootURL: rootURL),
+            rootDescription: rootURL.path,
+            shareName: shareName,
+            accessKey: accessKey,
+            shareID: shareID,
+            readOnly: readOnly,
+            tlsIdentity: tlsIdentity,
+            visibility: visibility,
+            advertisesBonjour: advertisesBonjour,
+            requestDelay: { _ in }
+        )
+    }
+
+    public convenience init(
+        provider: any GhostFileProvider,
+        shareName: String,
+        accessKey: String,
+        shareID: UUID = UUID(),
+        readOnly: Bool = true,
+        tlsIdentity: GhostFileTLSIdentity? = nil,
+        visibility: GhostFileShareVisibility = .localNetwork,
+        advertisesBonjour: Bool = true
+    ) {
+        self.init(
+            provider: provider,
+            rootDescription: String(describing: type(of: provider)),
+            shareName: shareName,
+            accessKey: accessKey,
+            shareID: shareID,
+            readOnly: readOnly,
+            tlsIdentity: tlsIdentity,
+            visibility: visibility,
+            advertisesBonjour: advertisesBonjour,
+            requestDelay: { _ in }
+        )
+    }
+
+    init(
+        provider: any GhostFileProvider,
+        rootDescription: String,
+        shareName: String,
+        accessKey: String,
+        shareID: UUID,
+        readOnly: Bool,
+        tlsIdentity: GhostFileTLSIdentity?,
+        visibility: GhostFileShareVisibility,
+        advertisesBonjour: Bool,
+        requestDelay: @escaping RequestDelay
+    ) {
+        self.provider = provider
+        self.rootDescription = rootDescription
+        self.shareName = shareName
+        self.accessKey = accessKey
+        self.shareID = shareID
+        self.readOnly = readOnly
+        self.tlsIdentity = tlsIdentity
+        self.visibility = visibility
+        self.advertisesBonjour = advertisesBonjour
+        self.requestDelay = requestDelay
+    }
+
+    convenience init(
+        rootURL: URL,
+        shareName: String,
+        accessKey: String,
+        shareID: UUID = UUID(),
+        readOnly: Bool = true,
+        tlsIdentity: GhostFileTLSIdentity? = nil,
+        requestDelay: @escaping RequestDelay
+    ) {
+        self.init(
+            provider: LocalFolderProvider(rootURL: rootURL),
+            rootDescription: rootURL.path,
+            shareName: shareName,
+            accessKey: accessKey,
+            shareID: shareID,
+            readOnly: readOnly,
+            tlsIdentity: tlsIdentity,
+            visibility: .localNetwork,
+            advertisesBonjour: true,
+            requestDelay: requestDelay
+        )
+    }
+
+    public var shareURL: URL? {
+        guard port != 0, let host = resolvedShareHost else { return nil }
+        return resourceURL(host: host)
+    }
+
+#if DEBUG
+    var loopbackShareURLForTesting: URL? {
+        guard port != 0 else { return nil }
+        return resourceURL(host: "127.0.0.1")
+    }
+#endif
+
+    private func resourceURL(host: String) -> URL? {
+        var components = URLComponents()
+        components.scheme = GhostFileProtocol.urlScheme
+        components.host = host
+        components.port = Int(port)
+        components.path = GhostFileProtocol.shareBasePath(id: shareID)
+        components.queryItems = [URLQueryItem(
+            name: GhostFileProtocol.publicKeyPinQueryName,
+            value: publicKeyPin
+        )]
+        return components.url
+    }
+
+    public func start(preferredPort: UInt16 = 0) throws {
+        guard listener == nil else { return }
+        ghostFileHTTP3ServerLogger.notice(
+            "Share listener starting share=\(self.shareID.uuidString.lowercased(), privacy: .public) \(ghostFileServerProcessLogIdentity, privacy: .public) preferredPort=\(preferredPort, privacy: .public) name=\(self.shareName, privacy: .private(mask: .hash)) root=\(self.rootDescription, privacy: .private(mask: .hash))"
+        )
+        let router = GhostFileShareRouter(
+            provider: provider,
+            shareID: shareID,
+            shareName: shareName,
+            accessKey: accessKey,
+            readOnly: readOnly
+        )
+        self.router = router
+        let identity = try tlsIdentity ?? GhostFileTLSIdentity.make()
+        publicKeyPin = identity.publicKeyPin
+        let identityFiles = try Self.writeIdentityFiles(identity)
+
+        let txt: [String: String] = [
+            "version": String(GhostFileProtocol.version),
+            "id": shareID.uuidString.lowercased(),
+            "mode": readOnly ? "ro" : "rw",
+            "transport": GhostFileProtocol.transport,
+            "alpn": GhostFileProtocol.alpn,
+            "auth": "access-key",
+            "pk": publicKeyPin,
+            "state": "ready",
+            "ttl": String(Int(GhostFileBonjourLease.advertisedTTL)),
+        ]
+        bonjourValues = txt
+        let parameters = NWParameters.udp
+        parameters.allowLocalEndpointReuse = true
+        parameters.includePeerToPeer = true
+        let requestedPort = NWEndpoint.Port(rawValue: preferredPort) ?? .any
+        if visibility == .loopbackOnly {
+            parameters.requiredLocalEndpoint = .hostPort(host: "127.0.0.1", port: requestedPort)
+        }
+
+        do {
+            let listener = visibility == .loopbackOnly
+                ? try NWListener(using: parameters)
+                : try NWListener(using: parameters, on: requestedPort)
+            listener.stateUpdateHandler = { [weak self] state in
+                Task { @MainActor in self?.listenerStateChanged(state) }
+            }
+            listener.newConnectionHandler = { [weak self] connection in
+                Task { @MainActor in
+                    self?.accept(
+                        connection,
+                        router: router,
+                        certificatePath: identityFiles.certificate.path,
+                        privateKeyPath: identityFiles.privateKey.path
+                    )
+                }
+            }
+            self.identityDirectory = identityFiles.directory
+            self.listener = listener
+            listener.start(queue: DispatchQueue(label: "org.ghostvm.ghostfile.http3.listener"))
+            port = listener.port?.rawValue ?? 0
+            isRunning = port != 0
+            portTask = Task { [weak self, weak listener] in
+                for _ in 0..<500 {
+                    guard let self, let listener else { return }
+                    // NWListener can transiently report `.any` (raw value 0)
+                    // before the kernel assigns its real ephemeral port. Never
+                    // publish that placeholder: `publishBonjour` is one-shot,
+                    // so doing so would permanently advertise an unusable SRV
+                    // endpoint for this share instance.
+                    if let boundPort = listener.port?.rawValue, boundPort != 0 {
+                        self.port = boundPort
+                        self.isRunning = true
+                        if self.visibility == .loopbackOnly {
+                            self.resolvedShareHost = "127.0.0.1"
+                        }
+                        if self.advertisesBonjour {
+                            self.publishBonjour(port: boundPort, values: txt)
+                        }
+                        return
+                    }
+                    try? await Task.sleep(for: .milliseconds(10))
+                }
+            }
+        } catch {
+            try? FileManager.default.removeItem(at: identityFiles.directory)
+            throw error
+        }
+    }
+
+    public func stop() {
+        guard listener != nil else {
+            finishStop()
+            return
+        }
+        guard !isStopping else { return }
+        isStopping = true
+        ghostFileHTTP3ServerLogger.notice(
+            "Share stop requested share=\(self.shareID.uuidString.lowercased(), privacy: .public) port=\(self.port, privacy: .public) sessions=\(self.sessions.count, privacy: .public) requests=\(self.requestCount, privacy: .public)"
+        )
+        isRunning = false
+        heartbeatTask?.cancel()
+        heartbeatTask = nil
+
+        // Tell mount clients to detach before closing their backing transport.
+        // This prevents a forced unmount from waiting on an already-dead share.
+        if let netService {
+            var stoppingValues = bonjourValues
+            stoppingValues["state"] = "stopping"
+            let dataValues = stoppingValues.mapValues { Data($0.utf8) }
+            netService.setTXTRecord(NetService.data(fromTXTRecord: dataValues))
+            stopTask = Task { [self] in
+                try? await Task.sleep(for: .seconds(2))
+                guard !Task.isCancelled else { return }
+                finishStop()
+            }
+        } else {
+            finishStop()
+        }
+    }
+
+    public func setReadOnly(_ readOnly: Bool) {
+        self.readOnly = readOnly
+        router?.setReadOnly(readOnly)
+        bonjourValues["mode"] = readOnly ? "ro" : "rw"
+        if let netService {
+            let dataValues = bonjourValues.mapValues { Data($0.utf8) }
+            netService.setTXTRecord(NetService.data(fromTXTRecord: dataValues))
+        }
+    }
+
+    private func finishStop() {
+        ghostFileHTTP3ServerLogger.notice(
+            "Share stopping share=\(self.shareID.uuidString.lowercased(), privacy: .public) port=\(self.port, privacy: .public) sessions=\(self.sessions.count, privacy: .public) requests=\(self.requestCount, privacy: .public)"
+        )
+        stopTask?.cancel()
+        stopTask = nil
+        listener?.cancel()
+        listener = nil
+        netService?.stop()
+        netService = nil
+        bonjourResolver?.stop()
+        bonjourResolver = nil
+        resolvedShareHost = nil
+        portTask?.cancel()
+        portTask = nil
+        heartbeatTask?.cancel()
+        heartbeatTask = nil
+        for session in sessions.values { session.stop() }
+        sessions.removeAll()
+        router = nil
+        if let identityDirectory { try? FileManager.default.removeItem(at: identityDirectory) }
+        identityDirectory = nil
+        bonjourValues = [:]
+        bonjourHeartbeat = 0
+        port = 0
+        isRunning = false
+        isStopping = false
+    }
+
+    private func accept(
+        _ connection: NWConnection,
+        router: GhostFileShareRouter,
+        certificatePath: String,
+        privateKeyPath: String
+    ) {
+        let id = UUID()
+        let sessionID = String(id.uuidString.prefix(12)).lowercased()
+        do {
+            let session = try GhostFileHTTP3ServerSession(
+                sessionID: sessionID,
+                connection: connection,
+                certificatePath: certificatePath,
+                privateKeyPath: privateKeyPath,
+                router: router,
+                requestDelay: requestDelay,
+                requestCompleted: { [weak self] in
+                    Task { @MainActor in self?.requestCount += 1 }
+                },
+                stopped: { [weak self] in
+                    Task { @MainActor in self?.sessions.removeValue(forKey: id) }
+                }
+            )
+            sessions[id] = session
+            ghostFileHTTP3ServerLogger.notice(
+                "Session accepted share=\(self.shareID.uuidString.lowercased(), privacy: .public) session=\(sessionID, privacy: .public) endpoint=\(String(describing: connection.endpoint), privacy: .public) activeSessions=\(self.sessions.count, privacy: .public)"
+            )
+            session.start()
+        } catch {
+            ghostFileHTTP3ServerLogger.error(
+                "Session setup failed share=\(self.shareID.uuidString.lowercased(), privacy: .public) session=\(sessionID, privacy: .public) error=\(String(describing: error), privacy: .public)"
+            )
+            connection.cancel()
+        }
+    }
+
+    private func listenerStateChanged(_ state: NWListener.State) {
+        switch state {
+        case .ready:
+            port = listener?.port?.rawValue ?? 0
+            isRunning = port != 0
+            if port != 0 {
+                ghostFileHTTP3ServerLogger.notice(
+                    "Share listener ready share=\(self.shareID.uuidString.lowercased(), privacy: .public) port=\(self.port, privacy: .public)"
+                )
+                if visibility == .loopbackOnly {
+                    resolvedShareHost = "127.0.0.1"
+                }
+                if advertisesBonjour { publishBonjour(port: port, values: [
+                    "version": String(GhostFileProtocol.version),
+                    "id": shareID.uuidString.lowercased(),
+                    "mode": readOnly ? "ro" : "rw",
+                    "transport": GhostFileProtocol.transport,
+                    "alpn": GhostFileProtocol.alpn,
+                    "auth": "access-key",
+                    "pk": publicKeyPin,
+                    "state": "ready",
+                    "ttl": String(Int(GhostFileBonjourLease.advertisedTTL)),
+                ]) }
+            }
+        case .failed(let error):
+            ghostFileHTTP3ServerLogger.error(
+                "Share listener failed share=\(self.shareID.uuidString.lowercased(), privacy: .public) error=\(String(describing: error), privacy: .public)"
+            )
+            finishStop()
+        case .cancelled:
+            ghostFileHTTP3ServerLogger.notice(
+                "Share listener cancelled share=\(self.shareID.uuidString.lowercased(), privacy: .public)"
+            )
+            port = 0
+            isRunning = false
+        case .waiting(let error):
+            ghostFileHTTP3ServerLogger.notice(
+                "Share listener waiting share=\(self.shareID.uuidString.lowercased(), privacy: .public) error=\(String(describing: error), privacy: .public)"
+            )
+        case .setup:
+            break
+        @unknown default:
+            break
+        }
+    }
+
+    private func publishBonjour(port: UInt16, values: [String: String]) {
+        guard netService == nil else { return }
+        guard port != 0 else {
+            ghostFileHTTP3ServerLogger.error(
+                "Refusing Bonjour publication with zero port share=\(self.shareID.uuidString.lowercased(), privacy: .public)"
+            )
+            return
+        }
+        ghostFileHTTP3ServerLogger.notice(
+            "Bonjour publish starting share=\(self.shareID.uuidString.lowercased(), privacy: .public) port=\(port, privacy: .public) ttl=\(values["ttl"] ?? "unknown", privacy: .public)"
+        )
+        bonjourValues = values
+        bonjourHeartbeat = 0
+        let service = NetService(
+            domain: GhostFileProtocol.bonjourDomain,
+            type: GhostFileProtocol.bonjourType,
+            name: shareName,
+            port: Int32(port)
+        )
+        service.includesPeerToPeer = true
+        var initialValues = values
+        initialValues["heartbeat"] = String(bonjourHeartbeat)
+        let dataValues = initialValues.mapValues { Data($0.utf8) }
+        service.setTXTRecord(NetService.data(fromTXTRecord: dataValues))
+        netService = service
+        let resolver = GhostFileBonjourSelfResolver { [weak self, weak service] host in
+            Task { @MainActor in
+                guard let self, let service, self.netService === service else { return }
+                self.resolvedShareHost = host
+                ghostFileHTTP3ServerLogger.notice(
+                    "Bonjour self-resolution ready share=\(self.shareID.uuidString.lowercased(), privacy: .public) host=\(host, privacy: .public) port=\(self.port, privacy: .public)"
+                )
+            }
+        }
+        bonjourResolver = resolver
+        resolver.publish(service)
+        heartbeatTask = Task { [weak self, weak service] in
+            while !Task.isCancelled {
+                try? await Task.sleep(for: GhostFileBonjourLease.heartbeatInterval)
+                guard !Task.isCancelled, let self, let service else { return }
+                guard self.netService === service, self.isRunning, !self.isStopping else { return }
+                self.bonjourHeartbeat &+= 1
+                var heartbeatValues = self.bonjourValues
+                heartbeatValues["heartbeat"] = String(self.bonjourHeartbeat)
+                let dataValues = heartbeatValues.mapValues { Data($0.utf8) }
+                service.setTXTRecord(NetService.data(fromTXTRecord: dataValues))
+            }
+        }
+    }
+
+    private static func writeIdentityFiles(
+        _ identity: GhostFileTLSIdentity
+    ) throws -> (directory: URL, certificate: URL, privateKey: URL) {
+        let directory = FileManager.default.temporaryDirectory
+            .appendingPathComponent("GhostFileHTTP3-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(
+            at: directory,
+            withIntermediateDirectories: false,
+            attributes: [.posixPermissions: 0o700]
+        )
+        do {
+            let certificate = directory.appendingPathComponent("certificate.pem")
+            let privateKey = directory.appendingPathComponent("private-key.pem")
+            try Data(identity.certificatePEM.utf8).write(to: certificate, options: .atomic)
+            try Data(identity.privateKeyPEM.utf8).write(to: privateKey, options: .atomic)
+            try FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: certificate.path)
+            try FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: privateKey.path)
+            return (directory, certificate, privateKey)
+        } catch {
+            try? FileManager.default.removeItem(at: directory)
+            throw error
+        }
+    }
+
+}
+
+private actor GhostFileHTTP3ServerSession {
+    typealias RequestDelay = GhostFileShareServer.RequestDelay
+
+    private struct RequestLogContext {
+        let requestID: String
+        let operation: String
+        let startedAt: UInt64
+    }
+
+    private struct PendingInboundRequest {
+        let request: HTTPRequestHead
+        let context: GhostFileHTTPRequest
+        let logContext: RequestLogContext
+        let expectedLength: Int?
+        var body = Data()
+    }
+
+    private let sessionID: String
+    private let connection: NWConnection
+    private let http3: GhostFileHTTP3Connection
+    private let router: GhostFileShareRouter
+    private let requestDelay: RequestDelay
+    private let requestCompleted: @Sendable () -> Void
+    private let stopped: @Sendable () -> Void
+    private var timeoutTask: Task?
+    private var isFlushing = false
+    private var flushAgain = false
+    private var isStopping = false
+    private var hasStopped = false
+    private var routingTasks: [UInt64: Task] = [:]
+    private var responseTasks: [UInt64: Task] = [:]
+    private var requestLogs: [UInt64: RequestLogContext] = [:]
+    private var inboundRequests: [UInt64: PendingInboundRequest] = [:]
+    private var terminatedRequestStreams: Set = []
+    private var pendingReceivedDatagrams: [Data] = []
+    private var pendingScheduledDatagram: GhostFileScheduledDatagram?
+    private var isReceiveDrainScheduled = false
+    private let createdAt = DispatchTime.now().uptimeNanoseconds
+    private var didLogHandshake = false
+    private var receivedDatagramCount = 0
+    private var receivedByteCount = 0
+    private var sentDatagramCount = 0
+    private var sentByteCount = 0
+
+    // GhostFile range requests are capped at 1 MiB. One DispatchIO operation per
+    // bounded range avoids re-entering the connection actor for artificial file
+    // chunks while independent HTTP/3 streams still read concurrently.
+    private static let fileReadChunkSize = GhostFileProtocol.maximumReadLength
+    private static let maximumRequestBodyLength = GhostFileProtocol.maximumWriteLength
+
+    init(
+        sessionID: String,
+        connection: NWConnection,
+        certificatePath: String,
+        privateKeyPath: String,
+        router: GhostFileShareRouter,
+        requestDelay: @escaping RequestDelay,
+        requestCompleted: @escaping @Sendable () -> Void,
+        stopped: @escaping @Sendable () -> Void
+    ) throws {
+        self.sessionID = sessionID
+        self.connection = connection
+        self.http3 = try GhostFileHTTP3Connection(
+            role: .server(certificatePath: certificatePath, privateKeyPath: privateKeyPath)
+        )
+        self.router = router
+        self.requestDelay = requestDelay
+        self.requestCompleted = requestCompleted
+        self.stopped = stopped
+    }
+
+    nonisolated func start() {
+        Task { await startIsolated() }
+    }
+
+    nonisolated func stop() {
+        Task { await stopIsolated() }
+    }
+
+    private func startIsolated() {
+        ghostFileHTTP3ServerLogger.notice(
+            "Session starting session=\(self.sessionID, privacy: .public) endpoint=\(String(describing: self.connection.endpoint), privacy: .public)"
+        )
+        connection.stateUpdateHandler = { [weak self] state in
+            Task { await self?.connectionStateChanged(state) }
+        }
+        connection.start(queue: DispatchQueue(label: "org.ghostvm.ghostfile.http3.session"))
+        connection.batch {
+            for _ in 0.. 0 {
+                    var inbound = PendingInboundRequest(
+                        request: request,
+                        context: context,
+                        logContext: logContext,
+                        expectedLength: expectedLength
+                    )
+                    if let expectedLength { inbound.body.reserveCapacity(expectedLength) }
+                    inboundRequests[streamID] = inbound
+                } else {
+                    beginRouting(
+                        request,
+                        body: Data(),
+                        streamID: streamID,
+                        context: context,
+                        logContext: logContext
+                    )
+                }
+            case .data(let streamID):
+                guard var inbound = inboundRequests[streamID] else {
+                    try http3.discardReceivedBody(streamID: streamID)
+                    continue
+                }
+                try http3.receiveBody(streamID: streamID, into: &inbound.body)
+                guard inbound.body.count <= Self.maximumRequestBodyLength,
+                      inbound.expectedLength == nil || inbound.body.count <= inbound.expectedLength! else {
+                    inboundRequests.removeValue(forKey: streamID)
+                    Task { await self.sendBadRequest(streamID: streamID) }
+                    continue
+                }
+                inboundRequests[streamID] = inbound
+            case .reset(let streamID):
+                inboundRequests.removeValue(forKey: streamID)
+                terminatedRequestStreams.insert(streamID)
+                if let context = requestLogs.removeValue(forKey: streamID) {
+                    ghostFileHTTP3ServerLogger.error(
+                        "Request reset by client request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+                    )
+                }
+                cancelResponse(streamID: streamID)
+            case .finished(let streamID):
+                guard let inbound = inboundRequests.removeValue(forKey: streamID) else { continue }
+                guard inbound.expectedLength == nil || inbound.expectedLength == inbound.body.count else {
+                    Task { await self.sendBadRequest(streamID: streamID) }
+                    continue
+                }
+                beginRouting(
+                    inbound.request,
+                    body: inbound.body,
+                    streamID: streamID,
+                    context: inbound.context,
+                    logContext: inbound.logContext
+                )
+            }
+        }
+    }
+
+    private func beginRouting(
+        _ request: HTTPRequestHead,
+        body: Data,
+        streamID: UInt64,
+        context: GhostFileHTTPRequest,
+        logContext: RequestLogContext
+    ) {
+        let router = self.router
+        let delay = self.requestDelay
+        let requestID = logContext.requestID
+        let task = Task { [weak self] in
+            let started = ContinuousClock.now
+            await delay(context)
+            guard !Task.isCancelled else {
+                await self?.routingCancelled(streamID: streamID)
+                return
+            }
+            let response = await Self.route(request, body: body, using: router)
+            guard !Task.isCancelled else {
+                await self?.routingCancelled(streamID: streamID)
+                return
+            }
+            let elapsed = started.duration(to: .now)
+            ghostFileHTTP3ServerLogger.info(
+                "Request routed request=\(requestID, privacy: .public) session=\(self?.sessionID ?? "gone", privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) status=\(response.status.rawValue, privacy: .public) bytes=\(response.body.contentLength, privacy: .public) elapsed=\(String(describing: elapsed), privacy: .public)"
+            )
+            await self?.routingFinished(
+                response,
+                streamID: streamID,
+                context: logContext
+            )
+        }
+        routingTasks[streamID] = task
+    }
+
+    private func sendBadRequest(streamID: UInt64) async {
+        let body = Data("Malformed HTTP/3 request".utf8)
+        do {
+            try http3.sendResponse(
+                streamID: streamID,
+                headers: [(":status", "400"), ("content-length", String(body.count))],
+                body: body
+            )
+            await flushOutgoing()
+        } catch { await stopIsolated(reason: "badRequestSendFailed") }
+    }
+
+    private func send(
+        _ response: GhostFileHTTPResponse,
+        streamID: UInt64,
+        context: RequestLogContext
+    ) async {
+        guard !hasStopped else { return }
+        guard terminatedRequestStreams.remove(streamID) == nil else {
+            requestLogs.removeValue(forKey: streamID)
+            return
+        }
+        do {
+            var headers: [(String, String)] = [
+                (":status", String(response.status.rawValue)),
+                ("content-length", String(response.body.contentLength)),
+            ]
+            headers.append(contentsOf: response.headers.all.compactMap { entry in
+                let name = entry.name.lowercased()
+                guard name != "content-length", !name.hasPrefix(":") else { return nil }
+                return (name, entry.value)
+            })
+
+            let completesImmediately: Bool
+            switch response.body {
+            case .empty:
+                try http3.sendResponse(streamID: streamID, headers: headers, body: Data())
+                completesImmediately = true
+            case .bytes(let body):
+                try http3.sendResponse(streamID: streamID, headers: headers, body: body)
+                completesImmediately = true
+            case .fileRegion(let path, let identity, let offset, let length):
+                try http3.beginResponse(
+                    streamID: streamID,
+                    headers: headers,
+                    contentLength: length
+                )
+                startFileResponse(
+                    path: path,
+                    identity: identity,
+                    offset: offset,
+                    length: length,
+                    streamID: streamID
+                )
+                completesImmediately = false
+            }
+            ghostFileHTTP3ServerLogger.info(
+                "Response queued request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) status=\(response.status.rawValue, privacy: .public) bytes=\(response.body.contentLength, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+            )
+            if completesImmediately {
+                requestLogs.removeValue(forKey: streamID)
+                requestCompleted()
+            }
+            await flushOutgoing()
+        } catch {
+            ghostFileHTTP3ServerLogger.error(
+                "Response failed request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) error=\(String(describing: error), privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+            )
+            await stopIsolated(reason: "responseFailed")
+        }
+    }
+
+    private func flushOutgoing() async {
+        guard !hasStopped, !isStopping else { return }
+        if isFlushing {
+            flushAgain = true
+            return
+        }
+        isFlushing = true
+        defer { isFlushing = false }
+        do {
+            repeat {
+                flushAgain = false
+                while !isStopping {
+                    let produceStartedAt = DispatchTime.now().uptimeNanoseconds
+                    var datagrams: [Data] = []
+                    datagrams.reserveCapacity(GhostFileNetworkDatagram.maximumSendBatchCount)
+                    var transportDrained = false
+                    while datagrams.count < GhostFileNetworkDatagram.maximumSendBatchCount {
+                        let scheduled: GhostFileScheduledDatagram
+                        if let pendingScheduledDatagram {
+                            scheduled = pendingScheduledDatagram
+                        } else if let next = try http3.nextScheduledDatagram() {
+                            scheduled = next
+                        } else {
+                            transportDrained = true
+                            break
+                        }
+                        let now = ghostFileMonotonicNanoseconds()
+                        guard scheduled.sendAtNanoseconds <= now else {
+                            pendingScheduledDatagram = scheduled
+                            break
+                        }
+                        pendingScheduledDatagram = nil
+                        datagrams.append(scheduled.data)
+                        drainPeerTerminatedResponses()
+                    }
+                    drainPeerTerminatedResponses()
+                    if datagrams.isEmpty {
+                        if transportDrained { break }
+                        guard let pendingScheduledDatagram else { break }
+                        let now = ghostFileMonotonicNanoseconds()
+                        if pendingScheduledDatagram.sendAtNanoseconds > now {
+                            try await Task.sleep(
+                                nanoseconds: pendingScheduledDatagram.sendAtNanoseconds - now
+                            )
+                        }
+                        continue
+                    }
+                    let produceFinishedAt = DispatchTime.now().uptimeNanoseconds
+                    try await connection.sendGhostFileDatagrams(datagrams)
+                    let sendFinishedAt = DispatchTime.now().uptimeNanoseconds
+                    sentDatagramCount += datagrams.count
+                    sentByteCount += datagrams.reduce(into: 0) { $0 += $1.count }
+                    http3.recordSendBatch(
+                        packetCount: datagrams.count,
+                        produceNanoseconds: produceFinishedAt - produceStartedAt,
+                        networkNanoseconds: sendFinishedAt - produceFinishedAt
+                    )
+                }
+            } while flushAgain
+            resetTimeout()
+        } catch {
+            ghostFileHTTP3ServerLogger.error(
+                "Session UDP send failed session=\(self.sessionID, privacy: .public) error=\(String(describing: error), privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+            )
+            await stopIsolated(reason: "sendFailed")
+        }
+    }
+
+    private func resetTimeout() {
+        timeoutTask?.cancel()
+        guard let nanoseconds = http3.timeoutNanoseconds else { return }
+        timeoutTask = Task { [weak self] in
+            do {
+                try await Task.sleep(nanoseconds: max(1_000_000, nanoseconds))
+                guard !Task.isCancelled else { return }
+                await self?.timeoutFired()
+            } catch {}
+        }
+    }
+
+    private func timeoutFired() async {
+        http3.handleTimeout()
+        await flushOutgoing()
+        if http3.isClosed {
+            ghostFileHTTP3ServerLogger.error(
+                "Session QUIC timeout closed connection session=\(self.sessionID, privacy: .public) activeRequests=\(self.requestLogs.count, privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+            )
+            await stopIsolated(reason: "quicTimeoutClosed")
+        }
+    }
+
+    private func connectionStateChanged(_ state: NWConnection.State) async {
+        switch state {
+        case .ready:
+            ghostFileHTTP3ServerLogger.notice(
+                "Session UDP ready session=\(self.sessionID, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+            )
+        case .waiting(let error):
+            ghostFileHTTP3ServerLogger.notice(
+                "Session UDP waiting session=\(self.sessionID, privacy: .public) error=\(String(describing: error), privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+            )
+        case .failed(let error):
+            ghostFileHTTP3ServerLogger.error(
+                "Session UDP failed session=\(self.sessionID, privacy: .public) error=\(String(describing: error), privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+            )
+            await stopIsolated(reason: "networkFailed")
+        case .cancelled:
+            await stopIsolated(reason: "networkCancelled")
+        default:
+            break
+        }
+    }
+
+    private func stopIsolated(reason: String = "requested") async {
+        guard !hasStopped, !isStopping else { return }
+        isStopping = true
+        ghostFileHTTP3ServerLogger.notice(
+            "Session stopping session=\(self.sessionID, privacy: .public) reason=\(reason, privacy: .public) activeRequests=\(self.requestLogs.count, privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) receivedBytes=\(self.receivedByteCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) sentBytes=\(self.sentByteCount, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+        )
+        timeoutTask?.cancel()
+        for task in routingTasks.values { task.cancel() }
+        routingTasks.removeAll()
+        for task in responseTasks.values { task.cancel() }
+        responseTasks.removeAll()
+        requestLogs.removeAll()
+        inboundRequests.removeAll()
+        pendingScheduledDatagram = nil
+        while isFlushing {
+            await Task.yield()
+        }
+        let applicationErrorCode = reason == "requested"
+            ? GhostFileHTTP3Connection.h3NoError
+            : GhostFileHTTP3Connection.h3InternalError
+        await sendConnectionClose(reason: reason, applicationErrorCode: applicationErrorCode)
+        hasStopped = true
+        connection.cancel()
+        stopped()
+    }
+
+    private func sendConnectionClose(reason: String, applicationErrorCode: UInt64) async {
+        do {
+            try http3.close(applicationErrorCode: applicationErrorCode, reason: reason)
+            while let datagram = try http3.nextScheduledDatagram() {
+                let now = ghostFileMonotonicNanoseconds()
+                if datagram.sendAtNanoseconds > now {
+                    try await Task.sleep(nanoseconds: datagram.sendAtNanoseconds - now)
+                }
+                try await connection.sendGhostFileDatagrams([datagram.data])
+                sentDatagramCount += 1
+                sentByteCount += datagram.data.count
+            }
+        } catch {
+            ghostFileHTTP3ServerLogger.error(
+                "Session close notification failed session=\(self.sessionID, privacy: .public) reason=\(reason, privacy: .public) error=\(String(describing: error), privacy: .public)"
+            )
+        }
+    }
+
+    private nonisolated static func httpRequest(fields: [(String, String)]) -> HTTPRequestHead? {
+        guard let methodValue = fields.first(where: { $0.0 == ":method" })?.1,
+              let method = HTTPMethod(rawValue: methodValue),
+              let path = fields.first(where: { $0.0 == ":path" })?.1,
+              fields.first(where: { $0.0 == ":scheme" })?.1 == "https" else {
+            return nil
+        }
+        let headers = HTTPHeaders(fields.compactMap { name, value in
+            guard !name.hasPrefix(":") else { return nil }
+            return HTTPHeaders.Entry(name: name, value: value)
+        })
+        return HTTPRequestHead(method: method, path: path, headers: headers)
+    }
+
+    private nonisolated static func requestContext(_ request: HTTPRequestHead) -> GhostFileHTTPRequest? {
+        guard let components = URLComponents(string: "https://ghostfile.local\(request.path)") else { return nil }
+        let operation = components.path.split(separator: "/").last.map(String.init) ?? ""
+        let path = components.queryItems?.first(where: { $0.name == "path" })?.value
+        var offset: UInt64?
+        var length: Int?
+        if let range = request.header("range"), range.hasPrefix("bytes=") {
+            let pieces = range.dropFirst(6).split(separator: "-", maxSplits: 1)
+            if pieces.count == 2, let start = UInt64(pieces[0]), let end = UInt64(pieces[1]), end >= start {
+                offset = start
+                length = Int(end - start + 1)
+            }
+        }
+        return GhostFileHTTPRequest(operation: operation, path: path, offset: offset, length: length)
+    }
+
+    private nonisolated static func route(
+        _ request: HTTPRequestHead,
+        body: Data,
+        using router: GhostFileShareRouter
+    ) async -> GhostFileHTTPResponse {
+        await router.route(request, body: body)
+    }
+
+    private func startFileResponse(
+        path: String,
+        identity: String,
+        offset: UInt64,
+        length: Int,
+        streamID: UInt64
+    ) {
+        if let context = requestLogs[streamID] {
+            ghostFileHTTP3ServerLogger.info(
+                "File response started request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) offset=\(offset, privacy: .public) bytes=\(length, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+            )
+        }
+        let task = Task { [weak self] in
+            guard let self else { return }
+            do {
+                try await Self.produceFileResponse(
+                    path: path,
+                    identity: identity,
+                    offset: offset,
+                    length: length,
+                    sendChunk: { [weak self] data, isFinal in
+                        guard let self else { throw CancellationError() }
+                        try await self.sendFileChunk(data, isFinal: isFinal, streamID: streamID)
+                    }
+                )
+                await self.fileResponseFinished(streamID: streamID)
+            } catch is CancellationError {
+                await self.cancelResponse(streamID: streamID)
+            } catch {
+                await self.fileResponseFailed(error, streamID: streamID)
+            }
+        }
+        responseTasks[streamID] = task
+    }
+
+    private func routingCancelled(streamID: UInt64) {
+        routingTasks.removeValue(forKey: streamID)
+        terminatedRequestStreams.remove(streamID)
+    }
+
+    private func routingFinished(
+        _ response: GhostFileHTTPResponse,
+        streamID: UInt64,
+        context: RequestLogContext
+    ) async {
+        guard routingTasks.removeValue(forKey: streamID) != nil,
+              !hasStopped,
+              !terminatedRequestStreams.contains(streamID) else { return }
+        await send(response, streamID: streamID, context: context)
+    }
+
+    private nonisolated static func produceFileResponse(
+        path: String,
+        identity: String,
+        offset: UInt64,
+        length: Int,
+        sendChunk: @escaping @Sendable (Data, Bool) async throws -> Void
+    ) async throws {
+        guard offset <= UInt64(Int64.max) else { throw POSIXError(.EOVERFLOW) }
+        let file = try await GhostFileDispatchIOFile.cached(path: path, identity: identity)
+
+        var currentOffset = offset
+        var remaining = length
+        while remaining > 0 {
+            try Task.checkCancellation()
+            let requestedLength = min(remaining, fileReadChunkSize)
+            let data = try await file.read(offset: currentOffset, length: requestedLength)
+            try Task.checkCancellation()
+            guard data.count == requestedLength else { throw POSIXError(.EIO) }
+            currentOffset += UInt64(data.count)
+            remaining -= data.count
+            try await sendChunk(data, remaining == 0)
+        }
+    }
+
+    private func sendFileChunk(_ data: Data, isFinal: Bool, streamID: UInt64) async throws {
+        guard !hasStopped, responseTasks[streamID] != nil else { throw CancellationError() }
+        try http3.appendResponseBody(streamID: streamID, data: data, isFinal: isFinal)
+        await flushOutgoing()
+        guard !hasStopped, responseTasks[streamID] != nil else { throw CancellationError() }
+    }
+
+    private func fileResponseFinished(streamID: UInt64) {
+        responseTasks.removeValue(forKey: streamID)
+        requestCompleted()
+        if let context = requestLogs.removeValue(forKey: streamID) {
+            ghostFileHTTP3ServerLogger.info(
+                "File response completed request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+            )
+        }
+    }
+
+    private func fileResponseFailed(_ error: Error, streamID: UInt64) async {
+        if let context = requestLogs.removeValue(forKey: streamID) {
+            ghostFileHTTP3ServerLogger.error(
+                "File response failed request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) error=\(String(describing: error), privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+            )
+        }
+        cancelResponse(streamID: streamID, resetTransport: true)
+        await flushOutgoing()
+    }
+
+    private func cancelResponse(streamID: UInt64, resetTransport: Bool = false) {
+        routingTasks.removeValue(forKey: streamID)?.cancel()
+        responseTasks.removeValue(forKey: streamID)?.cancel()
+        if resetTransport {
+            http3.resetResponse(streamID: streamID)
+        } else {
+            http3.abandonResponse(streamID: streamID)
+        }
+    }
+
+    private func drainPeerTerminatedResponses() {
+        for streamID in Array(routingTasks.keys)
+            where http3.peerStoppedReceivingResponse(streamID: streamID) {
+            terminatedRequestStreams.insert(streamID)
+            if let context = requestLogs.removeValue(forKey: streamID) {
+                ghostFileHTTP3ServerLogger.notice(
+                    "Response stopped by peer during routing request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+                )
+            }
+            cancelResponse(streamID: streamID)
+        }
+        for streamID in http3.takePeerTerminatedResponseStreamIDs() {
+            terminatedRequestStreams.insert(streamID)
+            if let context = requestLogs.removeValue(forKey: streamID) {
+                ghostFileHTTP3ServerLogger.notice(
+                    "Response abandoned by peer request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+                )
+            }
+            cancelResponse(streamID: streamID)
+        }
+        for streamID in http3.takeFailedResponseStreamIDs() {
+            terminatedRequestStreams.insert(streamID)
+            if let context = requestLogs.removeValue(forKey: streamID) {
+                ghostFileHTTP3ServerLogger.error(
+                    "Response stream failed request=\(context.requestID, privacy: .public) session=\(self.sessionID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(context.operation, privacy: .public) elapsedMs=\(ghostFileServerElapsedMilliseconds(since: context.startedAt), privacy: .public)"
+                )
+            }
+            cancelResponse(streamID: streamID, resetTransport: true)
+        }
+    }
+
+}
+
+/// Resolves the service GhostFile just published and returns the actual mDNS
+/// SRV target. `ProcessInfo.hostName` is not suitable here: VPN and DNS clients
+/// can replace it with a connectivity-check hostname that is not the machine's
+/// Bonjour endpoint.
+private final class GhostFileBonjourSelfResolver: NSObject, NetServiceBrowserDelegate, NetServiceDelegate {
+    private let completion: (String) -> Void
+    private let browser = NetServiceBrowser()
+    private weak var publishedService: NetService?
+    private var expectedName = ""
+    private var candidates: [ObjectIdentifier: NetService] = [:]
+    private var didResolve = false
+
+    init(completion: @escaping (String) -> Void) {
+        self.completion = completion
+        super.init()
+        browser.delegate = self
+        browser.includesPeerToPeer = true
+    }
+
+    func publish(_ service: NetService) {
+        publishedService = service
+        service.delegate = self
+        service.publish()
+    }
+
+    func stop() {
+        browser.stop()
+        for service in candidates.values {
+            service.stop()
+        }
+        candidates.removeAll()
+        publishedService?.delegate = nil
+        publishedService = nil
+    }
+
+    func netServiceDidPublish(_ sender: NetService) {
+        guard sender === publishedService else { return }
+        expectedName = sender.name
+        // Resolve the final registered name directly. Browsing for our own
+        // service can miss or be delayed when instances with the same display
+        // name overlap during their short shutdown grace period.
+        resolve(domain: sender.domain, type: sender.type, name: sender.name)
+        browser.searchForServices(ofType: sender.type, inDomain: sender.domain)
+    }
+
+    func netService(_ sender: NetService, didNotPublish errorDict: [String: NSNumber]) {
+        guard sender === publishedService else { return }
+        ghostFileHTTP3ServerLogger.error(
+            "Bonjour publication failed name=\(sender.name, privacy: .private(mask: .hash)) error=\(String(describing: errorDict), privacy: .public)"
+        )
+    }
+
+    func netServiceBrowser(
+        _ browser: NetServiceBrowser,
+        didFind service: NetService,
+        moreComing: Bool
+    ) {
+        guard !didResolve, service.name == expectedName else { return }
+        beginResolution(service)
+    }
+
+    func netService(_ sender: NetService, didNotResolve errorDict: [String: NSNumber]) {
+        guard candidates.removeValue(forKey: ObjectIdentifier(sender)) != nil else { return }
+        ghostFileHTTP3ServerLogger.notice(
+            "Bonjour self-resolution attempt failed name=\(sender.name, privacy: .private(mask: .hash)) error=\(String(describing: errorDict), privacy: .public)"
+        )
+    }
+
+    func netServiceDidResolveAddress(_ sender: NetService) {
+        guard !didResolve, candidates[ObjectIdentifier(sender)] != nil,
+              let hostName = sender.hostName else { return }
+        didResolve = true
+        let host = hostName.hasSuffix(".") ? String(hostName.dropLast()) : hostName
+        completion(host)
+        browser.stop()
+        for service in candidates.values where service !== sender {
+            service.stop()
+        }
+        candidates.removeAll()
+    }
+
+    private func resolve(domain: String, type: String, name: String) {
+        beginResolution(NetService(domain: domain, type: type, name: name))
+    }
+
+    private func beginResolution(_ service: NetService) {
+        let key = ObjectIdentifier(service)
+        guard candidates[key] == nil else { return }
+        candidates[key] = service
+        service.delegate = self
+        service.includesPeerToPeer = true
+        service.resolve(withTimeout: 5)
+    }
+}
+
+private final class GhostFileDispatchIOFile: @unchecked Sendable {
+    private static let callbackQueue = DispatchQueue(
+        label: "org.ghostvm.ghostfile.dispatch-io",
+        qos: .userInitiated,
+        attributes: .concurrent
+    )
+    private static let cacheMissQueue = DispatchQueue(
+        label: "org.ghostvm.ghostfile.dispatch-io.cache",
+        qos: .userInitiated
+    )
+    private static let cache: NSCache = {
+        let cache = NSCache()
+        cache.countLimit = 128
+        return cache
+    }()
+
+    private let channel: DispatchIO
+    private let cacheKey: NSString
+
+    static func cached(path: String, identity: String) async throws -> GhostFileDispatchIOFile {
+        let cacheKey = path + "\0" + identity
+        if let cached = cache.object(forKey: cacheKey as NSString) { return cached }
+        return try await withCheckedThrowingContinuation { continuation in
+            cacheMissQueue.async {
+                let key = cacheKey as NSString
+                if let cached = cache.object(forKey: key) {
+                    continuation.resume(returning: cached)
+                    return
+                }
+                do {
+                    let file = try GhostFileDispatchIOFile(path: path, cacheKey: key)
+                    cache.setObject(file, forKey: key)
+                    continuation.resume(returning: file)
+                } catch {
+                    continuation.resume(throwing: error)
+                }
+            }
+        }
+    }
+
+    init(path: String, cacheKey: NSString) throws {
+        guard let channel = path.withCString({ pathPointer in
+            DispatchIO(
+                type: .random,
+                path: pathPointer,
+                oflag: O_RDONLY,
+                mode: 0,
+                queue: Self.callbackQueue,
+                cleanupHandler: { _ in }
+            )
+        }) else {
+            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+        }
+        self.channel = channel
+        self.cacheKey = cacheKey
+    }
+
+    func read(offset: UInt64, length: Int) async throws -> Data {
+        guard offset <= UInt64(Int64.max), length >= 0 else { throw POSIXError(.EOVERFLOW) }
+        do {
+            return try await withCheckedThrowingContinuation { continuation in
+                let operation = GhostFileDispatchIOReadOperation(
+                    expectedLength: length,
+                    continuation: continuation
+                )
+                channel.read(
+                    offset: off_t(offset),
+                    length: length,
+                    queue: Self.callbackQueue,
+                    ioHandler: operation.receive(done:data:error:)
+                )
+            }
+        } catch {
+            if Self.cache.object(forKey: cacheKey) === self {
+                Self.cache.removeObject(forKey: cacheKey)
+            }
+            throw error
+        }
+    }
+
+    deinit { channel.close(flags: .stop) }
+}
+
+private final class GhostFileDispatchIOReadOperation: @unchecked Sendable {
+    private let lock = NSLock()
+    private let expectedLength: Int
+    private var data = Data()
+    private var continuation: CheckedContinuation?
+
+    init(expectedLength: Int, continuation: CheckedContinuation) {
+        self.expectedLength = expectedLength
+        self.continuation = continuation
+        data.reserveCapacity(expectedLength)
+    }
+
+    func receive(done: Bool, data dispatchData: DispatchData?, error: Int32) {
+        let chunk = dispatchData.map { Data($0) } ?? Data()
+        var completion: CheckedContinuation?
+        var result: Result?
+
+        lock.lock()
+        if continuation != nil {
+            if error != 0 {
+                completion = continuation
+                continuation = nil
+                result = .failure(POSIXError(POSIXErrorCode(rawValue: error) ?? .EIO))
+            } else {
+                if done {
+                    completion = continuation
+                    continuation = nil
+                    if data.isEmpty, chunk.count == expectedLength {
+                        result = .success(chunk)
+                    } else {
+                        data.append(chunk)
+                        result = data.count == expectedLength ? .success(data) : .failure(POSIXError(.EIO))
+                    }
+                } else {
+                    data.append(chunk)
+                }
+            }
+        }
+        lock.unlock()
+
+        if let completion, let result { completion.resume(with: result) }
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileHTTPClient.swift b/macOS/GhostFileKit/GhostFileHTTPClient.swift
new file mode 100644
index 0000000..730fdbf
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileHTTPClient.swift
@@ -0,0 +1,1440 @@
+import CryptoKit
+import Dispatch
+import Foundation
+import FSKit
+import GhostHTTP3
+import Network
+import OSLog
+import Security
+
+private let ghostFileHTTP3Logger = Logger(
+    subsystem: Bundle.main.bundleIdentifier ?? "org.ghostvm.ghostfilekit",
+    category: "HTTP3"
+)
+
+private let ghostFileCacheDiagnosticsEnabled =
+    ProcessInfo.processInfo.environment["GHOSTFILE_CACHE_DIAGNOSTICS"] == "1"
+
+private func ghostFileCacheDiagnostic(_ operation: String, path: String, result: String) {
+    guard ghostFileCacheDiagnosticsEnabled else { return }
+    ghostFileHTTP3Logger.notice(
+        "GHOSTFILE_CACHE_DIAG operation=\(operation, privacy: .public) result=\(result, privacy: .public) path=\(path, privacy: .private(mask: .hash))"
+    )
+}
+
+private let ghostFileProcessLogIdentity: String = {
+    let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "unknown"
+    let build = Bundle.main.object(forInfoDictionaryKey: "CFBundleVersion") as? String ?? "unknown"
+    return "version=\(version) build=\(build) pid=\(ProcessInfo.processInfo.processIdentifier)"
+}()
+
+private func ghostFileElapsedMilliseconds(since startedAt: UInt64) -> UInt64 {
+    let now = DispatchTime.now().uptimeNanoseconds
+    return now >= startedAt ? (now - startedAt) / 1_000_000 : 0
+}
+
+struct GhostFileHTTP3Client: Sendable {
+    private let transport: GhostFileHTTP3TransportPool
+    private let cache: GhostFileResponseCache
+    private let healthReporter: GhostFileMountHealthReporter?
+
+    init(
+        resourceURL: URL,
+        connectionTimeout: Duration = .seconds(8),
+        requestTimeout: Duration = .seconds(5)
+    ) throws {
+        guard resourceURL.scheme == GhostFileProtocol.urlScheme,
+              let host = resourceURL.host,
+              let portNumber = resourceURL.port,
+              let port = NWEndpoint.Port(rawValue: UInt16(portNumber)),
+              let components = URLComponents(url: resourceURL, resolvingAgainstBaseURL: false),
+              let accessKey = components.queryItems?.first(where: { $0.name == "access_key" })?.value,
+              !accessKey.isEmpty,
+              let peerPin = GhostFileProtocol.peerPin(from: resourceURL) else {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+        let cacheTTLSeconds: UInt64
+        if let rawTTL = components.queryItems?.first(where: {
+            $0.name == GhostFileProtocol.cacheTTLQueryName
+        })?.value {
+            guard let parsedTTL = UInt64(rawTTL),
+                  parsedTTL <= GhostFileProtocol.maximumCacheTTLSeconds else {
+                throw fs_errorForPOSIXError(EINVAL)
+            }
+            cacheTTLSeconds = parsedTTL
+        } else {
+            cacheTTLSeconds = GhostFileProtocol.defaultCacheTTLSeconds
+        }
+        cache = GhostFileResponseCache(lifetimeSeconds: cacheTTLSeconds)
+        transport = try GhostFileHTTP3TransportPool(
+            host: host,
+            port: port,
+            accessKey: accessKey,
+            peerPin: peerPin,
+            resourceBasePath: resourceURL.path,
+            connectionTimeout: connectionTimeout,
+            requestTimeout: requestTimeout
+        )
+        healthReporter = GhostFileProtocol.mountInstanceID(from: resourceURL).map {
+            GhostFileMountHealthReporter(mountID: $0)
+        }
+    }
+
+    func startHealthMonitoring() async {
+        await healthReporter?.start(transport: transport)
+    }
+
+    func stopHealthMonitoring() async {
+        await healthReporter?.stop()
+    }
+
+    func capabilities() async throws -> GhostFileCapabilities {
+        try await decode(GhostFileCapabilities.self, operation: "capabilities", relativePath: nil)
+    }
+
+    func metadata(path: String) async throws -> GhostFileMetadata {
+        if let cached = await cache.metadata(path: path) {
+            ghostFileCacheDiagnostic("metadata", path: path, result: "hit")
+            return cached
+        }
+        ghostFileCacheDiagnostic("metadata", path: path, result: "miss")
+        let metadata = try await decode(GhostFileMetadata.self, operation: "metadata", relativePath: path)
+        await cache.store(metadata: metadata, path: path)
+        return metadata
+    }
+
+    func directory(path: String) async throws -> GhostFileDirectoryListing {
+        if let cached = await cache.directory(path: path) {
+            ghostFileCacheDiagnostic("directory", path: path, result: "hit")
+            return cached
+        }
+        ghostFileCacheDiagnostic("directory", path: path, result: "miss")
+        let listing = try await decode(
+            GhostFileDirectoryListing.self,
+            operation: "directory",
+            relativePath: path
+        )
+        await cache.store(listing: listing, path: path)
+        return listing
+    }
+
+    func read(path: String, offset: UInt64, length: Int) async throws -> Data {
+        guard length >= 0, length <= GhostFileProtocol.maximumReadLength else {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+        if let cached = await cache.content(path: path, offset: offset, length: length) {
+            ghostFileCacheDiagnostic("content", path: path, result: "hit")
+            return cached
+        }
+        ghostFileCacheDiagnostic("content", path: path, result: "miss")
+        let data = try await request(operation: "content", relativePath: path, offset: offset, length: length)
+        await cache.storeRead(data: data, path: path, offset: offset)
+        return data
+    }
+
+    func readSymbolicLink(path: String) async throws -> String {
+        let data = try await request(operation: "readlink", relativePath: path)
+        guard let value = String(data: data, encoding: .utf8), !value.contains("\0") else {
+            throw fs_errorForPOSIXError(EIO)
+        }
+        return value
+    }
+
+    func create(path: String, type: GhostFileCreateType, mode: UInt32) async throws -> GhostFileMetadata {
+        let payload = try encode(GhostFileCreateRequest(type: type, mode: mode))
+        let metadata = try await decodeMutation(
+            operation: "create",
+            relativePath: path,
+            method: "POST",
+            body: payload
+        )
+        await cache.invalidateAll()
+        return metadata
+    }
+
+    func createSymbolicLink(path: String, destination: String) async throws -> GhostFileMetadata {
+        let payload = try encode(GhostFileSymbolicLinkRequest(destination: destination))
+        let metadata = try await decodeMutation(
+            operation: "symlink",
+            relativePath: path,
+            method: "POST",
+            body: payload
+        )
+        await cache.invalidateAll()
+        return metadata
+    }
+
+    func write(path: String, offset: UInt64, data: Data) async throws -> GhostFileMetadata {
+        var currentOffset = offset
+        var cursor = 0
+        var latestMetadata: GhostFileMetadata?
+        while cursor < data.count {
+            let end = min(data.count, cursor + GhostFileProtocol.maximumWriteLength)
+            let chunk = data.subdata(in: cursor.. GhostFileMetadata {
+        let metadata = try await decodeMutation(
+            operation: "attributes",
+            relativePath: path,
+            method: "PATCH",
+            body: try encode(attributes)
+        )
+        await cache.invalidateAll()
+        return metadata
+    }
+
+    func remove(path: String) async throws {
+        _ = try await request(operation: "remove", relativePath: path, method: "DELETE")
+        await cache.invalidateAll()
+    }
+
+    func rename(path: String, destinationPath: String) async throws -> GhostFileMetadata {
+        let metadata = try await decodeMutation(
+            operation: "rename",
+            relativePath: path,
+            method: "POST",
+            body: try encode(GhostFileRenameRequest(destinationPath: destinationPath))
+        )
+        await cache.invalidateAll()
+        return metadata
+    }
+
+    func invalidateTransportForTesting() async {
+        await transport.invalidateCurrentTransportForTesting()
+    }
+
+    func transportLogIDForTesting() async -> String? {
+        await transport.currentTransportLogIDForTesting()
+    }
+
+    private func decode(
+        _ type: T.Type,
+        operation: String,
+        relativePath: String?
+    ) async throws -> T {
+        let data = try await request(operation: operation, relativePath: relativePath)
+        do {
+            return try JSONDecoder().decode(type, from: data)
+        } catch {
+            throw fs_errorForPOSIXError(EIO)
+        }
+    }
+
+    private func decodeMutation(
+        operation: String,
+        relativePath: String,
+        method: String,
+        body: Data
+    ) async throws -> GhostFileMetadata {
+        let data = try await request(
+            operation: operation,
+            relativePath: relativePath,
+            method: method,
+            body: body
+        )
+        return try decodeResponse(GhostFileMetadata.self, data: data)
+    }
+
+    private func decodeResponse(_ type: T.Type, data: Data) throws -> T {
+        do {
+            return try JSONDecoder().decode(type, from: data)
+        } catch {
+            throw fs_errorForPOSIXError(EIO)
+        }
+    }
+
+    private func encode(_ value: T) throws -> Data {
+        do {
+            return try JSONEncoder().encode(value)
+        } catch {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+    }
+
+    private func request(
+        operation: String,
+        relativePath: String?,
+        offset: UInt64? = nil,
+        length: Int? = nil,
+        method: String = "GET",
+        body: Data = Data(),
+        headers: [(String, String)] = []
+    ) async throws -> Data {
+        let response: GhostFileHTTP3Transport.Response
+        do {
+            response = try await transport.request(
+                operation: operation,
+                relativePath: relativePath,
+                offset: offset,
+                length: length,
+                method: method,
+                body: body,
+                headers: headers
+            )
+            await healthReporter?.record(.operationSucceeded)
+        } catch {
+            await healthReporter?.record(
+                ghostFileIsExplicitPeerClose(error) ? .peerClosed : .operationFailed,
+                detail: String(describing: error)
+            )
+            ghostFileHTTP3Logger.error(
+                "Request failed operation=\(operation, privacy: .public) error=\(String(describing: error), privacy: .public)"
+            )
+            throw fs_errorForPOSIXError(ENOTCONN)
+        }
+        if ![200, 201, 204, 206].contains(response.status),
+           let payload = try? JSONDecoder().decode(GhostFileErrorPayload.self, from: response.body),
+           let rawErrno = payload.errno {
+            throw fs_errorForPOSIXError(rawErrno)
+        }
+        switch response.status {
+        case 200, 201, 204, 206:
+            return response.body
+        case 400, 416:
+            throw fs_errorForPOSIXError(EINVAL)
+        case 401, 403:
+            await healthReporter?.record(.operationFailed, detail: "The share rejected its access key")
+            throw fs_errorForPOSIXError(EACCES)
+        case 405:
+            throw fs_errorForPOSIXError(EROFS)
+        case 409:
+            throw fs_errorForPOSIXError(EEXIST)
+        case 507:
+            throw fs_errorForPOSIXError(ENOSPC)
+        case 404:
+            throw fs_errorForPOSIXError(ENOENT)
+        case 502, 503, 504:
+            await healthReporter?.record(.operationFailed, detail: "The share reported a transport failure")
+            throw fs_errorForPOSIXError(ENOTCONN)
+        default:
+            await healthReporter?.record(.operationFailed, detail: "The share returned HTTP \(response.status)")
+            throw fs_errorForPOSIXError(EIO)
+        }
+    }
+}
+
+private func ghostFileIsExplicitPeerClose(_ error: Error) -> Bool {
+    guard let transportError = error as? GhostFileHTTP3Transport.TransportError else { return false }
+    if case .peerClosed = transportError { return true }
+    return false
+}
+
+private actor GhostFileMountHealthReporter {
+    private let mountID: UUID
+    private let fileURL: URL
+    private var snapshot: GhostFileMountHealthSnapshot
+    private var heartbeatTask: Task?
+
+    init(mountID: UUID) {
+        self.mountID = mountID
+        fileURL = GhostFileMountHealthStorage.writerURL(for: mountID)
+        snapshot = GhostFileMountHealthSnapshot(
+            mountID: mountID,
+            state: .online,
+            detail: nil,
+            updatedAt: .distantPast
+        )
+    }
+
+    func start(transport: GhostFileHTTP3TransportPool) {
+        guard heartbeatTask == nil else { return }
+        heartbeatTask = Task { [weak self] in
+            while !Task.isCancelled {
+                do {
+                    try await Task.sleep(for: GhostFileProtocol.heartbeatInterval)
+                    guard !Task.isCancelled else { return }
+                    do {
+                        let response = try await transport.request(
+                            operation: "health",
+                            relativePath: nil,
+                            offset: nil,
+                            length: nil
+                        )
+                        if response.status == 200 {
+                            await self?.record(.heartbeatSucceeded)
+                        } else {
+                            await self?.record(
+                                .heartbeatMissed,
+                                detail: "Heartbeat returned HTTP \(response.status)"
+                            )
+                        }
+                    } catch {
+                        await self?.record(
+                            ghostFileIsExplicitPeerClose(error) ? .peerClosed : .heartbeatMissed,
+                            detail: String(describing: error)
+                        )
+                    }
+                } catch {
+                    return
+                }
+            }
+        }
+    }
+
+    func record(_ event: GhostFileMountHealthEvent, detail: String? = nil) {
+        snapshot = snapshot.applying(event, detail: detail)
+        persist()
+    }
+
+    func stop() {
+        heartbeatTask?.cancel()
+        heartbeatTask = nil
+        try? FileManager.default.removeItem(at: fileURL)
+    }
+
+    private func persist() {
+        do {
+            try FileManager.default.createDirectory(
+                at: fileURL.deletingLastPathComponent(),
+                withIntermediateDirectories: true
+            )
+            try JSONEncoder().encode(snapshot).write(to: fileURL, options: .atomic)
+        } catch {
+            ghostFileHTTP3Logger.error(
+                "Unable to persist mount health mount=\(self.mountID.uuidString.lowercased(), privacy: .public) error=\(String(describing: error), privacy: .public)"
+            )
+        }
+    }
+}
+
+private actor GhostFileHTTP3TransportPool {
+    private let host: String
+    private let port: NWEndpoint.Port
+    private let accessKey: String
+    private let peerPin: GhostFilePeerPin
+    private let resourceBasePath: String
+    private let connectionTimeout: Duration
+    private let requestTimeout: Duration
+    private var current: GhostFileHTTP3Transport?
+    private var mutationInFlight = false
+    private var mutationWaiters: [CheckedContinuation] = []
+
+    init(
+        host: String,
+        port: NWEndpoint.Port,
+        accessKey: String,
+        peerPin: GhostFilePeerPin,
+        resourceBasePath: String,
+        connectionTimeout: Duration,
+        requestTimeout: Duration
+    ) throws {
+        self.host = host
+        self.port = port
+        self.accessKey = accessKey
+        self.peerPin = peerPin
+        self.resourceBasePath = resourceBasePath
+        self.connectionTimeout = connectionTimeout
+        self.requestTimeout = requestTimeout
+        current = try Self.makeTransport(
+            host: host,
+            port: port,
+            accessKey: accessKey,
+            peerPin: peerPin,
+            resourceBasePath: resourceBasePath,
+            connectionTimeout: connectionTimeout,
+            requestTimeout: requestTimeout
+        )
+    }
+
+    func request(
+        operation: String,
+        relativePath: String?,
+        offset: UInt64?,
+        length: Int?,
+        method: String = "GET",
+        body: Data = Data(),
+        headers: [(String, String)] = []
+    ) async throws -> GhostFileHTTP3Transport.Response {
+        let isMutation = method != "GET" && method != "HEAD"
+        if isMutation { await acquireMutationSlot() }
+        defer {
+            if isMutation { releaseMutationSlot() }
+        }
+        let requestID = Self.makeLogID()
+        let pathTag = Self.pathTag(relativePath)
+        let startedAt = DispatchTime.now().uptimeNanoseconds
+        var lastError: Error?
+        for attempt in 0...1 {
+            let candidate = try transport()
+            ghostFileHTTP3Logger.info(
+                "Request attempt request=\(requestID, privacy: .public) transport=\(candidate.logID, privacy: .public) attempt=\(attempt + 1, privacy: .public) operation=\(operation, privacy: .public) pathTag=\(pathTag, privacy: .public) offset=\(String(describing: offset), privacy: .public) length=\(String(describing: length), privacy: .public)"
+            )
+            do {
+                let response = try await candidate.request(
+                    requestID: requestID,
+                    operation: operation,
+                    relativePath: relativePath,
+                    offset: offset,
+                    length: length,
+                    method: method,
+                    body: body,
+                    additionalHeaders: headers
+                )
+                ghostFileHTTP3Logger.info(
+                    "Request succeeded request=\(requestID, privacy: .public) transport=\(candidate.logID, privacy: .public) attempt=\(attempt + 1, privacy: .public) operation=\(operation, privacy: .public) status=\(response.status, privacy: .public) bytes=\(response.body.count, privacy: .public) totalMs=\(ghostFileElapsedMilliseconds(since: startedAt), privacy: .public)"
+                )
+                return response
+            } catch {
+                lastError = error
+                let terminal = await candidate.isTerminal
+                let requestTimedOut = Self.isRequestTimeout(error)
+                let peerClosed = Self.isCleanPeerClose(error)
+                ghostFileHTTP3Logger.error(
+                    "Request attempt failed request=\(requestID, privacy: .public) transport=\(candidate.logID, privacy: .public) attempt=\(attempt + 1, privacy: .public) operation=\(operation, privacy: .public) error=\(String(describing: error), privacy: .public) terminal=\(terminal, privacy: .public) totalMs=\(ghostFileElapsedMilliseconds(since: startedAt), privacy: .public)"
+                )
+                if requestTimedOut, !terminal {
+                    // A request deadline belongs to one HTTP/3 stream, not to
+                    // the QUIC connection. requestDeadlineExpired has already
+                    // reset that stream; keep the established transport for
+                    // sibling and subsequent requests.
+                    ghostFileHTTP3Logger.notice(
+                        "Request stream failed; transport retained request=\(requestID, privacy: .public) transport=\(candidate.logID, privacy: .public) operation=\(operation, privacy: .public) reason=requestTimedOut"
+                    )
+                    throw error
+                }
+                guard terminal else { throw error }
+                if current === candidate { current = nil }
+                guard !peerClosed else { throw error }
+                // A terminal failure can happen after the server committed a
+                // mutation but before its response reached us. Retrying a
+                // create, rename, delete, or write could apply it twice.
+                guard method == "GET" || method == "HEAD" else { throw error }
+                guard attempt == 0 else { throw error }
+                ghostFileHTTP3Logger.notice(
+                    "Request retry scheduled request=\(requestID, privacy: .public) retiredTransport=\(candidate.logID, privacy: .public) operation=\(operation, privacy: .public) reason=\(String(describing: error), privacy: .public) delayMs=100"
+                )
+                try? await Task.sleep(for: .milliseconds(100))
+            }
+        }
+        throw lastError ?? GhostFileHTTP3Transport.TransportError.closed
+    }
+
+    private func acquireMutationSlot() async {
+        if !mutationInFlight {
+            mutationInFlight = true
+            return
+        }
+        await withCheckedContinuation { continuation in
+            mutationWaiters.append(continuation)
+        }
+    }
+
+    private func releaseMutationSlot() {
+        if mutationWaiters.isEmpty {
+            mutationInFlight = false
+        } else {
+            mutationWaiters.removeFirst().resume()
+        }
+    }
+
+    func invalidateCurrentTransportForTesting() async {
+        await current?.invalidateForTesting()
+    }
+
+    func currentTransportLogIDForTesting() -> String? {
+        current?.logID
+    }
+
+    private func transport() throws -> GhostFileHTTP3Transport {
+        if let current { return current }
+        let replacement = try Self.makeTransport(
+            host: host,
+            port: port,
+            accessKey: accessKey,
+            peerPin: peerPin,
+            resourceBasePath: resourceBasePath,
+            connectionTimeout: connectionTimeout,
+            requestTimeout: requestTimeout
+        )
+        current = replacement
+        ghostFileHTTP3Logger.notice(
+            "Transport pool installed transport=\(replacement.logID, privacy: .public) host=\(self.host, privacy: .public) port=\(self.port.rawValue, privacy: .public)"
+        )
+        return replacement
+    }
+
+    private nonisolated static func makeLogID() -> String {
+        String(UUID().uuidString.prefix(12)).lowercased()
+    }
+
+    private nonisolated static func pathTag(_ path: String?) -> String {
+        guard let path else { return "none" }
+        let digest = SHA256.hash(data: Data(path.utf8))
+        return digest.prefix(6).map { String(format: "%02x", $0) }.joined()
+    }
+
+    private nonisolated static func makeTransport(
+        host: String,
+        port: NWEndpoint.Port,
+        accessKey: String,
+        peerPin: GhostFilePeerPin,
+        resourceBasePath: String,
+        connectionTimeout: Duration,
+        requestTimeout: Duration
+    ) throws -> GhostFileHTTP3Transport {
+        try GhostFileHTTP3Transport(
+            host: host,
+            port: port,
+            accessKey: accessKey,
+            peerPin: peerPin,
+            resourceBasePath: resourceBasePath,
+            connectionTimeout: connectionTimeout,
+            requestTimeout: requestTimeout
+        )
+    }
+
+    private nonisolated static func isRequestTimeout(_ error: Error) -> Bool {
+        guard let transportError = error as? GhostFileHTTP3Transport.TransportError else {
+            return false
+        }
+        if case .requestTimedOut = transportError { return true }
+        return false
+    }
+
+    private nonisolated static func isCleanPeerClose(_ error: Error) -> Bool {
+        guard let transportError = error as? GhostFileHTTP3Transport.TransportError else {
+            return false
+        }
+        if case .peerClosed = transportError { return true }
+        return false
+    }
+}
+
+private actor GhostFileResponseCache {
+    private struct Entry: Sendable {
+        let value: Value
+        let storedAt: UInt64
+    }
+
+    private struct CachedContent: Sendable {
+        let data: Data
+        let etag: String
+    }
+
+    private static let maximumMetadataCount = 32_768
+    private static let maximumDirectoryCount = 2_048
+    private static let maximumContentBytes = 64 * 1024 * 1024
+
+    private var metadataEntries: [String: Entry] = [:]
+    private var directoryEntries: [String: Entry] = [:]
+    private var contentEntries: [String: Entry] = [:]
+    private var contentBytes = 0
+    private let lifetime: UInt64
+
+    init(lifetimeSeconds: UInt64) {
+        lifetime = lifetimeSeconds * 1_000_000_000
+    }
+
+    func metadata(path: String) -> GhostFileMetadata? {
+        fresh(metadataEntries[path])?.value
+    }
+
+    func directory(path: String) -> GhostFileDirectoryListing? {
+        fresh(directoryEntries[path])?.value
+    }
+
+    func content(path: String, offset: UInt64, length: Int) -> Data? {
+        guard let entry = fresh(contentEntries[path]) else {
+            removeContent(path: path)
+            return nil
+        }
+        if let metadata = fresh(metadataEntries[path])?.value,
+           metadata.etag != entry.value.etag {
+            removeContent(path: path)
+            return nil
+        }
+        guard offset <= UInt64(entry.value.data.count) else { return nil }
+        let start = Int(offset)
+        let end = min(entry.value.data.count, start + length)
+        return entry.value.data.subdata(in: start..(_ entry: Entry?) -> Entry? {
+        guard lifetime > 0, let entry, Self.now &- entry.storedAt <= lifetime else { return nil }
+        return entry
+    }
+
+    private func storeContent(_ data: Data, etag: String, path: String, storedAt: UInt64) {
+        if let previous = contentEntries[path] { contentBytes -= previous.value.data.count }
+        contentEntries[path] = Entry(value: CachedContent(data: data, etag: etag), storedAt: storedAt)
+        contentBytes += data.count
+    }
+
+    private func removeContent(path: String) {
+        if let removed = contentEntries.removeValue(forKey: path) {
+            contentBytes -= removed.value.data.count
+        }
+    }
+
+    private func trimMetadataIfNeeded() {
+        guard metadataEntries.count > Self.maximumMetadataCount else { return }
+        removeOldest(from: &metadataEntries, count: metadataEntries.count - Self.maximumMetadataCount)
+    }
+
+    private func trimDirectoriesIfNeeded() {
+        guard directoryEntries.count > Self.maximumDirectoryCount else { return }
+        removeOldest(from: &directoryEntries, count: directoryEntries.count - Self.maximumDirectoryCount)
+    }
+
+    private func trimContentIfNeeded() {
+        guard contentBytes > Self.maximumContentBytes else { return }
+        for (path, _) in contentEntries.sorted(by: { $0.value.storedAt < $1.value.storedAt }) {
+            removeContent(path: path)
+            if contentBytes <= Self.maximumContentBytes { break }
+        }
+    }
+
+    private func removeOldest(from entries: inout [String: Entry], count: Int) {
+        for key in entries.sorted(by: { $0.value.storedAt < $1.value.storedAt }).prefix(count).map(\.key) {
+            entries.removeValue(forKey: key)
+        }
+    }
+
+    private static var now: UInt64 { DispatchTime.now().uptimeNanoseconds }
+}
+
+actor GhostFileHTTP3Transport {
+    struct Response: Sendable {
+        let status: Int
+        let body: Data
+    }
+
+    private let accessKey: String
+    private let host: String
+    private let resourceBasePath: String
+    private let expectedPeerPin: GhostFilePeerPin
+    private let connectionTimeout: Duration
+    private let requestTimeout: Duration
+    private let connection: NWConnection
+    private let http3: GhostFileHTTP3Connection
+    nonisolated let logID = String(UUID().uuidString.prefix(12)).lowercased()
+    private let createdAt = DispatchTime.now().uptimeNanoseconds
+    private var timeoutTask: Task?
+    private var connectionDeadlineTask: Task?
+    private var hasStarted = false
+    private var isNetworkReady = false
+    private var hasValidatedPeer = false
+    private var terminalError: Error?
+    private var readyWaiters: [UUID: CheckedContinuation] = [:]
+    private var handshakeWaiters: [UUID: CheckedContinuation] = [:]
+    private var pending: [UInt64: PendingResponse] = [:]
+    private var streamCreditWaiters: [PendingStreamCredit] = []
+    private var reservedStreamCredits: UInt64 = 0
+    private var isFlushing = false
+    private var flushAgain = false
+    private var pendingReceivedDatagrams: [Data] = []
+    private var pendingScheduledDatagram: GhostFileScheduledDatagram?
+    private var isReceiveDrainScheduled = false
+    private var receivedDatagramCount = 0
+    private var receivedByteCount = 0
+    private var sentDatagramCount = 0
+    private var sentByteCount = 0
+
+    var isTerminal: Bool { terminalError != nil }
+
+    init(
+        host: String,
+        port: NWEndpoint.Port,
+        accessKey: String,
+        peerPin: GhostFilePeerPin,
+        resourceBasePath: String = "/",
+        connectionTimeout: Duration = .seconds(8),
+        requestTimeout: Duration = .seconds(15)
+    ) throws {
+        self.accessKey = accessKey
+        self.host = host
+        self.resourceBasePath = resourceBasePath
+        self.expectedPeerPin = peerPin
+        self.connectionTimeout = connectionTimeout
+        self.requestTimeout = requestTimeout
+        let parameters = NWParameters.udp
+        parameters.includePeerToPeer = true
+        connection = NWConnection(host: NWEndpoint.Host(host), port: port, using: parameters)
+        http3 = try GhostFileHTTP3Connection(role: .client(serverName: host))
+        ghostFileHTTP3Logger.notice(
+            "Transport created transport=\(self.logID, privacy: .public) \(ghostFileProcessLogIdentity, privacy: .public) host=\(host, privacy: .public) port=\(port.rawValue, privacy: .public) connectionTimeout=\(String(describing: connectionTimeout), privacy: .public) requestTimeout=\(String(describing: requestTimeout), privacy: .public)"
+        )
+    }
+
+    init(
+        host: String,
+        port: NWEndpoint.Port,
+        accessKey: String,
+        publicKeyPin: String,
+        resourceBasePath: String = "/",
+        connectionTimeout: Duration = .seconds(8),
+        requestTimeout: Duration = .seconds(15)
+    ) throws {
+        try self.init(
+            host: host,
+            port: port,
+            accessKey: accessKey,
+            peerPin: .publicKey(publicKeyPin),
+            resourceBasePath: resourceBasePath,
+            connectionTimeout: connectionTimeout,
+            requestTimeout: requestTimeout
+        )
+    }
+
+    func request(
+        requestID: String = String(UUID().uuidString.prefix(12)).lowercased(),
+        operation: String,
+        relativePath: String?,
+        offset: UInt64?,
+        length: Int?,
+        method: String = "GET",
+        body: Data = Data(),
+        additionalHeaders: [(String, String)] = []
+    ) async throws -> Response {
+        let requestStartedAt = DispatchTime.now().uptimeNanoseconds
+        ghostFileHTTP3Logger.info(
+            "Transport request begin request=\(requestID, privacy: .public) transport=\(self.logID, privacy: .public) operation=\(operation, privacy: .public) started=\(self.hasStarted, privacy: .public) networkReady=\(self.isNetworkReady, privacy: .public) peerValidated=\(self.hasValidatedPeer, privacy: .public) pending=\(self.pending.count, privacy: .public)"
+        )
+        try await ensureHTTP3Ready()
+        try await acquireRequestStreamCredit(requestID: requestID, operation: operation)
+        do {
+            try Task.checkCancellation()
+            if let terminalError { throw terminalError }
+        } catch {
+            releaseReservedStreamCredit()
+            throw error
+        }
+        ghostFileHTTP3Logger.info(
+            "Transport request ready request=\(requestID, privacy: .public) transport=\(self.logID, privacy: .public) operation=\(operation, privacy: .public) readyMs=\(ghostFileElapsedMilliseconds(since: requestStartedAt), privacy: .public)"
+        )
+        var components = URLComponents()
+        components.path = operationPath(operation)
+        if let relativePath {
+            components.queryItems = [URLQueryItem(name: "path", value: relativePath)]
+        }
+        let path = components.string ?? components.path
+        var headers: [(String, String)] = [
+            (":method", method),
+            (":scheme", "https"),
+            (":authority", host),
+            (":path", path),
+            ("authorization", "Bearer \(accessKey)"),
+            ("accept", "application/json, application/octet-stream"),
+            ("x-ghostfile-request-id", requestID),
+        ]
+        if !body.isEmpty {
+            headers.append(("content-length", String(body.count)))
+            headers.append(("content-type", "application/octet-stream"))
+        }
+        headers.append(contentsOf: additionalHeaders)
+        if let offset, let length, length > 0 {
+            headers.append(("range", "bytes=\(offset)-\(offset + UInt64(length) - 1)"))
+        }
+        let streamID: UInt64
+        do {
+            streamID = try http3.sendRequest(headers: headers, body: body)
+            releaseReservedStreamCredit()
+        } catch {
+            releaseReservedStreamCredit()
+            grantAvailableStreamCredits()
+            throw error
+        }
+        ghostFileHTTP3Logger.info(
+            "HTTP/3 stream opened request=\(requestID, privacy: .public) transport=\(self.logID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(operation, privacy: .public) openMs=\(ghostFileElapsedMilliseconds(since: requestStartedAt), privacy: .public)"
+        )
+        return try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { continuation in
+                let deadlineTask = Task { [weak self, requestTimeout] in
+                    do {
+                        try await Task.sleep(for: requestTimeout)
+                        guard !Task.isCancelled else { return }
+                        await self?.requestDeadlineExpired(streamID: streamID)
+                    } catch {}
+                }
+                pending[streamID] = PendingResponse(
+                    requestID: requestID,
+                    operation: operation,
+                    startedAt: requestStartedAt,
+                    continuation: continuation,
+                    deadlineTask: deadlineTask
+                )
+                Task { await self.flushOutgoing() }
+            }
+        } onCancel: {
+            Task { await self.cancelPendingRequest(streamID: streamID) }
+        }
+    }
+
+    private func operationPath(_ operation: String) -> String {
+        // The share UUID is already part of the mount URL path. The server
+        // validates it, so retain it when translating an FSKit operation.
+        // `host` is intentionally not involved in HTTP routing.
+        return resourceBasePath + "/" + operation
+    }
+
+    private func ensureHTTP3Ready() async throws {
+        try Task.checkCancellation()
+        if let terminalError { throw terminalError }
+        if !hasStarted { start() }
+        try await waitForNetworkReady()
+        try Task.checkCancellation()
+        try await waitForValidatedPeer()
+    }
+
+    private func waitForNetworkReady() async throws {
+        guard !isNetworkReady else { return }
+        let waiterID = UUID()
+        try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { continuation in
+                readyWaiters[waiterID] = continuation
+            }
+        } onCancel: {
+            Task { await self.cancelNetworkReadyWaiter(id: waiterID) }
+        }
+    }
+
+    private func waitForValidatedPeer() async throws {
+        guard !hasValidatedPeer else { return }
+        let waiterID = UUID()
+        try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { continuation in
+                handshakeWaiters[waiterID] = continuation
+            }
+        } onCancel: {
+            Task { await self.cancelHandshakeWaiter(id: waiterID) }
+        }
+    }
+
+    private func cancelNetworkReadyWaiter(id: UUID) {
+        readyWaiters.removeValue(forKey: id)?.resume(throwing: CancellationError())
+    }
+
+    private func cancelHandshakeWaiter(id: UUID) {
+        handshakeWaiters.removeValue(forKey: id)?.resume(throwing: CancellationError())
+    }
+
+    private func start() {
+        guard !hasStarted else { return }
+        hasStarted = true
+        ghostFileHTTP3Logger.notice(
+            "UDP connection starting transport=\(self.logID, privacy: .public) host=\(self.host, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+        )
+        connection.stateUpdateHandler = { [weak self] state in
+            guard let self else { return }
+            Task { await self.connectionStateChanged(state) }
+        }
+        connection.start(queue: DispatchQueue(label: "org.ghostvm.ghostfile.http3.client"))
+        connectionDeadlineTask = Task { [weak self, connectionTimeout] in
+            do {
+                try await Task.sleep(for: connectionTimeout)
+                guard !Task.isCancelled else { return }
+                await self?.connectionDeadlineExpired()
+            } catch {}
+        }
+        connection.batch {
+            for _ in 0.. previousCount {
+                    response.firstDataAt = DispatchTime.now().uptimeNanoseconds
+                    ghostFileHTTP3Logger.info(
+                        "Response first data request=\(response.requestID, privacy: .public) transport=\(self.logID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(response.operation, privacy: .public) bytes=\(response.body.count - previousCount, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: response.startedAt), privacy: .public)"
+                    )
+                }
+                guard response.body.count <= GhostFileProtocol.maximumReadLength + 1024 * 1024 else {
+                    throw TransportError.invalidResponse
+                }
+            case .finished(let streamID):
+                guard let response = pending.removeValue(forKey: streamID) else { continue }
+                guard let status = response.status else {
+                    throw TransportError.invalidResponse
+                }
+                response.deadlineTask.cancel()
+                ghostFileHTTP3Logger.info(
+                    "Response finished request=\(response.requestID, privacy: .public) transport=\(self.logID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(response.operation, privacy: .public) status=\(status, privacy: .public) bytes=\(response.body.count, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: response.startedAt), privacy: .public)"
+                )
+                response.continuation.resume(returning: Response(status: status, body: response.body))
+            case .reset(let streamID):
+                if let response = pending.removeValue(forKey: streamID) {
+                    response.deadlineTask.cancel()
+                    ghostFileHTTP3Logger.error(
+                        "Response reset request=\(response.requestID, privacy: .public) transport=\(self.logID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(response.operation, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: response.startedAt), privacy: .public)"
+                    )
+                    response.continuation.resume(throwing: TransportError.streamReset)
+                }
+            }
+        }
+    }
+
+    private func acquireRequestStreamCredit(requestID: String, operation: String) async throws {
+        if unreservedStreamCreditCount > 0 {
+            reservedStreamCredits += 1
+            return
+        }
+
+        let waiterID = UUID()
+        ghostFileHTTP3Logger.notice(
+            "HTTP/3 stream credit wait request=\(requestID, privacy: .public) transport=\(self.logID, privacy: .public) operation=\(operation, privacy: .public) waiters=\(self.streamCreditWaiters.count + 1, privacy: .public)"
+        )
+        try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { continuation in
+                let deadlineTask = Task { [weak self, requestTimeout] in
+                    do {
+                        try await Task.sleep(for: requestTimeout)
+                        guard !Task.isCancelled else { return }
+                        await self?.streamCreditWaiterExpired(id: waiterID)
+                    } catch {}
+                }
+                streamCreditWaiters.append(PendingStreamCredit(
+                    id: waiterID,
+                    requestID: requestID,
+                    operation: operation,
+                    continuation: continuation,
+                    deadlineTask: deadlineTask
+                ))
+                grantAvailableStreamCredits()
+            }
+        } onCancel: {
+            Task { await self.cancelStreamCreditWaiter(id: waiterID) }
+        }
+    }
+
+    private var unreservedStreamCreditCount: UInt64 {
+        let available = http3.availableRequestStreamCount
+        return available > reservedStreamCredits ? available - reservedStreamCredits : 0
+    }
+
+    private func grantAvailableStreamCredits() {
+        while !streamCreditWaiters.isEmpty, unreservedStreamCreditCount > 0 {
+            let waiter = streamCreditWaiters.removeFirst()
+            reservedStreamCredits += 1
+            waiter.deadlineTask.cancel()
+            ghostFileHTTP3Logger.notice(
+                "HTTP/3 stream credit granted request=\(waiter.requestID, privacy: .public) transport=\(self.logID, privacy: .public) operation=\(waiter.operation, privacy: .public) remainingWaiters=\(self.streamCreditWaiters.count, privacy: .public)"
+            )
+            waiter.continuation.resume()
+        }
+    }
+
+    private func releaseReservedStreamCredit() {
+        precondition(reservedStreamCredits > 0, "Released HTTP/3 stream credit without a reservation")
+        reservedStreamCredits -= 1
+    }
+
+    private func cancelStreamCreditWaiter(id: UUID) {
+        guard let index = streamCreditWaiters.firstIndex(where: { $0.id == id }) else { return }
+        let waiter = streamCreditWaiters.remove(at: index)
+        waiter.deadlineTask.cancel()
+        waiter.continuation.resume(throwing: CancellationError())
+    }
+
+    private func streamCreditWaiterExpired(id: UUID) {
+        guard let index = streamCreditWaiters.firstIndex(where: { $0.id == id }) else { return }
+        let waiter = streamCreditWaiters.remove(at: index)
+        ghostFileHTTP3Logger.error(
+            "HTTP/3 stream credit deadline expired request=\(waiter.requestID, privacy: .public) transport=\(self.logID, privacy: .public) operation=\(waiter.operation, privacy: .public) waiters=\(self.streamCreditWaiters.count + 1, privacy: .public)"
+        )
+        waiter.continuation.resume(throwing: TransportError.requestTimedOut)
+    }
+
+    private func connectionDeadlineExpired() {
+        guard !hasValidatedPeer, terminalError == nil else { return }
+        ghostFileHTTP3Logger.error(
+            "QUIC handshake deadline expired transport=\(self.logID, privacy: .public) networkReady=\(self.isNetworkReady, privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) receivedBytes=\(self.receivedByteCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) sentBytes=\(self.sentByteCount, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+        )
+        fail(TransportError.connectionTimedOut)
+    }
+
+    private func requestDeadlineExpired(streamID: UInt64) async {
+        guard let response = pending.removeValue(forKey: streamID), terminalError == nil else { return }
+        ghostFileHTTP3Logger.error(
+            "Request deadline expired request=\(response.requestID, privacy: .public) transport=\(self.logID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(response.operation, privacy: .public) status=\(String(describing: response.status), privacy: .public) bodyBytes=\(response.body.count, privacy: .public) networkReady=\(self.isNetworkReady, privacy: .public) peerValidated=\(self.hasValidatedPeer, privacy: .public) pending=\(self.pending.count + 1, privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: response.startedAt), privacy: .public)"
+        )
+        http3.cancelRequest(streamID: streamID)
+        response.continuation.resume(throwing: TransportError.requestTimedOut)
+        await flushOutgoing()
+    }
+
+    private func cancelPendingRequest(streamID: UInt64) async {
+        guard let response = pending.removeValue(forKey: streamID) else { return }
+        response.deadlineTask.cancel()
+        ghostFileHTTP3Logger.notice(
+            "Request cancelled request=\(response.requestID, privacy: .public) transport=\(self.logID, privacy: .public) stream=\(streamID, privacy: .public) operation=\(response.operation, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: response.startedAt), privacy: .public)"
+        )
+        http3.cancelRequest(streamID: streamID)
+        response.continuation.resume(throwing: CancellationError())
+        await flushOutgoing()
+    }
+
+    private func flushOutgoing() async {
+        if isFlushing {
+            flushAgain = true
+            return
+        }
+        guard isNetworkReady, terminalError == nil else { return }
+        isFlushing = true
+        defer { isFlushing = false }
+        do {
+            repeat {
+                flushAgain = false
+                while true {
+                    let produceStartedAt = DispatchTime.now().uptimeNanoseconds
+                    var datagrams: [Data] = []
+                    datagrams.reserveCapacity(GhostFileNetworkDatagram.maximumSendBatchCount)
+                    var transportDrained = false
+                    while datagrams.count < GhostFileNetworkDatagram.maximumSendBatchCount {
+                        let scheduled: GhostFileScheduledDatagram
+                        if let pendingScheduledDatagram {
+                            scheduled = pendingScheduledDatagram
+                        } else if let next = try http3.nextScheduledDatagram() {
+                            scheduled = next
+                        } else {
+                            transportDrained = true
+                            break
+                        }
+                        let now = ghostFileMonotonicNanoseconds()
+                        guard scheduled.sendAtNanoseconds <= now else {
+                            pendingScheduledDatagram = scheduled
+                            break
+                        }
+                        pendingScheduledDatagram = nil
+                        datagrams.append(scheduled.data)
+                    }
+                    if datagrams.isEmpty {
+                        if transportDrained { break }
+                        guard let pendingScheduledDatagram else { break }
+                        let now = ghostFileMonotonicNanoseconds()
+                        if pendingScheduledDatagram.sendAtNanoseconds > now {
+                            try await Task.sleep(
+                                nanoseconds: pendingScheduledDatagram.sendAtNanoseconds - now
+                            )
+                        }
+                        continue
+                    }
+                    let produceFinishedAt = DispatchTime.now().uptimeNanoseconds
+                    try await connection.sendGhostFileDatagrams(datagrams)
+                    let sendFinishedAt = DispatchTime.now().uptimeNanoseconds
+                    sentDatagramCount += datagrams.count
+                    sentByteCount += datagrams.reduce(into: 0) { $0 += $1.count }
+                    http3.recordSendBatch(
+                        packetCount: datagrams.count,
+                        produceNanoseconds: produceFinishedAt - produceStartedAt,
+                        networkNanoseconds: sendFinishedAt - produceFinishedAt
+                    )
+                }
+            } while flushAgain
+            resetTimeout()
+        } catch {
+            fail(error)
+        }
+    }
+
+    private func resetTimeout() {
+        timeoutTask?.cancel()
+        guard let nanoseconds = http3.timeoutNanoseconds else { return }
+        timeoutTask = Task { [weak self] in
+            do {
+                try await Task.sleep(nanoseconds: max(1_000_000, nanoseconds))
+                guard !Task.isCancelled else { return }
+                await self?.timeoutFired()
+            } catch {}
+        }
+    }
+
+    private func timeoutFired() async {
+        http3.handleTimeout()
+        await flushOutgoing()
+        if http3.isClosed {
+            ghostFileHTTP3Logger.error(
+                "QUIC timeout closed transport transport=\(self.logID, privacy: .public) pending=\(self.pending.count, privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+            )
+            fail(TransportError.closed)
+        }
+    }
+
+    private func fail(_ error: Error) {
+        guard terminalError == nil else { return }
+        ghostFileHTTP3Logger.error(
+            "Transport failed transport=\(self.logID, privacy: .public) error=\(String(describing: error), privacy: .public) networkReady=\(self.isNetworkReady, privacy: .public) peerValidated=\(self.hasValidatedPeer, privacy: .public) pending=\(self.pending.count, privacy: .public) receivedDatagrams=\(self.receivedDatagramCount, privacy: .public) receivedBytes=\(self.receivedByteCount, privacy: .public) sentDatagrams=\(self.sentDatagramCount, privacy: .public) sentBytes=\(self.sentByteCount, privacy: .public) elapsedMs=\(ghostFileElapsedMilliseconds(since: self.createdAt), privacy: .public)"
+        )
+        terminalError = error
+        readyWaiters.values.forEach { $0.resume(throwing: error) }
+        handshakeWaiters.values.forEach { $0.resume(throwing: error) }
+        readyWaiters.removeAll()
+        handshakeWaiters.removeAll()
+        for response in pending.values { response.continuation.resume(throwing: error) }
+        pending.removeAll()
+        for waiter in streamCreditWaiters {
+            waiter.deadlineTask.cancel()
+            waiter.continuation.resume(throwing: error)
+        }
+        streamCreditWaiters.removeAll()
+        timeoutTask?.cancel()
+        connectionDeadlineTask?.cancel()
+        pendingScheduledDatagram = nil
+        connection.cancel()
+    }
+
+    func invalidateForTesting() {
+        fail(TransportError.closed)
+    }
+
+    private nonisolated static func matches(
+        certificate: Data,
+        expectedPin: GhostFilePeerPin
+    ) -> Bool {
+        switch expectedPin {
+        case .publicKey(let expected):
+            return publicKeyPin(forCertificate: certificate) == expected
+        case .legacyCertificate(let expected):
+            return certificatePin(for: certificate) == expected
+        }
+    }
+
+    private nonisolated static func certificatePin(for bytes: Data) -> String {
+        let digest = SHA256.hash(data: bytes)
+        return Data(digest).base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+
+    private nonisolated static func publicKeyPin(forCertificate bytes: Data) -> String? {
+        guard let certificate = SecCertificateCreateWithData(nil, bytes as CFData),
+              let publicKey = SecCertificateCopyKey(certificate) else { return nil }
+        var error: Unmanaged?
+        guard let publicKeyBytes = SecKeyCopyExternalRepresentation(publicKey, &error) as Data? else {
+            return nil
+        }
+        let digest = SHA256.hash(data: publicKeyBytes)
+        return "p256-sha256-" + Data(digest).base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+
+    private final class PendingResponse {
+        let requestID: String
+        let operation: String
+        let startedAt: UInt64
+        let continuation: CheckedContinuation
+        let deadlineTask: Task
+        var status: Int?
+        var body = Data()
+        var headersAt: UInt64?
+        var firstDataAt: UInt64?
+
+        init(
+            requestID: String,
+            operation: String,
+            startedAt: UInt64,
+            continuation: CheckedContinuation,
+            deadlineTask: Task
+        ) {
+            self.requestID = requestID
+            self.operation = operation
+            self.startedAt = startedAt
+            self.continuation = continuation
+            self.deadlineTask = deadlineTask
+        }
+    }
+
+    private struct PendingStreamCredit {
+        let id: UUID
+        let requestID: String
+        let operation: String
+        let continuation: CheckedContinuation
+        let deadlineTask: Task
+    }
+
+    enum TransportError: Error {
+        case invalidResponse
+        case certificatePinMismatch
+        case streamReset
+        case connectionTimedOut
+        case requestTimedOut
+        case peerClosed
+        case closed
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileItem.swift b/macOS/GhostFileKit/GhostFileItem.swift
new file mode 100644
index 0000000..5e5e014
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileItem.swift
@@ -0,0 +1,42 @@
+import FSKit
+import Foundation
+
+final class GhostFileItem: FSItem {
+    private let lock = NSLock()
+    private var storedRelativePath: String
+    private var storedParentID: FSItem.Identifier
+    private var storedMetadata: GhostFileMetadata
+
+    init(relativePath: String, parentID: FSItem.Identifier, metadata: GhostFileMetadata) {
+        self.storedRelativePath = relativePath
+        self.storedParentID = parentID
+        self.storedMetadata = metadata
+    }
+
+    var relativePath: String {
+        lock.withLock { storedRelativePath }
+    }
+
+    var parentID: FSItem.Identifier {
+        lock.withLock { storedParentID }
+    }
+
+    var metadata: GhostFileMetadata {
+        lock.lock()
+        defer { lock.unlock() }
+        return storedMetadata
+    }
+
+    func update(metadata: GhostFileMetadata) {
+        lock.lock()
+        storedMetadata = metadata
+        lock.unlock()
+    }
+
+    func updateLocation(relativePath: String, parentID: FSItem.Identifier) {
+        lock.lock()
+        storedRelativePath = relativePath
+        storedParentID = parentID
+        lock.unlock()
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileProtocol.swift b/macOS/GhostFileKit/GhostFileProtocol.swift
new file mode 100644
index 0000000..55d475d
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileProtocol.swift
@@ -0,0 +1,401 @@
+import Foundation
+
+public enum GhostFilePeerPin: Equatable, Sendable {
+    case publicKey(String)
+    case legacyCertificate(String)
+
+    public var value: String {
+        switch self {
+        case .publicKey(let value), .legacyCertificate(let value): value
+        }
+    }
+}
+
+public enum GhostFileProtocol {
+    public static let version = 3
+    public static let urlScheme = "ghostfile"
+    public static let bonjourType = "_ghostfile._udp."
+    public static let bonjourDomain = "local."
+    public static let alpn = "h3"
+    public static let transport = "http3"
+    public static let publicKeyPinQueryName = "pk"
+    public static let legacyCertificatePinQueryName = "tls_pin"
+    public static let maximumReadLength = 1024 * 1024
+    public static let maximumWriteLength = 1024 * 1024
+    public static let maximumInlineFileLength = 64 * 1024
+    public static let maximumInlineDirectoryLength = 512 * 1024
+    public static let maximumInlineDirectoryFileCount = 256
+    public static let mountInstanceQueryName = "mount_instance"
+    public static let cacheTTLQueryName = "cache_ttl"
+    public static let defaultCacheTTLSeconds: UInt64 = 5
+    public static let maximumCacheTTLSeconds: UInt64 = 300
+    public static let heartbeatInterval = Duration.seconds(5)
+    public static let heartbeatStaleAfter: TimeInterval = 12
+
+    public static func shareBasePath(id: UUID) -> String {
+        "/v1/shares/\(id.uuidString.lowercased())"
+    }
+
+    public static func peerPin(from url: URL) -> GhostFilePeerPin? {
+        guard let items = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems else {
+            return nil
+        }
+        let publicKeyPins = items.filter { $0.name == publicKeyPinQueryName }.compactMap(\.value)
+        if !publicKeyPins.isEmpty {
+            guard publicKeyPins.count == 1, validPublicKeyPin(publicKeyPins[0]) else { return nil }
+            return .publicKey(publicKeyPins[0])
+        }
+        let certificatePins = items.filter { $0.name == legacyCertificatePinQueryName }.compactMap(\.value)
+        guard certificatePins.count == 1, !certificatePins[0].isEmpty else { return nil }
+        return .legacyCertificate(certificatePins[0])
+    }
+
+    public static func validPublicKeyPin(_ value: String) -> Bool {
+        let prefix = "p256-sha256-"
+        guard value.hasPrefix(prefix) else { return false }
+        let digest = value.dropFirst(prefix.count)
+        guard digest.count == 43 else { return false }
+        return digest.unicodeScalars.allSatisfy {
+            CharacterSet.alphanumerics.contains($0) || $0 == "-" || $0 == "_"
+        }
+    }
+
+    /// FSKit uses the resource and volume identifiers to serialize work. Give
+    /// every network mount a connection-specific UUID so a dead mount cannot
+    /// leave a later connection to the same share permanently EBUSY.
+    ///
+    /// Although FSKit also exposes an eight-byte identifier qualifier for this
+    /// purpose, macOS 26.4 drops it during the final LiveFS connector lookup.
+    /// A plain UUID survives that handoff intact.
+    public static func mountInstanceID(from url: URL) -> UUID? {
+        guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+              let value = components.queryItems?.first(where: {
+                  $0.name == mountInstanceQueryName
+              })?.value else { return nil }
+        return UUID(uuidString: value)
+    }
+}
+
+public struct GhostFileBonjourLease {
+    // NetService does not expose record TTLs, so shares publish and refresh an
+    // application-level lease in their TXT record.
+    public static let advertisedTTL: TimeInterval = 6
+    public static let legacyTTL: TimeInterval = 15
+    public static let heartbeatInterval = Duration.seconds(2)
+    public static let sweepInterval = Duration.seconds(1)
+
+    public static func ttl(from txt: [String: Data]) -> TimeInterval {
+        guard let data = txt["ttl"],
+              let string = String(data: data, encoding: .utf8),
+              let seconds = TimeInterval(string),
+              seconds.isFinite else {
+            return legacyTTL
+        }
+        return min(max(seconds, 4), 60)
+    }
+
+    public static func isExpired(lastSeen: Date, ttl: TimeInterval, now: Date = Date()) -> Bool {
+        now.timeIntervalSince(lastSeen) >= ttl
+    }
+}
+
+public enum GhostFileMountHealthState: String, Codable, Equatable, Sendable {
+    case online
+    case degraded
+    case error
+    case offline
+}
+
+public enum GhostFileMountHealthEvent: Equatable, Sendable {
+    case heartbeatSucceeded
+    case heartbeatMissed
+    case operationSucceeded
+    case operationFailed
+    case peerClosed
+}
+
+public struct GhostFileMountHealthSnapshot: Codable, Equatable, Sendable {
+    public let mountID: UUID
+    public let state: GhostFileMountHealthState
+    public let detail: String?
+    public let updatedAt: Date
+
+    public init(mountID: UUID, state: GhostFileMountHealthState, detail: String?, updatedAt: Date) {
+        self.mountID = mountID
+        self.state = state
+        self.detail = detail
+        self.updatedAt = updatedAt
+    }
+
+    public func applying(
+        _ event: GhostFileMountHealthEvent,
+        detail newDetail: String? = nil,
+        at date: Date = Date()
+    ) -> Self {
+        let nextState: GhostFileMountHealthState
+        switch event {
+        case .heartbeatSucceeded, .operationSucceeded:
+            nextState = .online
+        case .heartbeatMissed:
+            // Heartbeat silence is only evidence for degradation. It must not
+            // erase a real operation error or an explicit peer close.
+            switch state {
+            case .online, .degraded: nextState = .degraded
+            case .error, .offline: nextState = state
+            }
+        case .operationFailed:
+            nextState = .error
+        case .peerClosed:
+            nextState = .offline
+        }
+        return Self(
+            mountID: mountID,
+            state: nextState,
+            detail: nextState == .online ? nil : newDetail ?? detail,
+            updatedAt: date
+        )
+    }
+
+    public func degradingIfStale(
+        at date: Date = Date(),
+        staleAfter: TimeInterval = GhostFileProtocol.heartbeatStaleAfter
+    ) -> Self {
+        guard state == .online, date.timeIntervalSince(updatedAt) > staleAfter else { return self }
+        return Self(
+            mountID: mountID,
+            state: .degraded,
+            detail: "No recent heartbeat",
+            updatedAt: updatedAt
+        )
+    }
+}
+
+public enum GhostFileMountHealthStorage {
+    private static let directoryComponents = ["GhostFile", "Mount Health"]
+    private static let extensionBundleIdentifier = "org.ghostvm.ghostfile.fs"
+
+    public static func writerURL(for mountID: UUID, fileManager: FileManager = .default) -> URL {
+        let applicationSupport = fileManager.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+        return directoryComponents.reduce(applicationSupport) {
+            $0.appendingPathComponent($1, isDirectory: true)
+        }.appendingPathComponent("\(mountID.uuidString.lowercased()).json")
+    }
+
+    public static func readerURL(
+        for mountID: UUID,
+        homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser
+    ) -> URL {
+        var url = homeDirectory
+            .appendingPathComponent("Library/Containers", isDirectory: true)
+            .appendingPathComponent(extensionBundleIdentifier, isDirectory: true)
+            .appendingPathComponent("Data/Library/Application Support", isDirectory: true)
+        for component in directoryComponents {
+            url.appendPathComponent(component, isDirectory: true)
+        }
+        return url.appendingPathComponent("\(mountID.uuidString.lowercased()).json")
+    }
+}
+
+struct GhostFileHTTPRequest: Sendable {
+    let operation: String
+    let path: String?
+    let offset: UInt64?
+    let length: Int?
+}
+
+public enum GhostFileNodeType: String, Codable, Sendable {
+    case file
+    case directory
+    case symbolicLink
+    case other
+}
+
+public struct GhostFileCapabilities: Codable, Equatable, Sendable {
+    public let protocolVersion: Int
+    public let shareID: UUID
+    public let name: String
+    public let readOnly: Bool
+    public let transports: [String]
+    public let maximumReadLength: Int
+}
+
+public struct GhostFileMetadata: Codable, Equatable, Sendable {
+    public let name: String
+    public let type: GhostFileNodeType
+    public let size: UInt64
+    public let mode: UInt32
+    public let uid: UInt32
+    public let gid: UInt32
+    public let objectID: UInt64
+    public let modifiedSeconds: Int64
+    public let modifiedNanoseconds: Int32
+    public let accessedSeconds: Int64?
+    public let accessedNanoseconds: Int32?
+    public let changedSeconds: Int64?
+    public let changedNanoseconds: Int32?
+    public let birthSeconds: Int64?
+    public let birthNanoseconds: Int32?
+    public let etag: String
+
+    public init(
+        name: String,
+        type: GhostFileNodeType,
+        size: UInt64,
+        mode: UInt32,
+        uid: UInt32,
+        gid: UInt32,
+        objectID: UInt64,
+        modifiedSeconds: Int64,
+        modifiedNanoseconds: Int32,
+        accessedSeconds: Int64? = nil,
+        accessedNanoseconds: Int32? = nil,
+        changedSeconds: Int64? = nil,
+        changedNanoseconds: Int32? = nil,
+        birthSeconds: Int64? = nil,
+        birthNanoseconds: Int32? = nil,
+        etag: String
+    ) {
+        self.name = name
+        self.type = type
+        self.size = size
+        self.mode = mode
+        self.uid = uid
+        self.gid = gid
+        self.objectID = objectID
+        self.modifiedSeconds = modifiedSeconds
+        self.modifiedNanoseconds = modifiedNanoseconds
+        self.accessedSeconds = accessedSeconds
+        self.accessedNanoseconds = accessedNanoseconds
+        self.changedSeconds = changedSeconds
+        self.changedNanoseconds = changedNanoseconds
+        self.birthSeconds = birthSeconds
+        self.birthNanoseconds = birthNanoseconds
+        self.etag = etag
+    }
+}
+
+public struct GhostFileDirectoryListing: Codable, Equatable, Sendable {
+    public let path: String
+    public let verifier: UInt64
+    public let entries: [GhostFileMetadata]
+    public let inlineContents: [GhostFileInlineContent]?
+
+    public init(
+        path: String,
+        verifier: UInt64,
+        entries: [GhostFileMetadata],
+        inlineContents: [GhostFileInlineContent]? = nil
+    ) {
+        self.path = path
+        self.verifier = verifier
+        self.entries = entries
+        self.inlineContents = inlineContents
+    }
+}
+
+public struct GhostFileInlineContent: Codable, Equatable, Sendable {
+    public let name: String
+    public let etag: String
+    public let data: Data
+}
+
+public struct GhostFileErrorPayload: Codable, Equatable, Sendable {
+    public let error: String
+    public let errno: Int32?
+
+    public init(error: String, errno: Int32? = nil) {
+        self.error = error
+        self.errno = errno
+    }
+}
+
+public enum GhostFileCreateType: String, Codable, Equatable, Sendable {
+    case file
+    case directory
+}
+
+public struct GhostFileCreateRequest: Codable, Equatable, Sendable {
+    public let type: GhostFileCreateType
+    public let mode: UInt32
+
+    public init(type: GhostFileCreateType, mode: UInt32) {
+        self.type = type
+        self.mode = mode
+    }
+}
+
+public struct GhostFileSymbolicLinkRequest: Codable, Equatable, Sendable {
+    public let destination: String
+
+    public init(destination: String) {
+        self.destination = destination
+    }
+}
+
+public struct GhostFileRenameRequest: Codable, Equatable, Sendable {
+    public let destinationPath: String
+
+    public init(destinationPath: String) {
+        self.destinationPath = destinationPath
+    }
+}
+
+public struct GhostFileSetAttributesRequest: Codable, Equatable, Sendable {
+    public let mode: UInt32?
+    public let size: UInt64?
+    public let modifiedSeconds: Int64?
+    public let modifiedNanoseconds: Int32?
+    public let accessedSeconds: Int64?
+    public let accessedNanoseconds: Int32?
+
+    public init(
+        mode: UInt32? = nil,
+        size: UInt64? = nil,
+        modifiedSeconds: Int64? = nil,
+        modifiedNanoseconds: Int32? = nil,
+        accessedSeconds: Int64? = nil,
+        accessedNanoseconds: Int32? = nil
+    ) {
+        self.mode = mode
+        self.size = size
+        self.modifiedSeconds = modifiedSeconds
+        self.modifiedNanoseconds = modifiedNanoseconds
+        self.accessedSeconds = accessedSeconds
+        self.accessedNanoseconds = accessedNanoseconds
+    }
+}
+
+enum GhostFilePath {
+    static func validatedComponents(_ relativePath: String) -> [String]? {
+        guard !relativePath.contains("\0"), !relativePath.hasPrefix("/") else { return nil }
+        let components = relativePath.split(separator: "/", omittingEmptySubsequences: true).map(String.init)
+        guard !components.contains(where: { $0 == "." || $0 == ".." }) else { return nil }
+        return components
+    }
+
+    static func percentEncodedQuery(_ value: String) -> String {
+        var components = URLComponents()
+        components.queryItems = [URLQueryItem(name: "path", value: value)]
+        return components.percentEncodedQuery ?? "path="
+    }
+}
+
+struct GhostFileByteRange: Equatable, Sendable {
+    let offset: UInt64
+    let length: Int
+
+    static func parse(_ value: String?, fileSize: UInt64, maximumLength: Int) -> Self? {
+        guard let value, value.lowercased().hasPrefix("bytes=") else { return nil }
+        let raw = value.dropFirst("bytes=".count)
+        let pieces = raw.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)
+        guard pieces.count == 2,
+              let start = UInt64(pieces[0]),
+              start < fileSize else { return nil }
+
+        let requestedEnd = pieces[1].isEmpty ? nil : UInt64(pieces[1])
+        guard requestedEnd == nil || requestedEnd! >= start else { return nil }
+        let boundedEnd = min(requestedEnd ?? (start + UInt64(maximumLength) - 1), fileSize - 1)
+        let length = Int(min(UInt64(maximumLength), boundedEnd - start + 1))
+        return Self(offset: start, length: length)
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileProvider.swift b/macOS/GhostFileKit/GhostFileProvider.swift
new file mode 100644
index 0000000..581617b
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileProvider.swift
@@ -0,0 +1,111 @@
+import Foundation
+
+public enum GhostFileProviderNodeType: String, Sendable {
+    case file
+    case directory
+    case symbolicLink
+    case other
+}
+
+public struct GhostFileProviderMetadata: Sendable {
+    public let name: String
+    public let type: GhostFileProviderNodeType
+    public let size: UInt64
+    public let mode: UInt32
+    public let uid: UInt32
+    public let gid: UInt32
+    public let objectID: UInt64
+    public let modifiedSeconds: Int64
+    public let modifiedNanoseconds: Int32
+    public let accessedSeconds: Int64?
+    public let accessedNanoseconds: Int32?
+    public let changedSeconds: Int64?
+    public let changedNanoseconds: Int32?
+    public let birthSeconds: Int64?
+    public let birthNanoseconds: Int32?
+    public let etag: String
+
+    public init(
+        name: String,
+        type: GhostFileProviderNodeType,
+        size: UInt64,
+        mode: UInt32,
+        uid: UInt32,
+        gid: UInt32,
+        objectID: UInt64,
+        modifiedSeconds: Int64,
+        modifiedNanoseconds: Int32,
+        accessedSeconds: Int64? = nil,
+        accessedNanoseconds: Int32? = nil,
+        changedSeconds: Int64? = nil,
+        changedNanoseconds: Int32? = nil,
+        birthSeconds: Int64? = nil,
+        birthNanoseconds: Int32? = nil,
+        etag: String
+    ) {
+        self.name = name
+        self.type = type
+        self.size = size
+        self.mode = mode
+        self.uid = uid
+        self.gid = gid
+        self.objectID = objectID
+        self.modifiedSeconds = modifiedSeconds
+        self.modifiedNanoseconds = modifiedNanoseconds
+        self.accessedSeconds = accessedSeconds
+        self.accessedNanoseconds = accessedNanoseconds
+        self.changedSeconds = changedSeconds
+        self.changedNanoseconds = changedNanoseconds
+        self.birthSeconds = birthSeconds
+        self.birthNanoseconds = birthNanoseconds
+        self.etag = etag
+    }
+}
+
+public enum GhostFileProviderRead: Sendable {
+    case data(Data)
+    case fileRegion(path: String, identity: String, offset: UInt64, length: Int)
+}
+
+public enum GhostFileProviderCreateType: Sendable {
+    case file
+    case directory
+}
+
+public struct GhostFileProviderAttributes: Sendable {
+    public let mode: UInt32?
+    public let size: UInt64?
+    public let modifiedSeconds: Int64?
+    public let modifiedNanoseconds: Int32?
+    public let accessedSeconds: Int64?
+    public let accessedNanoseconds: Int32?
+
+    public init(
+        mode: UInt32? = nil,
+        size: UInt64? = nil,
+        modifiedSeconds: Int64? = nil,
+        modifiedNanoseconds: Int32? = nil,
+        accessedSeconds: Int64? = nil,
+        accessedNanoseconds: Int32? = nil
+    ) {
+        self.mode = mode
+        self.size = size
+        self.modifiedSeconds = modifiedSeconds
+        self.modifiedNanoseconds = modifiedNanoseconds
+        self.accessedSeconds = accessedSeconds
+        self.accessedNanoseconds = accessedNanoseconds
+    }
+}
+
+public protocol GhostFileProvider: Sendable {
+    func metadata(path: String) async throws -> GhostFileProviderMetadata
+    func contentsOfDirectory(path: String) async throws -> [GhostFileProviderMetadata]
+    func read(path: String, offset: UInt64, length: Int) async throws -> GhostFileProviderRead
+    func readSymbolicLink(path: String) async throws -> String
+    func create(path: String, type: GhostFileProviderCreateType, mode: UInt32) async throws -> GhostFileProviderMetadata
+    func createSymbolicLink(path: String, destination: String) async throws -> GhostFileProviderMetadata
+    func write(path: String, offset: UInt64, data: Data) async throws -> GhostFileProviderMetadata
+    func setAttributes(path: String, attributes: GhostFileProviderAttributes) async throws -> GhostFileProviderMetadata
+    func remove(path: String) async throws
+    func rename(path: String, destinationPath: String) async throws -> GhostFileProviderMetadata
+}
diff --git a/macOS/GhostFileKit/GhostFileShareRouter.swift b/macOS/GhostFileKit/GhostFileShareRouter.swift
new file mode 100644
index 0000000..d2e98a9
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileShareRouter.swift
@@ -0,0 +1,419 @@
+import Foundation
+import GhostHTTP
+#if !GHOSTFILEKIT_BUILD
+import GhostFileKit
+#endif
+
+struct GhostFileHTTPResponse: Sendable {
+    var status: HTTPStatus
+    var headers: HTTPHeaders
+    var body: GhostFileHTTPResponseBody
+
+    init(
+        status: HTTPStatus,
+        headers: HTTPHeaders = HTTPHeaders(),
+        body: GhostFileHTTPResponseBody = .empty
+    ) {
+        self.status = status
+        self.headers = headers
+        self.body = body
+    }
+
+    init(
+        status: HTTPStatus,
+        headers: [String: String],
+        body: GhostFileHTTPResponseBody = .empty
+    ) {
+        self.init(status: status, headers: HTTPHeaders(headers), body: body)
+    }
+
+    static func text(_ string: String, status: HTTPStatus = .ok) -> GhostFileHTTPResponse {
+        GhostFileHTTPResponse(
+            status: status,
+            headers: ["Content-Type": "text/plain; charset=utf-8"],
+            body: .bytes(Data(string.utf8))
+        )
+    }
+}
+
+enum GhostFileHTTPResponseBody: Sendable {
+    case empty
+    case bytes(Data)
+    case fileRegion(path: String, identity: String, offset: UInt64, length: Int)
+
+    var contentLength: Int {
+        switch self {
+        case .empty:
+            return 0
+        case .bytes(let data):
+            return data.count
+        case .fileRegion(_, _, _, let length):
+            return length
+        }
+    }
+}
+
+final class GhostFileShareRouter: @unchecked Sendable {
+    let shareID: UUID
+    let shareName: String
+    let accessKey: String
+    private let provider: any GhostFileProvider
+    private let policyLock = NSLock()
+    private var storedReadOnly: Bool
+
+    init(rootURL: URL, shareID: UUID, shareName: String, accessKey: String, readOnly: Bool = true) {
+        self.provider = LocalFolderProvider(rootURL: rootURL)
+        self.shareID = shareID
+        self.shareName = shareName
+        self.accessKey = accessKey
+        self.storedReadOnly = readOnly
+    }
+
+    init(
+        provider: any GhostFileProvider,
+        shareID: UUID,
+        shareName: String,
+        accessKey: String,
+        readOnly: Bool = true
+    ) {
+        self.provider = provider
+        self.shareID = shareID
+        self.shareName = shareName
+        self.accessKey = accessKey
+        self.storedReadOnly = readOnly
+    }
+
+    var readOnly: Bool { policyLock.withLock { storedReadOnly } }
+
+    func setReadOnly(_ readOnly: Bool) {
+        policyLock.withLock { storedReadOnly = readOnly }
+    }
+
+    func route(_ request: HTTPRequestHead, body: Data = Data()) async -> GhostFileHTTPResponse {
+        guard request.header("authorization") == "Bearer \(accessKey)" else {
+            return responseError(.unauthorized, "A valid GhostFile access key is required")
+        }
+        guard let components = URLComponents(string: "http://ghostfile.local\(request.path)") else {
+            return responseError(.badRequest, "Malformed request URL")
+        }
+        let basePath = GhostFileProtocol.shareBasePath(id: shareID)
+        guard components.path.hasPrefix(basePath + "/") || components.path == basePath else {
+            return responseError(.notFound, "Share not found")
+        }
+
+        let operation = String(components.path.dropFirst(basePath.count))
+            .trimmingCharacters(in: CharacterSet(charactersIn: "/"))
+        if operation == "capabilities", request.method == .GET || request.method == .OPTIONS {
+            let isReadOnly = readOnly
+            let capabilities = GhostFileCapabilities(
+                protocolVersion: GhostFileProtocol.version,
+                shareID: shareID,
+                name: shareName,
+                readOnly: isReadOnly,
+                transports: [GhostFileProtocol.transport],
+                maximumReadLength: GhostFileProtocol.maximumReadLength
+            )
+            return json(capabilities, headers: [
+                "Allow": isReadOnly
+                    ? "OPTIONS, GET, HEAD"
+                    : "OPTIONS, GET, HEAD, POST, PATCH, DELETE",
+            ])
+        }
+        if operation == "health", request.method == .GET || request.method == .HEAD {
+            return GhostFileHTTPResponse(
+                status: .ok,
+                headers: ["Cache-Control": "no-store"],
+                body: request.method == .HEAD ? .empty : .bytes(Data("ok".utf8))
+            )
+        }
+
+        let relativePath = components.queryItems?.first(where: { $0.name == "path" })?.value ?? ""
+        guard GhostFilePath.validatedComponents(relativePath) != nil else {
+            return responseError(.badRequest, "Invalid or escaping relative path")
+        }
+
+        do {
+            let isMutation = request.method == .POST || request.method == .PATCH || request.method == .DELETE
+            if isMutation && readOnly {
+                return responseError(.methodNotAllowed, "This share is read-only")
+            }
+            switch (request.method, operation) {
+            case (.GET, "metadata"), (.HEAD, "metadata"):
+                let metadata = try await metadata(path: relativePath, displayName: relativePath.isEmpty ? shareName : nil)
+                if request.method == .HEAD {
+                    return GhostFileHTTPResponse(status: .ok, headers: ["ETag": metadata.etag])
+                }
+                return json(metadata, headers: ["ETag": metadata.etag])
+
+            case (.GET, "directory"):
+                let entries = try await provider.contentsOfDirectory(path: relativePath).map {
+                    metadata($0)
+                }
+                var inlineContents: [GhostFileInlineContent] = []
+                var inlineByteCount = 0
+                for entry in entries where entry.type == .file
+                    && entry.size <= UInt64(GhostFileProtocol.maximumInlineFileLength) {
+                    guard inlineContents.count < GhostFileProtocol.maximumInlineDirectoryFileCount else {
+                        break
+                    }
+                    let length = Int(entry.size)
+                    guard inlineByteCount + length <= GhostFileProtocol.maximumInlineDirectoryLength else {
+                        continue
+                    }
+                    let childPath = relativePath.isEmpty ? entry.name : "\(relativePath)/\(entry.name)"
+                    let data = try await data(from: provider.read(path: childPath, offset: 0, length: length))
+                    let currentMetadata = try await metadata(path: childPath)
+                    guard data.count == length, currentMetadata.etag == entry.etag else { continue }
+                    inlineContents.append(GhostFileInlineContent(
+                        name: entry.name,
+                        etag: entry.etag,
+                        data: data
+                    ))
+                    inlineByteCount += data.count
+                }
+                let listing = GhostFileDirectoryListing(
+                    path: relativePath,
+                    verifier: directoryVerifier(entries),
+                    entries: entries,
+                    inlineContents: inlineContents.isEmpty ? nil : inlineContents
+                )
+                return json(listing, headers: [
+                    "Cache-Control": "private, max-age=5",
+                    "ETag": "\"dir-\(String(listing.verifier, radix: 16))\"",
+                ])
+
+            case (.GET, "content"):
+                let metadata = try await metadata(path: relativePath)
+                guard metadata.type == .file else {
+                    return responseError(.badRequest, "Path is not a regular file")
+                }
+                guard metadata.size > 0 else {
+                    return GhostFileHTTPResponse(
+                        status: .ok,
+                        headers: ["Accept-Ranges": "bytes", "ETag": metadata.etag],
+                        body: .bytes(Data())
+                    )
+                }
+                guard let byteRange = GhostFileByteRange.parse(
+                    request.header("range"),
+                    fileSize: metadata.size,
+                    maximumLength: GhostFileProtocol.maximumReadLength
+                ) else {
+                    return GhostFileHTTPResponse(
+                        status: .rangeNotSatisfiable,
+                        headers: ["Content-Range": "bytes */\(metadata.size)"]
+                    )
+                }
+                return try await fileResponse(path: relativePath, metadata: metadata, byteRange: byteRange)
+
+            case (.GET, "readlink"):
+                return .text(try await provider.readSymbolicLink(path: relativePath))
+
+            case (.POST, "create"):
+                guard !relativePath.isEmpty,
+                      let create = try? JSONDecoder().decode(GhostFileCreateRequest.self, from: body) else {
+                    return responseError(.badRequest, "A valid create request is required")
+                }
+                let type: GhostFileProviderCreateType = create.type == .file ? .file : .directory
+                return json(metadata(try await provider.create(
+                    path: relativePath,
+                    type: type,
+                    mode: create.mode
+                )))
+
+            case (.POST, "symlink"):
+                guard !relativePath.isEmpty,
+                      let link = try? JSONDecoder().decode(GhostFileSymbolicLinkRequest.self, from: body),
+                      !link.destination.contains("\0") else {
+                    return responseError(.badRequest, "A valid symbolic-link request is required")
+                }
+                return json(metadata(try await provider.createSymbolicLink(
+                    path: relativePath,
+                    destination: link.destination
+                )))
+
+            case (.PATCH, "content"):
+                guard body.count <= GhostFileProtocol.maximumWriteLength,
+                      let offsetValue = request.header("x-ghostfile-offset"),
+                      let offset = UInt64(offsetValue), offset <= UInt64(Int64.max) else {
+                    return responseError(.badRequest, "A valid write offset and bounded body are required")
+                }
+                let updated = try await provider.write(path: relativePath, offset: offset, data: body)
+                return json(metadata(updated), headers: [
+                    "X-GhostFile-Bytes-Written": String(body.count),
+                ])
+
+            case (.PATCH, "attributes"):
+                guard let attributes = try? JSONDecoder().decode(
+                    GhostFileSetAttributesRequest.self,
+                    from: body
+                ) else {
+                    return responseError(.badRequest, "A valid attribute request is required")
+                }
+                let updated = try await provider.setAttributes(
+                    path: relativePath,
+                    attributes: GhostFileProviderAttributes(
+                        mode: attributes.mode,
+                        size: attributes.size,
+                        modifiedSeconds: attributes.modifiedSeconds,
+                        modifiedNanoseconds: attributes.modifiedNanoseconds,
+                        accessedSeconds: attributes.accessedSeconds,
+                        accessedNanoseconds: attributes.accessedNanoseconds
+                    )
+                )
+                return json(metadata(updated))
+
+            case (.DELETE, "remove"):
+                guard !relativePath.isEmpty else {
+                    return responseError(.badRequest, "The share root cannot be removed")
+                }
+                try await provider.remove(path: relativePath)
+                return GhostFileHTTPResponse(status: .noContent)
+
+            case (.POST, "rename"):
+                guard !relativePath.isEmpty,
+                      let rename = try? JSONDecoder().decode(GhostFileRenameRequest.self, from: body),
+                      !rename.destinationPath.isEmpty,
+                      GhostFilePath.validatedComponents(rename.destinationPath) != nil else {
+                    return responseError(.badRequest, "A valid contained rename destination is required")
+                }
+                return json(metadata(try await provider.rename(
+                    path: relativePath,
+                    destinationPath: rename.destinationPath
+                )))
+
+            default:
+                return responseError(.methodNotAllowed, "Operation not supported")
+            }
+        } catch let error as POSIXError {
+            switch error.code {
+            case .ENOENT: return responseError(.notFound, "Path not found", errno: error.code.rawValue)
+            case .EACCES, .EPERM: return responseError(.forbidden, "Access denied", errno: error.code.rawValue)
+            case .EEXIST, .ENOTEMPTY: return responseError(.conflict, error.localizedDescription, errno: error.code.rawValue)
+            case .ENOSPC: return responseError(.insufficientStorage, error.localizedDescription, errno: error.code.rawValue)
+            case .EINVAL, .EISDIR, .ENOTDIR: return responseError(.badRequest, error.localizedDescription, errno: error.code.rawValue)
+            default: return responseError(.internalServerError, error.localizedDescription, errno: error.code.rawValue)
+            }
+        } catch {
+            return responseError(.internalServerError, error.localizedDescription)
+        }
+    }
+
+    private func metadata(path: String, displayName: String? = nil) async throws -> GhostFileMetadata {
+        metadata(try await provider.metadata(path: path), displayName: displayName)
+    }
+
+    private func metadata(
+        _ value: GhostFileProviderMetadata,
+        displayName: String? = nil
+    ) -> GhostFileMetadata {
+        let type: GhostFileNodeType
+        switch value.type {
+        case .file: type = .file
+        case .directory: type = .directory
+        case .symbolicLink: type = .symbolicLink
+        case .other: type = .other
+        }
+        return GhostFileMetadata(
+            name: displayName ?? value.name,
+            type: type,
+            size: value.size,
+            mode: value.mode,
+            uid: value.uid,
+            gid: value.gid,
+            objectID: value.objectID,
+            modifiedSeconds: value.modifiedSeconds,
+            modifiedNanoseconds: value.modifiedNanoseconds,
+            accessedSeconds: value.accessedSeconds,
+            accessedNanoseconds: value.accessedNanoseconds,
+            changedSeconds: value.changedSeconds,
+            changedNanoseconds: value.changedNanoseconds,
+            birthSeconds: value.birthSeconds,
+            birthNanoseconds: value.birthNanoseconds,
+            etag: value.etag
+        )
+    }
+
+    private func data(from read: GhostFileProviderRead) async throws -> Data {
+        switch read {
+        case .data(let data):
+            return data
+        case .fileRegion(let path, _, let offset, let length):
+            let handle = try FileHandle(forReadingFrom: URL(fileURLWithPath: path))
+            defer { try? handle.close() }
+            try handle.seek(toOffset: offset)
+            return try handle.read(upToCount: length) ?? Data()
+        }
+    }
+
+    private func directoryVerifier(_ entries: [GhostFileMetadata]) -> UInt64 {
+        var value: UInt64 = 0xcbf2_9ce4_8422_2325
+        for entry in entries {
+            for byte in (entry.name + "\0" + entry.etag).utf8 {
+                value = (value ^ UInt64(byte)) &* 0x100_0000_01b3
+            }
+        }
+        return max(value, 1)
+    }
+
+    private func fileResponse(
+        path: String,
+        metadata: GhostFileMetadata,
+        byteRange: GhostFileByteRange
+    ) async throws -> GhostFileHTTPResponse {
+        let end = byteRange.offset + UInt64(byteRange.length) - 1
+        let read = try await provider.read(
+            path: path,
+            offset: byteRange.offset,
+            length: byteRange.length
+        )
+        let body: GhostFileHTTPResponseBody
+        switch read {
+        case .data(let data):
+            guard data.count == byteRange.length else { throw POSIXError(.EIO) }
+            body = .bytes(data)
+        case .fileRegion(let path, let identity, let offset, let length):
+            body = .fileRegion(path: path, identity: identity, offset: offset, length: length)
+        }
+        return GhostFileHTTPResponse(
+            status: .partialContent,
+            headers: [
+                "Content-Type": "application/octet-stream",
+                "Accept-Ranges": "bytes",
+                "Content-Range": "bytes \(byteRange.offset)-\(end)/\(metadata.size)",
+                "ETag": metadata.etag,
+            ],
+            body: body
+        )
+    }
+
+    private func json(
+        _ value: T,
+        headers: [String: String] = [:]
+    ) -> GhostFileHTTPResponse {
+        do {
+            var responseHeaders = headers
+            responseHeaders["Content-Type"] = "application/json"
+            return GhostFileHTTPResponse(
+                status: .ok,
+                headers: responseHeaders,
+                body: .bytes(try JSONEncoder().encode(value))
+            )
+        } catch {
+            return responseError(.internalServerError, "Failed to encode response")
+        }
+    }
+
+    private func responseError(
+        _ status: HTTPStatus,
+        _ message: String,
+        errno: Int32? = nil
+    ) -> GhostFileHTTPResponse {
+        let payload = (try? JSONEncoder().encode(GhostFileErrorPayload(error: message, errno: errno))) ?? Data()
+        return GhostFileHTTPResponse(
+            status: status,
+            headers: ["Content-Type": "application/json"],
+            body: .bytes(payload)
+        )
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileSystem.swift b/macOS/GhostFileKit/GhostFileSystem.swift
new file mode 100644
index 0000000..eb9eb26
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileSystem.swift
@@ -0,0 +1,66 @@
+import Foundation
+import FSKit
+
+public final class GhostFileSystem: FSUnaryFileSystem, FSUnaryFileSystemOperations {
+    public override init() {
+        super.init()
+    }
+
+    public func probeResource(resource: FSResource) async throws -> FSProbeResult {
+        guard let resource = resource as? FSGenericURLResource,
+              Self.validResourceURL(resource.url),
+              let shareID = Self.shareID(from: resource.url) else {
+            return .notRecognized
+        }
+        let mountID = GhostFileProtocol.mountInstanceID(from: resource.url) ?? shareID
+        return .usable(
+            name: "GhostFile",
+            containerID: FSContainerIdentifier(uuid: mountID)
+        )
+    }
+
+    public func loadResource(resource: FSResource, options: FSTaskOptions) async throws -> FSVolume {
+        guard let resource = resource as? FSGenericURLResource,
+              Self.validResourceURL(resource.url),
+              let shareID = Self.shareID(from: resource.url) else {
+            throw fs_errorForPOSIXError(ENOTSUP)
+        }
+        let mountID = GhostFileProtocol.mountInstanceID(from: resource.url) ?? shareID
+        let client = try GhostFileHTTP3Client(resourceURL: resource.url)
+        let capabilities = try await client.capabilities()
+        guard capabilities.protocolVersion == GhostFileProtocol.version,
+              capabilities.shareID == shareID else {
+            throw fs_errorForPOSIXError(ENOTSUP)
+        }
+        await client.startHealthMonitoring()
+        containerStatus = .ready
+        return GhostFileVolume(
+            // LiveFS performs its final connector lookup using this identity.
+            // Use the same unqualified per-mount UUID returned by probeResource.
+            volumeID: FSVolume.Identifier(uuid: mountID),
+            volumeName: FSFileName(string: capabilities.name),
+            client: client,
+            readOnly: capabilities.readOnly
+        )
+    }
+
+    public func unloadResource(resource: FSResource, options: FSTaskOptions) async throws {}
+
+    private static func validResourceURL(_ url: URL) -> Bool {
+        guard url.scheme == GhostFileProtocol.urlScheme,
+              url.host != nil,
+              url.port != nil,
+              let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+              components.queryItems?.contains(where: { $0.name == "access_key" && !($0.value ?? "").isEmpty }) == true,
+              GhostFileProtocol.peerPin(from: url) != nil else {
+            return false
+        }
+        return shareID(from: url) != nil
+    }
+
+    private static func shareID(from url: URL) -> UUID? {
+        let parts = url.path.split(separator: "/", omittingEmptySubsequences: true)
+        guard parts.count == 3, parts[0] == "v1", parts[1] == "shares" else { return nil }
+        return UUID(uuidString: String(parts[2]))
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileTLSIdentity.swift b/macOS/GhostFileKit/GhostFileTLSIdentity.swift
new file mode 100644
index 0000000..39e689e
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileTLSIdentity.swift
@@ -0,0 +1,105 @@
+import Crypto
+import Foundation
+import Security
+import X509
+
+public struct GhostFileTLSIdentity {
+    let networkIdentity: sec_identity_t
+    public let publicKeyPin: String
+    let certificatePEM: String
+    let privateKeyPEM: String
+    public let privateKeyRepresentation: Data
+
+    public static func make(privateKeyRepresentation storedKey: Data? = nil) throws -> Self {
+        let keyAttributes: [CFString: Any] = [
+            kSecAttrKeyType: kSecAttrKeyTypeECSECPrimeRandom,
+            kSecAttrKeySizeInBits: 256,
+        ]
+        let secKey: SecKey
+        if let storedKey {
+            var keyError: Unmanaged?
+            var importAttributes = keyAttributes
+            importAttributes[kSecAttrKeyClass] = kSecAttrKeyClassPrivate
+            guard let importedKey = SecKeyCreateWithData(
+                storedKey as CFData,
+                importAttributes as CFDictionary,
+                &keyError
+            ) else {
+                throw IdentityError.security(keyError?.takeRetainedValue())
+            }
+            secKey = importedKey
+        } else {
+            var keyError: Unmanaged?
+            guard let generatedKey = SecKeyCreateRandomKey(keyAttributes as CFDictionary, &keyError) else {
+                throw IdentityError.security(keyError?.takeRetainedValue())
+            }
+            secKey = generatedKey
+        }
+
+        var exportError: Unmanaged?
+        guard let externalKey = SecKeyCopyExternalRepresentation(secKey, &exportError) as Data? else {
+            throw IdentityError.security(exportError?.takeRetainedValue())
+        }
+        let signingKey = try P256.Signing.PrivateKey(x963Representation: externalKey)
+        let name = try DistinguishedName {
+            OrganizationName("GhostVM")
+            CommonName("GhostFile Local Share")
+        }
+        let certificate = try Certificate(
+            version: .v3,
+            serialNumber: .init(),
+            publicKey: .init(signingKey.publicKey),
+            notValidBefore: Date().addingTimeInterval(-300),
+            notValidAfter: Date().addingTimeInterval(365 * 24 * 60 * 60),
+            issuer: name,
+            subject: name,
+            signatureAlgorithm: .ecdsaWithSHA256,
+            extensions: try Certificate.Extensions {
+                Critical(BasicConstraints.notCertificateAuthority)
+            },
+            issuerPrivateKey: Certificate.PrivateKey(signingKey)
+        )
+        let secCertificate = try SecCertificate.makeWithCertificate(certificate)
+        guard let secIdentity = SecIdentityCreate(nil, secCertificate, secKey),
+              let networkIdentity = sec_identity_create(secIdentity) else {
+            throw IdentityError.couldNotCreateIdentity
+        }
+
+        guard let publicKey = SecKeyCopyPublicKey(secKey) else {
+            throw IdentityError.couldNotCreateIdentity
+        }
+        var publicKeyError: Unmanaged?
+        guard let publicKeyBytes = SecKeyCopyExternalRepresentation(
+            publicKey,
+            &publicKeyError
+        ) as Data? else {
+            throw IdentityError.security(publicKeyError?.takeRetainedValue())
+        }
+        let digest = SHA256.hash(data: publicKeyBytes)
+        let pin = "p256-sha256-" + Data(digest).base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+        return Self(
+            networkIdentity: networkIdentity,
+            publicKeyPin: pin,
+            certificatePEM: try certificate.serializeAsPEM().pemString,
+            privateKeyPEM: try Certificate.PrivateKey(signingKey).serializeAsPEM().pemString,
+            privateKeyRepresentation: externalKey
+        )
+    }
+
+    private enum IdentityError: LocalizedError {
+        case security(CFError?)
+        case couldNotCreateIdentity
+
+        var errorDescription: String? {
+            switch self {
+            case .security(let error):
+                return error.map { CFErrorCopyDescription($0) as String } ?? "Unable to create the GhostFile TLS key"
+            case .couldNotCreateIdentity:
+                return "Unable to create the GhostFile TLS identity"
+            }
+        }
+    }
+}
diff --git a/macOS/GhostFileKit/GhostFileVolume.swift b/macOS/GhostFileKit/GhostFileVolume.swift
new file mode 100644
index 0000000..f1cac40
--- /dev/null
+++ b/macOS/GhostFileKit/GhostFileVolume.swift
@@ -0,0 +1,457 @@
+import Foundation
+import FSKit
+
+final class GhostFileVolume: FSVolume, FSVolume.Operations, FSVolume.ReadWriteOperations {
+    private let client: GhostFileHTTP3Client
+    private let readOnly: Bool
+    private let itemLock = NSLock()
+    private var items: [UInt64: GhostFileItem] = [:]
+    private var rootItem: GhostFileItem?
+
+    init(
+        volumeID: FSVolume.Identifier,
+        volumeName: FSFileName,
+        client: GhostFileHTTP3Client,
+        readOnly: Bool
+    ) {
+        self.client = client
+        self.readOnly = readOnly
+        self.requestedMountOptions = readOnly ? .readOnly : []
+        super.init(volumeID: volumeID, volumeName: volumeName)
+    }
+
+    var supportedVolumeCapabilities: FSVolume.SupportedCapabilities {
+        let capabilities = FSVolume.SupportedCapabilities()
+        capabilities.supportsPersistentObjectIDs = false
+        capabilities.supports64BitObjectIDs = true
+        capabilities.supports2TBFiles = true
+        capabilities.supportsSymbolicLinks = true
+        capabilities.supportsHardLinks = false
+        capabilities.supportsFastStatFS = true
+        capabilities.doesNotSupportVolumeSizes = true
+        capabilities.caseFormat = .sensitive
+        return capabilities
+    }
+
+    var volumeStatistics: FSStatFSResult {
+        let result = FSStatFSResult(fileSystemTypeName: "ghostfile")
+        result.blockSize = 4096
+        result.ioSize = GhostFileProtocol.maximumReadLength
+        return result
+    }
+
+    var requestedMountOptions: FSVolume.MountOptions
+    var maximumLinkCount: Int { 1 }
+    var maximumNameLength: Int { 255 }
+    var restrictsOwnershipChanges: Bool { true }
+    var truncatesLongNames: Bool { false }
+    var maximumFileSize: UInt64 { UInt64(Int64.max) }
+
+    func mount(options: FSTaskOptions) async throws {}
+
+    func unmount() async {
+        await client.stopHealthMonitoring()
+        clearItems()
+    }
+
+    func synchronize(flags: FSSyncFlags) async throws {}
+
+    func activate(options: FSTaskOptions) async throws -> FSItem {
+        let existingRoot = itemLock.withLock { rootItem }
+        if let existingRoot { return existingRoot }
+
+        let metadata = try await client.metadata(path: "")
+        let candidate = GhostFileItem(relativePath: "", parentID: .parentOfRoot, metadata: metadata)
+        return itemLock.withLock {
+            if let rootItem { return rootItem }
+            rootItem = candidate
+            items[FSItem.Identifier.rootDirectory.rawValue] = candidate
+            return candidate
+        }
+    }
+
+    func deactivate(options: FSDeactivateOptions = []) async throws {
+        await client.stopHealthMonitoring()
+        clearItems()
+    }
+
+    func attributes(_ request: FSItem.GetAttributesRequest, of item: FSItem) async throws -> FSItem.Attributes {
+        let item = try ghostItem(item)
+        let metadata = try await client.metadata(path: item.relativePath)
+        item.update(metadata: metadata)
+        return attributes(for: item, request: request)
+    }
+
+    func setAttributes(_ newAttributes: FSItem.SetAttributesRequest, on item: FSItem) async throws -> FSItem.Attributes {
+        try ensureWritable()
+        let item = try ghostItem(item)
+        var consumed: FSItem.Attribute = []
+        let mode: UInt32? = newAttributes.isValid(.mode) ? newAttributes.mode : nil
+        if mode != nil { consumed.insert(.mode) }
+        let size: UInt64? = newAttributes.isValid(.size) ? newAttributes.size : nil
+        if size != nil { consumed.insert(.size) }
+        let modifyTime = newAttributes.isValid(.modifyTime) ? newAttributes.modifyTime : nil
+        if modifyTime != nil { consumed.insert(.modifyTime) }
+        let accessTime = newAttributes.isValid(.accessTime) ? newAttributes.accessTime : nil
+        if accessTime != nil { consumed.insert(.accessTime) }
+        let request = GhostFileSetAttributesRequest(
+            mode: mode,
+            size: size,
+            modifiedSeconds: modifyTime.map { Int64($0.tv_sec) },
+            modifiedNanoseconds: modifyTime.map { Int32($0.tv_nsec) },
+            accessedSeconds: accessTime.map { Int64($0.tv_sec) },
+            accessedNanoseconds: accessTime.map { Int32($0.tv_nsec) }
+        )
+        let metadata = try await client.setAttributes(path: item.relativePath, attributes: request)
+        item.update(metadata: metadata)
+        newAttributes.consumedAttributes = consumed
+        return attributes(for: item)
+    }
+
+    func lookupItem(named name: FSFileName, inDirectory directory: FSItem) async throws -> (FSItem, FSFileName) {
+        let directory = try ghostItem(directory)
+        guard directory.metadata.type == .directory,
+              let nameString = name.string,
+              isValidName(nameString) else {
+            throw fs_errorForPOSIXError(ENOENT)
+        }
+        let path = childPath(nameString, parent: directory.relativePath)
+        let metadata = try await client.metadata(path: path)
+        return (cachedItem(path: path, parent: identifier(for: directory), metadata: metadata), name)
+    }
+
+    func reclaimItem(_ item: FSItem) async throws {
+        guard let item = item as? GhostFileItem, !item.relativePath.isEmpty else { return }
+        let id = identifier(for: item).rawValue
+        itemLock.withLock {
+            if items[id] === item { items.removeValue(forKey: id) }
+        }
+    }
+
+    func readSymbolicLink(_ item: FSItem) async throws -> FSFileName {
+        let item = try ghostItem(item)
+        guard item.metadata.type == .symbolicLink else { throw fs_errorForPOSIXError(EINVAL) }
+        return FSFileName(string: try await client.readSymbolicLink(path: item.relativePath))
+    }
+
+    func createItem(
+        named name: FSFileName,
+        type: FSItem.ItemType,
+        inDirectory directory: FSItem,
+        attributes: FSItem.SetAttributesRequest
+    ) async throws -> (FSItem, FSFileName) {
+        try ensureWritable()
+        let directory = try ghostItem(directory)
+        guard directory.metadata.type == .directory,
+              let nameString = name.string,
+              isValidName(nameString) else {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+        let createType: GhostFileCreateType
+        let defaultMode: UInt32
+        switch type {
+        case .file:
+            createType = .file
+            defaultMode = 0o644
+        case .directory:
+            createType = .directory
+            defaultMode = 0o755
+        default:
+            throw fs_errorForPOSIXError(ENOTSUP)
+        }
+        let mode = attributes.isValid(.mode) ? attributes.mode : defaultMode
+        let path = childPath(nameString, parent: directory.relativePath)
+        let metadata = try await client.create(path: path, type: createType, mode: mode)
+        if attributes.isValid(.mode) { attributes.consumedAttributes.insert(.mode) }
+        return (
+            cachedItem(path: path, parent: identifier(for: directory), metadata: metadata),
+            name
+        )
+    }
+
+    func createSymbolicLink(
+        named name: FSFileName,
+        inDirectory directory: FSItem,
+        attributes: FSItem.SetAttributesRequest,
+        linkContents contents: FSFileName
+    ) async throws -> (FSItem, FSFileName) {
+        try ensureWritable()
+        let directory = try ghostItem(directory)
+        guard directory.metadata.type == .directory,
+              let nameString = name.string,
+              let linkContents = contents.string,
+              isValidName(nameString),
+              !linkContents.contains("\0") else {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+        let path = childPath(nameString, parent: directory.relativePath)
+        let metadata = try await client.createSymbolicLink(path: path, destination: linkContents)
+        return (
+            cachedItem(path: path, parent: identifier(for: directory), metadata: metadata),
+            name
+        )
+    }
+
+    func createLink(to item: FSItem, named name: FSFileName, inDirectory directory: FSItem) async throws -> FSFileName {
+        try ensureWritable()
+        throw fs_errorForPOSIXError(ENOTSUP)
+    }
+
+    func removeItem(_ item: FSItem, named name: FSFileName, fromDirectory directory: FSItem) async throws {
+        try ensureWritable()
+        let item = try ghostItem(item)
+        let directory = try ghostItem(directory)
+        guard let nameString = name.string,
+              isValidName(nameString),
+              item.relativePath == childPath(nameString, parent: directory.relativePath) else {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+        try await client.remove(path: item.relativePath)
+    }
+
+    func renameItem(
+        _ item: FSItem,
+        inDirectory sourceDirectory: FSItem,
+        named sourceName: FSFileName,
+        to destinationName: FSFileName,
+        inDirectory destinationDirectory: FSItem,
+        overItem: FSItem?
+    ) async throws -> FSFileName {
+        try ensureWritable()
+        let item = try ghostItem(item)
+        let sourceDirectory = try ghostItem(sourceDirectory)
+        let destinationDirectory = try ghostItem(destinationDirectory)
+        guard let sourceNameString = sourceName.string,
+              let destinationNameString = destinationName.string,
+              isValidName(sourceNameString),
+              isValidName(destinationNameString) else {
+            throw fs_errorForPOSIXError(EINVAL)
+        }
+        let sourcePath = childPath(sourceNameString, parent: sourceDirectory.relativePath)
+        guard sourcePath == item.relativePath else { throw fs_errorForPOSIXError(EINVAL) }
+        let destinationPath = childPath(destinationNameString, parent: destinationDirectory.relativePath)
+        let metadata = try await client.rename(path: sourcePath, destinationPath: destinationPath)
+        let destinationParentID = identifier(for: destinationDirectory)
+        itemLock.withLock {
+            if let overItem = overItem as? GhostFileItem {
+                items.removeValue(forKey: identifier(for: overItem).rawValue)
+            }
+            for cached in items.values {
+                let oldPath = cached.relativePath
+                if oldPath == sourcePath {
+                    cached.updateLocation(relativePath: destinationPath, parentID: destinationParentID)
+                    cached.update(metadata: metadata)
+                } else if oldPath.hasPrefix(sourcePath + "/") {
+                    cached.updateLocation(
+                        relativePath: destinationPath + oldPath.dropFirst(sourcePath.count),
+                        parentID: cached.parentID
+                    )
+                }
+            }
+        }
+        return destinationName
+    }
+
+    func enumerateDirectory(
+        _ directory: FSItem,
+        startingAt cookie: FSDirectoryCookie,
+        verifier suppliedVerifier: FSDirectoryVerifier,
+        attributes requestedAttributes: FSItem.GetAttributesRequest?,
+        packer: FSDirectoryEntryPacker
+    ) async throws -> FSDirectoryVerifier {
+        let directory = try ghostItem(directory)
+        let listing = try await client.directory(path: directory.relativePath)
+        let currentVerifier = FSDirectoryVerifier(max(listing.verifier, 1))
+        if suppliedVerifier != .initial && suppliedVerifier != currentVerifier {
+            throw invalidDirectoryCookieError()
+        }
+
+        let entries = listing.entries.filter { isValidName($0.name) }
+        let syntheticEntryCount = requestedAttributes == nil ? 2 : 0
+        let totalEntryCount = syntheticEntryCount + entries.count
+        let start = Int(cookie.rawValue)
+        guard start <= totalEntryCount else { throw invalidDirectoryCookieError() }
+
+        var cursor = start
+        while cursor < totalEntryCount {
+            let packed: Bool
+            if requestedAttributes == nil, cursor < 2 {
+                let isDot = cursor == 0
+                let itemID: FSItem.Identifier
+                if isDot || directory.relativePath.isEmpty {
+                    itemID = identifier(for: directory)
+                } else {
+                    itemID = directory.parentID
+                }
+                packed = packer.packEntry(
+                    name: FSFileName(string: isDot ? "." : ".."),
+                    itemType: .directory,
+                    itemID: itemID,
+                    nextCookie: FSDirectoryCookie(UInt64(cursor + 1)),
+                    attributes: nil
+                )
+            } else {
+                let metadata = entries[cursor - syntheticEntryCount]
+                let path = childPath(metadata.name, parent: directory.relativePath)
+                let child = cachedItem(path: path, parent: identifier(for: directory), metadata: metadata)
+                packed = packer.packEntry(
+                    name: FSFileName(string: metadata.name),
+                    itemType: itemType(metadata.type),
+                    itemID: identifier(for: child),
+                    nextCookie: FSDirectoryCookie(UInt64(cursor + 1)),
+                    attributes: requestedAttributes.map { attributes(for: child, request: $0) }
+                )
+            }
+            guard packed else { break }
+            cursor += 1
+        }
+        return currentVerifier
+    }
+
+    func read(
+        from item: FSItem,
+        at offset: off_t,
+        length: Int,
+        into buffer: FSMutableFileDataBuffer
+    ) async throws -> Int {
+        let item = try ghostItem(item)
+        guard offset >= 0, length >= 0 else { throw fs_errorForPOSIXError(EINVAL) }
+        guard item.metadata.type == .file else {
+            throw fs_errorForPOSIXError(item.metadata.type == .directory ? EISDIR : EINVAL)
+        }
+        let requestLength = min(length, GhostFileProtocol.maximumReadLength)
+        if requestLength == 0 { return 0 }
+        let data = try await client.read(path: item.relativePath, offset: UInt64(offset), length: requestLength)
+        return buffer.withUnsafeMutableBytes { destination in
+            let count = min(destination.count, data.count)
+            data.copyBytes(to: destination.bindMemory(to: UInt8.self), count: count)
+            return count
+        }
+    }
+
+    func write(contents: Data, to item: FSItem, at offset: off_t) async throws -> Int {
+        try ensureWritable()
+        let item = try ghostItem(item)
+        guard offset >= 0 else { throw fs_errorForPOSIXError(EINVAL) }
+        guard item.metadata.type == .file else {
+            throw fs_errorForPOSIXError(item.metadata.type == .directory ? EISDIR : EINVAL)
+        }
+        guard !contents.isEmpty else { return 0 }
+        let metadata = try await client.write(
+            path: item.relativePath,
+            offset: UInt64(offset),
+            data: contents
+        )
+        item.update(metadata: metadata)
+        return contents.count
+    }
+
+    private func ghostItem(_ item: FSItem) throws -> GhostFileItem {
+        guard let item = item as? GhostFileItem else { throw fs_errorForPOSIXError(ESTALE) }
+        return item
+    }
+
+    private func ensureWritable() throws {
+        if readOnly { throw fs_errorForPOSIXError(EROFS) }
+    }
+
+    private func cachedItem(path: String, parent: FSItem.Identifier, metadata: GhostFileMetadata) -> GhostFileItem {
+        let id = identifier(for: metadata).rawValue
+        itemLock.lock()
+        defer { itemLock.unlock() }
+        if let existing = items[id] {
+            existing.update(metadata: metadata)
+            return existing
+        }
+        let item = GhostFileItem(relativePath: path, parentID: parent, metadata: metadata)
+        items[id] = item
+        return item
+    }
+
+    private func clearItems() {
+        itemLock.lock()
+        items.removeAll()
+        rootItem = nil
+        itemLock.unlock()
+    }
+
+    private func attributes(
+        for item: GhostFileItem,
+        request: FSItem.GetAttributesRequest? = nil
+    ) -> FSItem.Attributes {
+        let metadata = item.metadata
+        let result = FSItem.Attributes()
+        func wanted(_ attribute: FSItem.Attribute) -> Bool {
+            request?.isAttributeWanted(attribute) ?? true
+        }
+        if wanted(.type) { result.type = itemType(metadata.type) }
+        if wanted(.mode) { result.mode = metadata.mode }
+        if wanted(.uid) { result.uid = metadata.uid }
+        if wanted(.gid) { result.gid = metadata.gid }
+        if wanted(.linkCount) { result.linkCount = 1 }
+        if wanted(.flags) { result.flags = 0 }
+        if wanted(.size) { result.size = metadata.size }
+        if wanted(.allocSize) { result.allocSize = metadata.size }
+        if wanted(.fileID) { result.fileID = identifier(for: item) }
+        if wanted(.parentID) { result.parentID = item.parentID }
+
+        let modifyTime = timestamp(
+            seconds: metadata.modifiedSeconds,
+            nanoseconds: metadata.modifiedNanoseconds
+        )
+        let accessTime = timestamp(
+            seconds: metadata.accessedSeconds ?? metadata.modifiedSeconds,
+            nanoseconds: metadata.accessedNanoseconds ?? metadata.modifiedNanoseconds
+        )
+        let changeTime = timestamp(
+            seconds: metadata.changedSeconds ?? metadata.modifiedSeconds,
+            nanoseconds: metadata.changedNanoseconds ?? metadata.modifiedNanoseconds
+        )
+        let birthTime = timestamp(
+            seconds: metadata.birthSeconds ?? metadata.modifiedSeconds,
+            nanoseconds: metadata.birthNanoseconds ?? metadata.modifiedNanoseconds
+        )
+        if wanted(.modifyTime) { result.modifyTime = modifyTime }
+        if wanted(.accessTime) { result.accessTime = accessTime }
+        if wanted(.changeTime) { result.changeTime = changeTime }
+        if wanted(.birthTime) { result.birthTime = birthTime }
+        if wanted(.addedTime) { result.addedTime = birthTime }
+        if wanted(.backupTime) { result.backupTime = timespec() }
+        if wanted(.supportsLimitedXAttrs) { result.supportsLimitedXAttrs = false }
+        if wanted(.inhibitKernelOffloadedIO) { result.inhibitKernelOffloadedIO = false }
+        return result
+    }
+
+    private func timestamp(seconds: Int64, nanoseconds: Int32) -> timespec {
+        timespec(tv_sec: Int(seconds), tv_nsec: Int(nanoseconds))
+    }
+
+    private func identifier(for item: GhostFileItem) -> FSItem.Identifier {
+        item.relativePath.isEmpty ? .rootDirectory : identifier(for: item.metadata)
+    }
+
+    private func identifier(for metadata: GhostFileMetadata) -> FSItem.Identifier {
+        FSItem.Identifier(rawValue: max(metadata.objectID, 3)) ?? .invalid
+    }
+
+    private func itemType(_ type: GhostFileNodeType) -> FSItem.ItemType {
+        switch type {
+        case .file: return .file
+        case .directory: return .directory
+        case .symbolicLink: return .symlink
+        case .other: return .unknown
+        }
+    }
+
+    private func childPath(_ child: String, parent: String) -> String {
+        parent.isEmpty ? child : "\(parent)/\(child)"
+    }
+
+    private func isValidName(_ name: String) -> Bool {
+        !name.isEmpty && name != "." && name != ".." && !name.contains("/") && !name.contains("\0")
+    }
+
+    private func invalidDirectoryCookieError() -> Error {
+        NSError(domain: FSKitErrorDomain, code: FSError.Code.invalidDirectoryCookie.rawValue)
+    }
+}
diff --git a/macOS/GhostFileKit/LocalFolderProvider.swift b/macOS/GhostFileKit/LocalFolderProvider.swift
new file mode 100644
index 0000000..f2ec5e4
--- /dev/null
+++ b/macOS/GhostFileKit/LocalFolderProvider.swift
@@ -0,0 +1,187 @@
+import Darwin
+import Foundation
+
+public final class LocalFolderProvider: GhostFileProvider, @unchecked Sendable {
+    public let rootURL: URL
+    private let resolvedRootURL: URL
+
+    public init(rootURL: URL) {
+        self.rootURL = rootURL.standardizedFileURL
+        self.resolvedRootURL = rootURL.resolvingSymlinksInPath().standardizedFileURL
+    }
+
+    public func metadata(path: String) async throws -> GhostFileProviderMetadata {
+        try fileMetadata(at: resolvedURL(path: path, followFinalSymbolicLink: false))
+    }
+
+    public func contentsOfDirectory(path: String) async throws -> [GhostFileProviderMetadata] {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: true)
+        return try FileManager.default.contentsOfDirectory(atPath: url.path).sorted().map {
+            try fileMetadata(at: url.appendingPathComponent($0, isDirectory: false))
+        }
+    }
+
+    public func read(path: String, offset: UInt64, length: Int) async throws -> GhostFileProviderRead {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: true)
+        let metadata = try fileMetadata(at: url)
+        guard metadata.type == .file else { throw POSIXError(.EINVAL) }
+        return .fileRegion(path: url.path, identity: metadata.etag, offset: offset, length: length)
+    }
+
+    public func readSymbolicLink(path: String) async throws -> String {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: false)
+        var info = stat()
+        guard Darwin.lstat(url.path, &info) == 0 else { throw POSIXError.current() }
+        guard info.st_mode & S_IFMT == S_IFLNK else { throw POSIXError(.EINVAL) }
+        return try FileManager.default.destinationOfSymbolicLink(atPath: url.path)
+    }
+
+    public func create(path: String, type: GhostFileProviderCreateType, mode: UInt32) async throws -> GhostFileProviderMetadata {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: false)
+        let permissions = mode_t(mode & 0o7777)
+        switch type {
+        case .file:
+            let descriptor = Darwin.open(url.path, O_WRONLY | O_CREAT | O_EXCL, permissions)
+            guard descriptor >= 0 else { throw POSIXError.current() }
+            guard Darwin.close(descriptor) == 0 else { throw POSIXError.current() }
+        case .directory:
+            guard Darwin.mkdir(url.path, permissions) == 0 else { throw POSIXError.current() }
+        }
+        return try fileMetadata(at: url)
+    }
+
+    public func createSymbolicLink(path: String, destination: String) async throws -> GhostFileProviderMetadata {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: false)
+        guard Darwin.symlink(destination, url.path) == 0 else { throw POSIXError.current() }
+        return try fileMetadata(at: url)
+    }
+
+    public func write(path: String, offset: UInt64, data: Data) async throws -> GhostFileProviderMetadata {
+        guard offset <= UInt64(Int64.max) else { throw POSIXError(.EOVERFLOW) }
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: true)
+        var info = stat()
+        guard Darwin.lstat(url.path, &info) == 0 else { throw POSIXError.current() }
+        guard info.st_mode & S_IFMT == S_IFREG else { throw POSIXError(.EINVAL) }
+        let descriptor = Darwin.open(url.path, O_WRONLY)
+        guard descriptor >= 0 else { throw POSIXError.current() }
+        defer { Darwin.close(descriptor) }
+        var written = 0
+        try data.withUnsafeBytes { bytes in
+            while written < bytes.count {
+                let result = Darwin.pwrite(
+                    descriptor,
+                    bytes.baseAddress?.advanced(by: written),
+                    bytes.count - written,
+                    off_t(offset) + off_t(written)
+                )
+                if result < 0, errno == EINTR { continue }
+                guard result > 0 else { throw POSIXError.current() }
+                written += result
+            }
+        }
+        return try fileMetadata(at: url)
+    }
+
+    public func setAttributes(path: String, attributes: GhostFileProviderAttributes) async throws -> GhostFileProviderMetadata {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: true)
+        if let size = attributes.size {
+            guard size <= UInt64(Int64.max), Darwin.truncate(url.path, off_t(size)) == 0 else {
+                throw POSIXError.current()
+            }
+        }
+        if let mode = attributes.mode, Darwin.chmod(url.path, mode_t(mode & 0o7777)) != 0 {
+            throw POSIXError.current()
+        }
+        if attributes.modifiedSeconds != nil || attributes.accessedSeconds != nil {
+            func requestedTime(seconds: Int64?, nanoseconds: Int32?) -> timespec {
+                guard let seconds else { return timespec(tv_sec: 0, tv_nsec: Int(UTIME_OMIT)) }
+                return timespec(tv_sec: Int(seconds), tv_nsec: Int(nanoseconds ?? 0))
+            }
+            let times = [
+                requestedTime(seconds: attributes.accessedSeconds, nanoseconds: attributes.accessedNanoseconds),
+                requestedTime(seconds: attributes.modifiedSeconds, nanoseconds: attributes.modifiedNanoseconds),
+            ]
+            let result = times.withUnsafeBufferPointer {
+                Darwin.utimensat(AT_FDCWD, url.path, $0.baseAddress, 0)
+            }
+            guard result == 0 else { throw POSIXError.current() }
+        }
+        return try fileMetadata(at: url)
+    }
+
+    public func remove(path: String) async throws {
+        let url = try resolvedURL(path: path, followFinalSymbolicLink: false)
+        var info = stat()
+        guard Darwin.lstat(url.path, &info) == 0 else { throw POSIXError.current() }
+        let result = info.st_mode & S_IFMT == S_IFDIR ? Darwin.rmdir(url.path) : Darwin.unlink(url.path)
+        guard result == 0 else { throw POSIXError.current() }
+    }
+
+    public func rename(path: String, destinationPath: String) async throws -> GhostFileProviderMetadata {
+        let source = try resolvedURL(path: path, followFinalSymbolicLink: false)
+        let destination = try resolvedURL(path: destinationPath, followFinalSymbolicLink: false)
+        guard Darwin.rename(source.path, destination.path) == 0 else { throw POSIXError.current() }
+        return try fileMetadata(at: destination)
+    }
+
+    private func resolvedURL(path: String, followFinalSymbolicLink: Bool) throws -> URL {
+        guard !path.contains("\0"), !path.hasPrefix("/") else { throw POSIXError(.EINVAL) }
+        let components = path.split(separator: "/", omittingEmptySubsequences: true)
+        guard !components.contains(where: { $0 == "." || $0 == ".." }) else { throw POSIXError(.EINVAL) }
+        if components.isEmpty { return rootURL }
+        let candidate = components.reduce(rootURL) {
+            $0.appendingPathComponent(String($1), isDirectory: false)
+        }.standardizedFileURL
+        let containmentCandidate = followFinalSymbolicLink
+            ? candidate.resolvingSymlinksInPath().standardizedFileURL
+            : candidate.deletingLastPathComponent().resolvingSymlinksInPath().standardizedFileURL
+        let rootPath = resolvedRootURL.path
+        guard containmentCandidate.path == rootPath || containmentCandidate.path.hasPrefix(rootPath + "/") else {
+            throw POSIXError(.EINVAL)
+        }
+        return candidate
+    }
+
+    private func fileMetadata(at url: URL) throws -> GhostFileProviderMetadata {
+        var info = stat()
+        guard Darwin.lstat(url.path, &info) == 0 else { throw POSIXError.current() }
+        let type: GhostFileProviderNodeType
+        switch info.st_mode & S_IFMT {
+        case S_IFREG: type = .file
+        case S_IFDIR: type = .directory
+        case S_IFLNK: type = .symbolicLink
+        default: type = .other
+        }
+        let objectID = UInt64(info.st_ino) ^ (UInt64(info.st_dev) &* 0x9E37_79B9_7F4A_7C15)
+        let modifiedSeconds = Int64(info.st_mtimespec.tv_sec)
+        let modifiedNanoseconds = Int32(info.st_mtimespec.tv_nsec)
+        let etagValue = objectID
+            ^ UInt64(max(0, info.st_size))
+            ^ UInt64(bitPattern: modifiedSeconds)
+            ^ UInt64(bitPattern: Int64(modifiedNanoseconds))
+        return GhostFileProviderMetadata(
+            name: url.lastPathComponent,
+            type: type,
+            size: UInt64(max(0, info.st_size)),
+            mode: UInt32(info.st_mode),
+            uid: info.st_uid,
+            gid: info.st_gid,
+            objectID: max(objectID, 3),
+            modifiedSeconds: modifiedSeconds,
+            modifiedNanoseconds: modifiedNanoseconds,
+            accessedSeconds: Int64(info.st_atimespec.tv_sec),
+            accessedNanoseconds: Int32(info.st_atimespec.tv_nsec),
+            changedSeconds: Int64(info.st_ctimespec.tv_sec),
+            changedNanoseconds: Int32(info.st_ctimespec.tv_nsec),
+            birthSeconds: Int64(info.st_birthtimespec.tv_sec),
+            birthNanoseconds: Int32(info.st_birthtimespec.tv_nsec),
+            etag: "\"node-\(String(etagValue, radix: 16))\""
+        )
+    }
+}
+
+private extension POSIXError {
+    static func current() -> POSIXError {
+        POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+    }
+}
diff --git a/macOS/GhostFileTests/GhostFileProtocolTests.swift b/macOS/GhostFileTests/GhostFileProtocolTests.swift
new file mode 100644
index 0000000..ea158e2
--- /dev/null
+++ b/macOS/GhostFileTests/GhostFileProtocolTests.swift
@@ -0,0 +1,865 @@
+import Combine
+import Foundation
+import GhostHTTP
+import XCTest
+@testable import GhostFile
+@testable import GhostFileKit
+
+final class GhostFileProtocolTests: XCTestCase {
+    func testMountInstancesIdentifyOtherwiseIdenticalNetworkVolumes() throws {
+        let first = UUID(uuidString: "11111111-2222-3333-4444-555555555555")!
+        let second = UUID(uuidString: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")!
+        let base = "ghostfile://example.local:443/v1/shares/99999999-8888-7777-6666-555555555555"
+        let firstURL = try XCTUnwrap(URL(string: "\(base)?mount_instance=\(first.uuidString)"))
+        let secondURL = try XCTUnwrap(URL(string: "\(base)?mount_instance=\(second.uuidString)"))
+
+        XCTAssertEqual(GhostFileProtocol.mountInstanceID(from: firstURL), first)
+        XCTAssertEqual(GhostFileProtocol.mountInstanceID(from: secondURL), second)
+        XCTAssertNotEqual(
+            GhostFileProtocol.mountInstanceID(from: firstURL),
+            GhostFileProtocol.mountInstanceID(from: secondURL)
+        )
+        XCTAssertNil(GhostFileProtocol.mountInstanceID(from: try XCTUnwrap(URL(string: base))))
+    }
+
+    func testRelativePathValidationRejectsEscapes() {
+        XCTAssertEqual(GhostFilePath.validatedComponents("folder/file.txt"), ["folder", "file.txt"])
+        XCTAssertEqual(GhostFilePath.validatedComponents(""), [])
+        XCTAssertNil(GhostFilePath.validatedComponents("../secret"))
+        XCTAssertNil(GhostFilePath.validatedComponents("folder/../secret"))
+        XCTAssertNil(GhostFilePath.validatedComponents("/absolute"))
+        XCTAssertNil(GhostFilePath.validatedComponents("bad\0name"))
+    }
+
+    func testByteRangeIsBoundedToProtocolMaximum() {
+        XCTAssertEqual(
+            GhostFileByteRange.parse("bytes=4-9", fileSize: 20, maximumLength: 1024),
+            .init(offset: 4, length: 6)
+        )
+        XCTAssertEqual(
+            GhostFileByteRange.parse("bytes=10-", fileSize: 100, maximumLength: 8),
+            .init(offset: 10, length: 8)
+        )
+        XCTAssertNil(GhostFileByteRange.parse("bytes=20-30", fileSize: 20, maximumLength: 8))
+        XCTAssertNil(GhostFileByteRange.parse("items=0-1", fileSize: 20, maximumLength: 8))
+    }
+}
+
+final class GhostFileMountHealthTests: XCTestCase {
+    private let mountID = UUID(uuidString: "11111111-2222-3333-4444-555555555555")!
+
+    func testHeartbeatSilenceOnlyDegradesHealthyMount() {
+        let initial = snapshot(state: .online)
+        XCTAssertEqual(initial.applying(.heartbeatMissed).state, .degraded)
+
+        let errored = initial.applying(.operationFailed, detail: "timed out")
+        XCTAssertEqual(errored.applying(.heartbeatMissed).state, .error)
+
+        let offline = initial.applying(.peerClosed)
+        XCTAssertEqual(offline.applying(.heartbeatMissed).state, .offline)
+    }
+
+    func testRealOperationFailureAndExplicitCloseRemainDistinct() {
+        let initial = snapshot(state: .online)
+        XCTAssertEqual(initial.applying(.operationFailed).state, .error)
+        XCTAssertEqual(initial.applying(.peerClosed).state, .offline)
+    }
+
+    func testSuccessfulTrafficRestoresOnlineState() {
+        XCTAssertEqual(snapshot(state: .degraded).applying(.heartbeatSucceeded).state, .online)
+        XCTAssertEqual(snapshot(state: .error).applying(.operationSucceeded).state, .online)
+        XCTAssertEqual(snapshot(state: .offline).applying(.heartbeatSucceeded).state, .online)
+    }
+
+    func testStaleOnlineSnapshotBecomesDegradedButNeverOffline() {
+        let updatedAt = Date(timeIntervalSince1970: 1_000)
+        let initial = GhostFileMountHealthSnapshot(
+            mountID: mountID,
+            state: .online,
+            detail: nil,
+            updatedAt: updatedAt
+        )
+        XCTAssertEqual(
+            initial.degradingIfStale(
+                at: updatedAt.addingTimeInterval(GhostFileProtocol.heartbeatStaleAfter + 1)
+            ).state,
+            .degraded
+        )
+    }
+
+    private func snapshot(state: GhostFileMountHealthState) -> GhostFileMountHealthSnapshot {
+        GhostFileMountHealthSnapshot(
+            mountID: mountID,
+            state: state,
+            detail: nil,
+            updatedAt: Date(timeIntervalSince1970: 1_000)
+        )
+    }
+}
+
+final class GhostFileBonjourLeaseTests: XCTestCase {
+    func testDiscoveredShareProvidesStableDisplayMetadataAndWindowValue() throws {
+        let id = UUID(uuidString: "11111111-2222-3333-4444-555555555555")!
+        let share = DiscoveredGhostFileShare(
+            id: id,
+            name: "Studio Mac",
+            host: "studio.local",
+            port: 8049,
+            readOnly: true,
+            transport: GhostFileProtocol.transport,
+            publicKeyPin: "test-pin"
+        )
+
+        XCTAssertEqual(share.serviceType, "_ghostfile._udp")
+        XCTAssertEqual(share.url?.host, "studio.local")
+        XCTAssertEqual(share.url?.port, 8049)
+        XCTAssertTrue(try XCTUnwrap(share.url?.absoluteString).contains(id.uuidString))
+
+        let encoded = try JSONEncoder().encode(share)
+        XCTAssertEqual(try JSONDecoder().decode(DiscoveredGhostFileShare.self, from: encoded), share)
+    }
+
+    func testDiscoveryVisibilityHidesSelfSharesUnlessEnabled() {
+        let localID = UUID(uuidString: "11111111-2222-3333-4444-555555555555")!
+        let remoteID = UUID(uuidString: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")!
+        let shares = [
+            DiscoveredGhostFileShare(
+                id: localID,
+                name: "This Mac",
+                host: "this-mac.local",
+                port: 8049,
+                readOnly: true,
+                transport: GhostFileProtocol.transport,
+                publicKeyPin: "local-pin"
+            ),
+            DiscoveredGhostFileShare(
+                id: remoteID,
+                name: "Nearby Mac",
+                host: "nearby.local",
+                port: 8050,
+                readOnly: true,
+                transport: GhostFileProtocol.transport,
+                publicKeyPin: "remote-pin"
+            )
+        ]
+
+        XCTAssertEqual(
+            GhostFileDiscoveryVisibility.visibleShares(
+                from: shares,
+                localShareIDs: [localID],
+                discoverSelfShares: false
+            ).map(\.id),
+            [remoteID]
+        )
+        XCTAssertEqual(
+            GhostFileDiscoveryVisibility.visibleShares(
+                from: shares,
+                localShareIDs: [localID],
+                discoverSelfShares: true
+            ),
+            shares
+        )
+    }
+
+    func testAdvertisedTTLIsShortAndHeartbeatRefreshesBeforeExpiry() {
+        XCTAssertEqual(GhostFileBonjourLease.advertisedTTL, 6)
+        XCTAssertLessThan(
+            GhostFileBonjourLease.heartbeatInterval,
+            .seconds(GhostFileBonjourLease.advertisedTTL)
+        )
+    }
+
+    func testTTLParsingBoundsUntrustedAdvertisements() {
+        XCTAssertEqual(GhostFileBonjourLease.ttl(from: [:]), 15)
+        XCTAssertEqual(GhostFileBonjourLease.ttl(from: ["ttl": Data("1".utf8)]), 4)
+        XCTAssertEqual(GhostFileBonjourLease.ttl(from: ["ttl": Data("6".utf8)]), 6)
+        XCTAssertEqual(GhostFileBonjourLease.ttl(from: ["ttl": Data("600".utf8)]), 60)
+        XCTAssertEqual(GhostFileBonjourLease.ttl(from: ["ttl": Data("invalid".utf8)]), 15)
+    }
+
+    func testLeaseExpiresAtAdvertisedTTL() {
+        let lastSeen = Date(timeIntervalSince1970: 1_000)
+        let ttl = GhostFileBonjourLease.advertisedTTL
+        XCTAssertFalse(GhostFileBonjourLease.isExpired(
+            lastSeen: lastSeen,
+            ttl: ttl,
+            now: lastSeen.addingTimeInterval(ttl - 0.001)
+        ))
+        XCTAssertTrue(GhostFileBonjourLease.isExpired(
+            lastSeen: lastSeen,
+            ttl: ttl,
+            now: lastSeen.addingTimeInterval(ttl)
+        ))
+    }
+}
+
+@MainActor
+final class GhostFileLibraryTests: XCTestCase {
+    func testShareDefinitionRejectsEmptyAccessKey() throws {
+        let library = GhostFileLibrary(
+            configurationStorage: MemoryConfigurationStorage(),
+            accessKeyStorage: MemoryAccessKeyStorage(),
+            tlsPrivateKeyStorage: MemoryTLSPrivateKeyStorage()
+        )
+        let folder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-empty-key-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: folder) }
+
+        XCTAssertThrowsError(try library.addShare(
+            folderURL: folder,
+            name: "Invalid",
+            accessKey: "   "
+        ))
+        XCTAssertTrue(library.shares.isEmpty)
+    }
+
+    func testSharesPersistWithStableIdentityAndDeleteCleanly() throws {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-library-tests-\(UUID().uuidString)", isDirectory: true)
+        let sharedFolder = root.appendingPathComponent("Shared Folder", isDirectory: true)
+        let storageURL = root.appendingPathComponent("shares.json")
+        try FileManager.default.createDirectory(at: sharedFolder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+
+        let configurationStorage = GhostFileShareJSONStorage(fileURL: storageURL)
+        let keyStorage = MemoryAccessKeyStorage()
+        let identityStorage = MemoryTLSPrivateKeyStorage()
+        let library = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage
+        )
+        let saved = try library.addShare(
+            folderURL: sharedFolder,
+            name: "Test Share",
+            preferredPort: 8049,
+            accessKey: "test-key"
+        )
+
+        let reloaded = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage
+        )
+        XCTAssertEqual(reloaded.shares.map(\.id), [saved.id])
+        XCTAssertEqual(reloaded.shares.first?.name, "Test Share")
+        XCTAssertEqual(reloaded.shares.first?.preferredPort, 8049)
+        XCTAssertEqual(try keyStorage.accessKey(for: saved.id), "test-key")
+        XCTAssertEqual(
+            try library.publicKeyPin(for: saved.id),
+            try reloaded.publicKeyPin(for: saved.id)
+        )
+
+        reloaded.delete([saved.id])
+
+        let afterDelete = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage
+        )
+        XCTAssertTrue(afterDelete.shares.isEmpty)
+        XCTAssertNil(try keyStorage.accessKey(for: saved.id))
+        XCTAssertNil(try identityStorage.privateKey(for: saved.id))
+    }
+
+    func testStartAndStopUseSavedShareIDAndPublishLiveStatus() throws {
+        let sharedFolder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-runtime-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: sharedFolder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: sharedFolder) }
+
+        let configurationStorage = MemoryConfigurationStorage()
+        let keyStorage = MemoryAccessKeyStorage()
+        let identityStorage = MemoryTLSPrivateKeyStorage()
+        var runtimes: [UUID: FakeShareRuntime] = [:]
+        var observedIdentityPins: [String] = []
+        let library = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage,
+            serverFactory: { share, _, _, identity in
+                let runtime = FakeShareRuntime()
+                runtimes[share.id] = runtime
+                observedIdentityPins.append(identity.publicKeyPin)
+                return runtime
+            }
+        )
+        let saved = try library.addShare(
+            folderURL: sharedFolder,
+            name: "Runtime Test",
+            accessKey: "runtime-key"
+        )
+
+        XCTAssertEqual(library.status(for: saved.id), .stopped)
+        library.start(saved.id)
+        XCTAssertEqual(library.status(for: saved.id), .online)
+        XCTAssertNotNil(runtimes[saved.id])
+        XCTAssertEqual(runtimes[saved.id]?.preferredPort, saved.preferredPort)
+        let firstRuntime = try XCTUnwrap(runtimes[saved.id])
+
+        library.stop(saved.id)
+        XCTAssertEqual(library.status(for: saved.id), .stopped)
+        XCTAssertEqual(firstRuntime.stopCount, 1)
+
+        library.start(saved.id)
+        XCTAssertEqual(observedIdentityPins.count, 2)
+        XCTAssertEqual(observedIdentityPins[0], observedIdentityPins[1])
+    }
+
+    func testExplicitIdentityRotationInvalidatesOldFingerprint() throws {
+        let sharedFolder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-rotation-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: sharedFolder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: sharedFolder) }
+
+        let library = GhostFileLibrary(
+            configurationStorage: MemoryConfigurationStorage(),
+            accessKeyStorage: MemoryAccessKeyStorage(),
+            tlsPrivateKeyStorage: MemoryTLSPrivateKeyStorage()
+        )
+        let saved = try library.addShare(
+            folderURL: sharedFolder,
+            name: "Rotation Test",
+            accessKey: "rotation-key"
+        )
+        let oldPin = try library.publicKeyPin(for: saved.id)
+
+        library.rotateTLSIdentity(for: saved.id)
+
+        XCTAssertNotEqual(try library.publicKeyPin(for: saved.id), oldPin)
+    }
+
+    func testReadOnlyChangePersistsAndUpdatesRunningServerImmediately() throws {
+        let sharedFolder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-access-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: sharedFolder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: sharedFolder) }
+
+        let configurationStorage = MemoryConfigurationStorage()
+        let keyStorage = MemoryAccessKeyStorage()
+        let identityStorage = MemoryTLSPrivateKeyStorage()
+        var runtime: FakeShareRuntime?
+        let library = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage,
+            serverFactory: { _, _, _, _ in
+                let created = FakeShareRuntime()
+                runtime = created
+                return created
+            }
+        )
+        let saved = try library.addShare(
+            folderURL: sharedFolder,
+            name: "Access Test",
+            accessKey: "access-key"
+        )
+        library.start(saved.id)
+
+        library.setReadOnly(false, for: saved.id)
+
+        XCTAssertEqual(library.share(withID: saved.id)?.readOnly, false)
+        XCTAssertEqual(runtime?.readOnlyValues, [false])
+        let reloaded = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage
+        )
+        XCTAssertEqual(reloaded.share(withID: saved.id)?.readOnly, false)
+    }
+
+    func testEditingRunningShareRestartsWithUpdatedConfiguration() throws {
+        let folder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-edit-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: folder) }
+
+        let configurationStorage = MemoryConfigurationStorage()
+        let keyStorage = MemoryAccessKeyStorage()
+        let identityStorage = MemoryTLSPrivateKeyStorage()
+        var runtimes: [FakeShareRuntime] = []
+        let library = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage,
+            serverFactory: { _, _, _, _ in
+                let runtime = FakeShareRuntime()
+                runtimes.append(runtime)
+                return runtime
+            }
+        )
+        let saved = try library.addShare(folderURL: folder, name: "Before", accessKey: "old-key")
+        library.start(saved.id)
+
+        try library.updateShare(
+            saved.id,
+            name: "After",
+            preferredPort: 9000,
+            accessKey: "new-key"
+        )
+
+        XCTAssertEqual(library.share(withID: saved.id)?.name, "After")
+        XCTAssertEqual(library.share(withID: saved.id)?.preferredPort, 9000)
+        XCTAssertEqual(try library.accessKey(for: saved.id), "new-key")
+        XCTAssertEqual(runtimes.count, 2)
+        XCTAssertEqual(runtimes.first?.stopCount, 1)
+        XCTAssertEqual(library.status(for: saved.id), .online)
+    }
+
+    func testFailedRunningShareEditRollsBackAndRestartsOriginal() throws {
+        let folder = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-edit-rollback-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: folder) }
+
+        let configurationStorage = MemoryConfigurationStorage()
+        let keyStorage = MemoryAccessKeyStorage()
+        let identityStorage = MemoryTLSPrivateKeyStorage()
+        var runtimes: [FakeShareRuntime] = []
+        let library = GhostFileLibrary(
+            configurationStorage: configurationStorage,
+            accessKeyStorage: keyStorage,
+            tlsPrivateKeyStorage: identityStorage,
+            serverFactory: { _, _, _, _ in
+                let runtime = FakeShareRuntime()
+                runtimes.append(runtime)
+                return runtime
+            }
+        )
+        let saved = try library.addShare(folderURL: folder, name: "Original", accessKey: "old-key")
+        library.start(saved.id)
+        configurationStorage.failSaves = true
+
+        XCTAssertThrowsError(try library.updateShare(
+            saved.id,
+            name: "Should Roll Back",
+            preferredPort: 9999,
+            accessKey: "new-key"
+        ))
+
+        XCTAssertEqual(library.share(withID: saved.id)?.name, "Original")
+        XCTAssertEqual(try library.accessKey(for: saved.id), "old-key")
+        XCTAssertEqual(runtimes.count, 2)
+        XCTAssertEqual(runtimes.first?.stopCount, 1)
+        XCTAssertEqual(library.status(for: saved.id), .online)
+    }
+}
+
+@MainActor
+final class GhostFileMountLibraryTests: XCTestCase {
+    func testMountDefinitionPersistsSanitizedURLAndKeySeparately() async throws {
+        let storage = MemoryMountConfigurationStorage()
+        let keys = MemoryAccessKeyStorage()
+        let library = GhostFileMountLibrary(
+            configurationStorage: storage,
+            accessKeyStorage: keys
+        )
+        let shareID = UUID()
+        let mountInstance = UUID()
+        let saved = try library.addMount(
+            name: "Build Cache",
+            sourceURL: "ghostfile://build.local:8049/v1/shares/\(shareID.uuidString)?tls_pin=pin&access_key=secret&mount_instance=\(mountInstance.uuidString)",
+            accessKey: "separate-key"
+        )
+
+        XCTAssertEqual(saved.shareID, shareID)
+        XCTAssertFalse(saved.sourceURL.contains("access_key"))
+        XCTAssertFalse(saved.sourceURL.contains("mount_instance"))
+        XCTAssertTrue(saved.sourceURL.contains("tls_pin=pin"))
+        XCTAssertEqual(try library.accessKey(for: saved.id), "separate-key")
+
+        let reloaded = GhostFileMountLibrary(
+            configurationStorage: storage,
+            accessKeyStorage: keys
+        )
+        XCTAssertEqual(reloaded.mounts, [saved])
+
+        await reloaded.delete([saved.id])
+        XCTAssertTrue(reloaded.mounts.isEmpty)
+        XCTAssertNil(try keys.accessKey(for: saved.id))
+    }
+
+    func testMountDefinitionRejectsNonGhostFileURL() {
+        let library = GhostFileMountLibrary(
+            configurationStorage: MemoryMountConfigurationStorage(),
+            accessKeyStorage: MemoryAccessKeyStorage()
+        )
+        XCTAssertThrowsError(try library.addMount(
+            name: "Invalid",
+            sourceURL: "https://example.com/share",
+            accessKey: "key"
+        ))
+    }
+
+    func testMountDefinitionRejectsEmptyAccessKey() {
+        let library = GhostFileMountLibrary(
+            configurationStorage: MemoryMountConfigurationStorage(),
+            accessKeyStorage: MemoryAccessKeyStorage()
+        )
+        XCTAssertThrowsError(try library.addMount(
+            name: "Invalid",
+            sourceURL: "ghostfile://example.local/v1/shares/\(UUID().uuidString)",
+            accessKey: "   "
+        ))
+    }
+}
+
+private final class MemoryConfigurationStorage: GhostFileShareConfigurationStorage {
+    private var savedShares: [SavedGhostFileShare] = []
+    var failSaves = false
+
+    func load() throws -> [SavedGhostFileShare] { savedShares }
+    func save(_ shares: [SavedGhostFileShare]) throws {
+        if failSaves { throw MemoryStorageError.saveFailed }
+        savedShares = shares
+    }
+}
+
+private final class MemoryMountConfigurationStorage: GhostFileMountConfigurationStorage {
+    private var savedMounts: [SavedGhostFileMount] = []
+
+    func load() throws -> [SavedGhostFileMount] { savedMounts }
+    func save(_ mounts: [SavedGhostFileMount]) throws { savedMounts = mounts }
+}
+
+private enum MemoryStorageError: Error {
+    case saveFailed
+}
+
+private final class MemoryAccessKeyStorage: GhostFileAccessKeyStorage {
+    private var keys: [UUID: String] = [:]
+
+    func accessKey(for shareID: UUID) throws -> String? { keys[shareID] }
+    func setAccessKey(_ accessKey: String, for shareID: UUID) throws { keys[shareID] = accessKey }
+    func removeAccessKey(for shareID: UUID) throws { keys[shareID] = nil }
+}
+
+private final class MemoryTLSPrivateKeyStorage: GhostFileTLSPrivateKeyStorage {
+    private var keys: [UUID: Data] = [:]
+
+    func privateKey(for shareID: UUID) throws -> Data? { keys[shareID] }
+    func setPrivateKey(_ privateKey: Data, for shareID: UUID) throws { keys[shareID] = privateKey }
+    func removePrivateKey(for shareID: UUID) throws { keys[shareID] = nil }
+}
+
+@MainActor
+private final class FakeShareRuntime: ObservableObject, GhostFileShareRuntime {
+    @Published var isRunning = false
+    var shareURL: URL?
+    var requestCount = 0
+    var preferredPort: UInt16?
+    var stopCount = 0
+    var readOnlyValues: [Bool] = []
+
+    func start(preferredPort: UInt16) throws {
+        self.preferredPort = preferredPort
+        isRunning = true
+    }
+
+    func stop() {
+        stopCount += 1
+        isRunning = false
+    }
+
+    func setReadOnly(_ readOnly: Bool) {
+        readOnlyValues.append(readOnly)
+    }
+}
+
+final class GhostFileShareRouterTests: XCTestCase {
+    private var directory: URL!
+    private var router: GhostFileShareRouter!
+    private let shareID = UUID(uuidString: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")!
+    private let accessKey = "demo-access-key"
+
+    override func setUpWithError() throws {
+        directory = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        try Data("abcdefghij".utf8).write(to: directory.appendingPathComponent("sample.txt"))
+        try FileManager.default.createDirectory(
+            at: directory.appendingPathComponent("folder", isDirectory: true),
+            withIntermediateDirectories: true
+        )
+        router = GhostFileShareRouter(
+            rootURL: directory,
+            shareID: shareID,
+            shareName: "DemoShare",
+            accessKey: accessKey
+        )
+    }
+
+    override func tearDownWithError() throws {
+        try? FileManager.default.removeItem(at: directory)
+    }
+
+    func testCapabilitiesRequireAccessKey() async throws {
+        let path = "\(GhostFileProtocol.shareBasePath(id: shareID))/capabilities"
+        let unauthorized = await router.route(.init(method: .GET, path: path))
+        XCTAssertEqual(unauthorized.status, .unauthorized)
+
+        let authorized = await router.route(request(method: .GET, path: path))
+        XCTAssertEqual(authorized.status, .ok)
+        let capabilities = try JSONDecoder().decode(GhostFileCapabilities.self, from: bodyData(authorized))
+        XCTAssertEqual(capabilities.shareID, shareID)
+        XCTAssertTrue(capabilities.readOnly)
+        XCTAssertEqual(capabilities.transports, [GhostFileProtocol.transport])
+    }
+
+    func testHealthIsAuthenticatedAndDoesNotTouchTheSharedFolder() async throws {
+        let path = "\(GhostFileProtocol.shareBasePath(id: shareID))/health"
+        let unauthorized = await router.route(.init(method: .GET, path: path))
+        XCTAssertEqual(unauthorized.status, .unauthorized)
+
+        let response = await router.route(request(method: .GET, path: path))
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertEqual(String(data: try bodyData(response), encoding: .utf8), "ok")
+        XCTAssertEqual(response.headers["Cache-Control"], "no-store")
+    }
+
+    func testMetadataAndDirectoryListing() async throws {
+        let metadataResponse = await router.route(request(
+            method: .GET,
+            path: operationPath("metadata", relativePath: "sample.txt")
+        ))
+        XCTAssertEqual(metadataResponse.status, .ok)
+        let metadata = try JSONDecoder().decode(GhostFileMetadata.self, from: bodyData(metadataResponse))
+        XCTAssertEqual(metadata.name, "sample.txt")
+        XCTAssertEqual(metadata.type, .file)
+        XCTAssertEqual(metadata.size, 10)
+
+        let listingResponse = await router.route(request(
+            method: .GET,
+            path: operationPath("directory", relativePath: "")
+        ))
+        XCTAssertEqual(listingResponse.status, .ok)
+        let listing = try JSONDecoder().decode(GhostFileDirectoryListing.self, from: bodyData(listingResponse))
+        XCTAssertEqual(listing.entries.map(\.name), ["folder", "sample.txt"])
+        XCTAssertNotEqual(listing.verifier, 0)
+        XCTAssertEqual(listing.inlineContents?.map(\.name), ["sample.txt"])
+        XCTAssertEqual(listing.inlineContents?.first?.data, Data("abcdefghij".utf8))
+        XCTAssertEqual(listing.inlineContents?.first?.etag, listing.entries.last?.etag)
+    }
+
+    func testDirectoryListingBoundsInlineContent() async throws {
+        let oversized = Data(repeating: 0x41, count: GhostFileProtocol.maximumInlineFileLength + 1)
+        try oversized.write(to: directory.appendingPathComponent("oversized.bin"))
+
+        let listingResponse = await router.route(request(
+            method: .GET,
+            path: operationPath("directory", relativePath: "")
+        ))
+        XCTAssertEqual(listingResponse.status, .ok)
+        let listing = try JSONDecoder().decode(GhostFileDirectoryListing.self, from: bodyData(listingResponse))
+        XCTAssertTrue(listing.entries.contains(where: { $0.name == "oversized.bin" }))
+        XCTAssertFalse(listing.inlineContents?.contains(where: { $0.name == "oversized.bin" }) ?? false)
+    }
+
+    func testRangeReadStreamsOnlyRequestedBytes() async throws {
+        let response = await router.route(request(
+            method: .GET,
+            path: operationPath("content", relativePath: "sample.txt"),
+            extraHeaders: ["Range": "bytes=2-5"]
+        ))
+        XCTAssertEqual(response.status, .partialContent)
+        XCTAssertEqual(response.headers["Content-Range"], "bytes 2-5/10")
+        XCTAssertEqual(String(data: try bodyData(response), encoding: .utf8), "cdef")
+    }
+
+    func testTraversalIsRejected() async {
+        let response = await router.route(request(
+            method: .GET,
+            path: operationPath("metadata", relativePath: "../secret")
+        ))
+        XCTAssertEqual(response.status, .badRequest)
+    }
+
+    func testReadOnlyPolicyRejectsMutationAndCanChangeLive() async throws {
+        let createPath = operationPath("create", relativePath: "created.txt")
+        let payload = try JSONEncoder().encode(
+            GhostFileCreateRequest(type: .file, mode: 0o640)
+        )
+        let rejectedCreate = await router.route(request(method: .POST, path: createPath), body: payload)
+        XCTAssertEqual(rejectedCreate.status, .methodNotAllowed)
+        XCTAssertFalse(FileManager.default.fileExists(atPath: directory.appendingPathComponent("created.txt").path))
+
+        router.setReadOnly(false)
+        let capabilitiesPath = "\(GhostFileProtocol.shareBasePath(id: shareID))/capabilities"
+        let capabilitiesResponse = await router.route(request(method: .GET, path: capabilitiesPath))
+        let capabilities = try JSONDecoder().decode(
+            GhostFileCapabilities.self,
+            from: bodyData(capabilitiesResponse)
+        )
+        XCTAssertFalse(capabilities.readOnly)
+        let acceptedCreate = await router.route(request(method: .POST, path: createPath), body: payload)
+        XCTAssertEqual(acceptedCreate.status, .ok)
+    }
+
+    func testWritableMutationsCreateWriteResizeRenameSymlinkAndRemove() async throws {
+        router.setReadOnly(false)
+
+        let createDirectory = try JSONEncoder().encode(
+            GhostFileCreateRequest(type: .directory, mode: 0o750)
+        )
+        let createDirectoryResponse = await router.route(
+            request(method: .POST, path: operationPath("create", relativePath: "new")),
+            body: createDirectory
+        )
+        XCTAssertEqual(createDirectoryResponse.status, .ok)
+
+        let createFile = try JSONEncoder().encode(
+            GhostFileCreateRequest(type: .file, mode: 0o640)
+        )
+        let createResponse = await router.route(
+            request(method: .POST, path: operationPath("create", relativePath: "new/data.bin")),
+            body: createFile
+        )
+        XCTAssertEqual(createResponse.status, .ok)
+        let created = try JSONDecoder().decode(GhostFileMetadata.self, from: bodyData(createResponse))
+
+        let writeResponse = await router.route(
+            request(
+                method: .PATCH,
+                path: operationPath("content", relativePath: "new/data.bin"),
+                extraHeaders: ["X-GhostFile-Offset": "3"]
+            ),
+            body: Data("hello".utf8)
+        )
+        XCTAssertEqual(writeResponse.status, .ok)
+        XCTAssertEqual(
+            try Data(contentsOf: directory.appendingPathComponent("new/data.bin")),
+            Data([0, 0, 0]) + Data("hello".utf8)
+        )
+
+        let attributes = try JSONEncoder().encode(
+            GhostFileSetAttributesRequest(mode: 0o600, size: 5)
+        )
+        let attributesResponse = await router.route(
+            request(method: .PATCH, path: operationPath("attributes", relativePath: "new/data.bin")),
+            body: attributes
+        )
+        XCTAssertEqual(attributesResponse.status, .ok)
+        XCTAssertEqual(
+            try Data(contentsOf: directory.appendingPathComponent("new/data.bin")),
+            Data([0, 0, 0]) + Data("he".utf8)
+        )
+
+        let rename = try JSONEncoder().encode(
+            GhostFileRenameRequest(destinationPath: "new/renamed.bin")
+        )
+        let renameResponse = await router.route(
+            request(method: .POST, path: operationPath("rename", relativePath: "new/data.bin")),
+            body: rename
+        )
+        XCTAssertEqual(renameResponse.status, .ok)
+        let renamed = try JSONDecoder().decode(GhostFileMetadata.self, from: bodyData(renameResponse))
+        XCTAssertEqual(renamed.objectID, created.objectID, "Renaming must preserve filesystem identity")
+
+        let link = try JSONEncoder().encode(GhostFileSymbolicLinkRequest(destination: "renamed.bin"))
+        let linkResponse = await router.route(
+            request(method: .POST, path: operationPath("symlink", relativePath: "new/link")),
+            body: link
+        )
+        XCTAssertEqual(linkResponse.status, .ok)
+        let readLink = await router.route(request(
+            method: .GET,
+            path: operationPath("readlink", relativePath: "new/link")
+        ))
+        XCTAssertEqual(String(data: try bodyData(readLink), encoding: .utf8), "renamed.bin")
+
+        let removeLink = await router.route(request(
+            method: .DELETE,
+            path: operationPath("remove", relativePath: "new/link")
+        ))
+        XCTAssertEqual(removeLink.status, .noContent)
+        let removeFile = await router.route(request(
+            method: .DELETE,
+            path: operationPath("remove", relativePath: "new/renamed.bin")
+        ))
+        XCTAssertEqual(removeFile.status, .noContent)
+        let removeDirectory = await router.route(request(
+            method: .DELETE,
+            path: operationPath("remove", relativePath: "new")
+        ))
+        XCTAssertEqual(removeDirectory.status, .noContent)
+        XCTAssertFalse(FileManager.default.fileExists(atPath: directory.appendingPathComponent("new").path))
+    }
+
+    func testWritableMutationsRejectEscapingDestinationsAndConflicts() async throws {
+        router.setReadOnly(false)
+        let createFile = try JSONEncoder().encode(
+            GhostFileCreateRequest(type: .file, mode: 0o600)
+        )
+        let existing = operationPath("create", relativePath: "sample.txt")
+        let conflict = await router.route(request(method: .POST, path: existing), body: createFile)
+        XCTAssertEqual(conflict.status, .conflict)
+        XCTAssertEqual(
+            try JSONDecoder().decode(GhostFileErrorPayload.self, from: bodyData(conflict)).errno,
+            EEXIST
+        )
+
+        let escapingRename = try JSONEncoder().encode(
+            GhostFileRenameRequest(destinationPath: "../escaped.txt")
+        )
+        let escapingRenameResponse = await router.route(
+            request(method: .POST, path: operationPath("rename", relativePath: "sample.txt")),
+            body: escapingRename
+        )
+        XCTAssertEqual(escapingRenameResponse.status, .badRequest)
+    }
+
+    private func request(
+        method: HTTPMethod,
+        path: String,
+        extraHeaders: [String: String] = [:]
+    ) -> HTTPRequestHead {
+        var headers = extraHeaders
+        headers["Authorization"] = "Bearer \(accessKey)"
+        return HTTPRequestHead(method: method, path: path, headers: HTTPHeaders(headers))
+    }
+
+    private func operationPath(_ operation: String, relativePath: String) -> String {
+        "\(GhostFileProtocol.shareBasePath(id: shareID))/\(operation)?\(GhostFilePath.percentEncodedQuery(relativePath))"
+    }
+
+    private func bodyData(_ response: GhostFileHTTPResponse) throws -> Data {
+        switch response.body {
+        case .empty:
+            return Data()
+        case .bytes(let data):
+            return data
+        case .fileRegion(let path, _, let offset, let length):
+            let handle = try FileHandle(forReadingFrom: URL(fileURLWithPath: path))
+            defer { try? handle.close() }
+            try handle.seek(toOffset: offset)
+            return try XCTUnwrap(handle.read(upToCount: length))
+        }
+    }
+}
+
+final class GhostFileTLSIdentityTests: XCTestCase {
+    func testCreatesRestorablePublicKeyIdentity() throws {
+        let identity = try GhostFileTLSIdentity.make()
+        let restored = try GhostFileTLSIdentity.make(
+            privateKeyRepresentation: identity.privateKeyRepresentation
+        )
+        XCTAssertEqual(identity.publicKeyPin, restored.publicKeyPin)
+        XCTAssertTrue(identity.publicKeyPin.hasPrefix("p256-sha256-"))
+        XCTAssertFalse(identity.publicKeyPin.contains("="))
+        XCTAssertTrue(GhostFileProtocol.validPublicKeyPin(identity.publicKeyPin))
+    }
+
+    func testParsesNewAndLegacyPeerPinsWithoutAmbiguity() throws {
+        let identity = try GhostFileTLSIdentity.make()
+        let id = UUID(uuidString: "11111111-2222-3333-4444-555555555555")!
+        let base = "ghostfile://example.local:8049/v1/shares/\(id.uuidString)"
+        let modern = try XCTUnwrap(URL(string: "\(base)?pk=\(identity.publicKeyPin)"))
+        let legacy = try XCTUnwrap(URL(string: "\(base)?tls_pin=legacy-certificate-pin"))
+        let ambiguous = try XCTUnwrap(URL(string: "\(base)?pk=\(identity.publicKeyPin)&pk=\(identity.publicKeyPin)"))
+
+        XCTAssertEqual(GhostFileProtocol.peerPin(from: modern), .publicKey(identity.publicKeyPin))
+        XCTAssertEqual(GhostFileProtocol.peerPin(from: legacy), .legacyCertificate("legacy-certificate-pin"))
+        XCTAssertNil(GhostFileProtocol.peerPin(from: ambiguous))
+    }
+}
diff --git a/macOS/GhostFileTests/GhostFileQUICIntegrationTests.swift b/macOS/GhostFileTests/GhostFileQUICIntegrationTests.swift
new file mode 100644
index 0000000..1dbc313
--- /dev/null
+++ b/macOS/GhostFileTests/GhostFileQUICIntegrationTests.swift
@@ -0,0 +1,1526 @@
+import Foundation
+import Network
+import XCTest
+@testable import GhostFile
+@testable import GhostFileKit
+
+final class GhostFileHTTP3IntegrationTests: XCTestCase {
+    func testInstalledGhostVMFSMountReadsLiveLoopbackShare() async throws {
+        let extensionURL = URL(
+            fileURLWithPath: "/Applications/GhostVM.app/Contents/Extensions/GhostVMFS.appex",
+            isDirectory: true
+        )
+        guard FileManager.default.fileExists(atPath: extensionURL.path) else {
+            throw XCTSkip("GhostVMFS is not installed")
+        }
+
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostvm-fskit-mount-tests-\(UUID().uuidString)", isDirectory: true)
+        let mountPoint = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostvm-fskit-mounted-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try FileManager.default.createDirectory(at: mountPoint, withIntermediateDirectories: true)
+        try Data("mounted through GhostVMFS".utf8)
+            .write(to: fixture.appendingPathComponent("proof.txt"))
+        defer {
+            try? FileManager.default.removeItem(at: fixture)
+            try? FileManager.default.removeItem(at: mountPoint)
+        }
+
+        let accessKey = "ghostvm-fskit-mount-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostVMFSMountTest",
+                accessKey: accessKey,
+                readOnly: true,
+                visibility: .loopbackOnly,
+                advertisesBonjour: false
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        var components = try XCTUnwrap(URLComponents(url: shareURL, resolvingAgainstBaseURL: false))
+        components.queryItems = (components.queryItems ?? []) + [
+            URLQueryItem(name: "access_key", value: accessKey),
+            URLQueryItem(name: "mount_instance", value: UUID().uuidString.lowercased()),
+        ]
+        let resourceURL = try XCTUnwrap(components.url)
+
+        let mount = Process()
+        let mountOutput = Pipe()
+        mount.executableURL = URL(fileURLWithPath: "/sbin/mount")
+        mount.arguments = [
+            "-F", "-t", "ghostvm",
+            "-o", "rdonly,nobrowse,nodev,nosuid",
+            resourceURL.absoluteString,
+            mountPoint.path,
+        ]
+        mount.standardOutput = mountOutput
+        mount.standardError = mountOutput
+        try mount.run()
+        mount.waitUntilExit()
+        let mountDetail = String(
+            data: mountOutput.fileHandleForReading.readDataToEndOfFile(),
+            encoding: .utf8
+        ) ?? ""
+        XCTAssertEqual(mount.terminationStatus, 0, mountDetail)
+        guard mount.terminationStatus == 0 else { return }
+        defer {
+            let unmount = Process()
+            unmount.executableURL = URL(fileURLWithPath: "/sbin/umount")
+            unmount.arguments = [mountPoint.path]
+            try? unmount.run()
+            unmount.waitUntilExit()
+        }
+
+        XCTAssertEqual(
+            try String(contentsOf: mountPoint.appendingPathComponent("proof.txt"), encoding: .utf8),
+            "mounted through GhostVMFS"
+        )
+    }
+
+    func testLoopbackOnlyShareProducesAuthenticatedReadOnlyResource() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-loopback-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = UUID().uuidString
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "LoopbackTest",
+                accessKey: accessKey,
+                readOnly: true,
+                visibility: .loopbackOnly,
+                advertisesBonjour: false
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        XCTAssertEqual(shareURL.host, "127.0.0.1")
+        XCTAssertNotEqual(shareURL.port, 0)
+        let resourceURL = try loopbackResourceURL(shareURL: shareURL, accessKey: accessKey)
+        let client = try GhostFileHTTP3Client(resourceURL: resourceURL)
+        let capabilities = try await client.capabilities()
+        XCTAssertTrue(capabilities.readOnly)
+    }
+
+    func testWritableShareMutatesFilesEndToEndAndSwitchesReadOnlyLive() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-write-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "write-integration-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "WritableTest",
+                accessKey: accessKey,
+                readOnly: false
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey)
+        )
+        let writableCapabilities = try await client.capabilities()
+        XCTAssertFalse(writableCapabilities.readOnly)
+
+        _ = try await client.create(path: "folder", type: .directory, mode: 0o750)
+        let created = try await client.create(path: "folder/data.bin", type: .file, mode: 0o640)
+        let payload = Data((0..<(2 * GhostFileProtocol.maximumWriteLength + 123)).map { UInt8($0 & 0xff) })
+        _ = try await client.write(path: "folder/data.bin", offset: 0, data: payload)
+        XCTAssertEqual(try Data(contentsOf: fixture.appendingPathComponent("folder/data.bin")), payload)
+
+        _ = try await client.create(path: "folder/concurrent.bin", type: .file, mode: 0o640)
+        let concurrentChunks = (0..<3).map { index in
+            Data(repeating: UInt8(0x40 + index), count: GhostFileProtocol.maximumWriteLength)
+        }
+        try await withThrowingTaskGroup(of: Void.self) { group in
+            for (index, chunk) in concurrentChunks.enumerated() {
+                group.addTask {
+                    _ = try await client.write(
+                        path: "folder/concurrent.bin",
+                        offset: UInt64(index * GhostFileProtocol.maximumWriteLength),
+                        data: chunk
+                    )
+                }
+            }
+            try await group.waitForAll()
+        }
+        XCTAssertEqual(
+            try Data(contentsOf: fixture.appendingPathComponent("folder/concurrent.bin")),
+            concurrentChunks.reduce(into: Data()) { $0.append($1) }
+        )
+        try await client.remove(path: "folder/concurrent.bin")
+
+        _ = try await client.setAttributes(
+            path: "folder/data.bin",
+            attributes: GhostFileSetAttributesRequest(mode: 0o600, size: 257)
+        )
+        XCTAssertEqual(
+            try FileManager.default.attributesOfItem(
+                atPath: fixture.appendingPathComponent("folder/data.bin").path
+            )[.size] as? NSNumber,
+            NSNumber(value: 257)
+        )
+
+        let renamed = try await client.rename(
+            path: "folder/data.bin",
+            destinationPath: "folder/renamed.bin"
+        )
+        XCTAssertEqual(renamed.objectID, created.objectID)
+        _ = try await client.createSymbolicLink(path: "folder/link", destination: "renamed.bin")
+        let linkDestination = try await client.readSymbolicLink(path: "folder/link")
+        XCTAssertEqual(linkDestination, "renamed.bin")
+        let remoteContents = try await client.read(
+            path: "folder/renamed.bin",
+            offset: 0,
+            length: 257
+        )
+        XCTAssertEqual(remoteContents, payload.prefix(257))
+
+        try await client.remove(path: "folder/link")
+        try await client.remove(path: "folder/renamed.bin")
+        try await client.remove(path: "folder")
+        XCTAssertFalse(FileManager.default.fileExists(atPath: fixture.appendingPathComponent("folder").path))
+
+        await MainActor.run { server.setReadOnly(true) }
+        let readOnlyCapabilities = try await client.capabilities()
+        XCTAssertTrue(readOnlyCapabilities.readOnly)
+        do {
+            _ = try await client.create(path: "must-not-exist", type: .file, mode: 0o600)
+            XCTFail("A live read-only share accepted a create")
+        } catch let error as NSError {
+            XCTAssertEqual(error.domain, NSPOSIXErrorDomain)
+            XCTAssertEqual(error.code, Int(EROFS))
+        }
+        XCTAssertFalse(FileManager.default.fileExists(atPath: fixture.appendingPathComponent("must-not-exist").path))
+    }
+
+    func testPublishedShareURLConnectsThroughResolvedBonjourHost() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-share-url-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "bonjour-share-url-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "URLTest-\(UUID().uuidString)",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        guard var components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false) else {
+            throw TestError.missingShareURL
+        }
+        components.queryItems = (components.queryItems ?? []) + [
+            URLQueryItem(name: "access_key", value: accessKey)
+        ]
+        let resourceURL = try XCTUnwrap(components.url)
+        let client = try GhostFileHTTP3Client(resourceURL: resourceURL)
+        let capabilities = try await client.capabilities()
+        let expectedShareID = await MainActor.run { server.shareID }
+
+        XCTAssertEqual(capabilities.shareID, expectedShareID)
+        XCTAssertEqual(shareURL.host?.hasSuffix(".local"), true)
+        XCTAssertNotEqual(shareURL.host, "connectivity-check.warp-svc.local")
+    }
+
+    func testMismatchedPublicKeyPinRejectsPeerBeforeAccessKeyIsSent() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-pin-mismatch-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "must-not-cross-an-untrusted-connection"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "PinMismatchTest",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        var resourceComponents = try XCTUnwrap(URLComponents(
+            url: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey),
+            resolvingAgainstBaseURL: false
+        ))
+        let unrelatedIdentity = try GhostFileTLSIdentity.make()
+        resourceComponents.queryItems = resourceComponents.queryItems?.map { item in
+            item.name == GhostFileProtocol.publicKeyPinQueryName
+                ? URLQueryItem(name: item.name, value: unrelatedIdentity.publicKeyPin)
+                : item
+        }
+        let client = try GhostFileHTTP3Client(
+            resourceURL: try XCTUnwrap(resourceComponents.url),
+            connectionTimeout: .seconds(2),
+            requestTimeout: .seconds(2)
+        )
+
+        do {
+            _ = try await client.capabilities()
+            XCTFail("A client accepted a server with the wrong public key")
+        } catch {}
+        let receivedRequestCount = await MainActor.run { server.requestCount }
+        XCTAssertEqual(receivedRequestCount, 0, "The access key was sent before peer authentication")
+    }
+
+    func testSavedLinkSurvivesCertificateReissueWithPersistentPrivateKey() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-persistent-identity-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let shareID = UUID()
+        let accessKey = "persistent-identity-key"
+        let initialIdentity = try GhostFileTLSIdentity.make()
+        let storedPrivateKey = initialIdentity.privateKeyRepresentation
+        let firstServer = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "PersistentIdentityTest",
+                accessKey: accessKey,
+                shareID: shareID,
+                tlsIdentity: initialIdentity
+            )
+            try server.start()
+            return server
+        }
+        let savedShareURL = try await waitForShareURL(firstServer)
+        let firstClient = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: savedShareURL, accessKey: accessKey)
+        )
+        let firstCapabilities = try await firstClient.capabilities()
+        XCTAssertEqual(firstCapabilities.shareID, shareID)
+
+        await MainActor.run { firstServer.stop() }
+        try await waitForShareToStop(firstServer)
+
+        // Reissue a new self-signed certificate from the persisted per-share
+        // private key. The old saved link must still authenticate it.
+        let reissuedIdentity = try GhostFileTLSIdentity.make(
+            privateKeyRepresentation: storedPrivateKey
+        )
+        XCTAssertNotEqual(initialIdentity.certificatePEM, reissuedIdentity.certificatePEM)
+        XCTAssertEqual(initialIdentity.publicKeyPin, reissuedIdentity.publicKeyPin)
+        let savedPort = try XCTUnwrap(savedShareURL.port).magnitude
+        let secondServer = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "PersistentIdentityTest",
+                accessKey: accessKey,
+                shareID: shareID,
+                tlsIdentity: reissuedIdentity
+            )
+            try server.start(preferredPort: UInt16(savedPort))
+            return server
+        }
+        defer { Task { @MainActor in secondServer.stop() } }
+        _ = try await waitForShareURL(secondServer)
+
+        let reconnectedClient = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: savedShareURL, accessKey: accessKey)
+        )
+        let reconnectedCapabilities = try await reconnectedClient.capabilities()
+        XCTAssertEqual(reconnectedCapabilities.shareID, shareID)
+    }
+
+    func testClientReconnectsAfterHTTP3ConnectionLoss() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-reconnect-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("reconnected".utf8).write(to: fixture.appendingPathComponent("hello.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "reconnect-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "ReconnectTest",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey)
+        )
+        _ = try await client.capabilities()
+
+        await client.invalidateTransportForTesting()
+
+        let metadata = try await client.metadata(path: "hello.txt")
+        let contents = try await client.read(path: "hello.txt", offset: 0, length: 64)
+        XCTAssertEqual(metadata.size, UInt64(contents.count))
+        XCTAssertEqual(contents, Data("reconnected".utf8))
+    }
+
+    func testTimedOutStreamDoesNotReplaceHTTP3Connection() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-timeout-retry-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("fresh connection".utf8).write(to: fixture.appendingPathComponent("hello.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let delay = GhostFileOneShotRequestDelay()
+        let accessKey = "timeout-retry-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "TimeoutRetryTest",
+                accessKey: accessKey,
+                requestDelay: { request in
+                    guard request.operation == "metadata", request.path == "hello.txt",
+                          await delay.consume() else { return }
+                    try? await Task.sleep(for: .milliseconds(500))
+                }
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey),
+            connectionTimeout: .seconds(2),
+            requestTimeout: .milliseconds(150)
+        )
+
+        let initialTransport = await client.transportLogIDForTesting()
+        let originalTransport = try XCTUnwrap(initialTransport)
+        do {
+            _ = try await client.metadata(path: "hello.txt")
+            XCTFail("The delayed request unexpectedly completed before its deadline")
+        } catch {}
+        let firstInvocationCount = await delay.invocationCount
+        let transportAfterTimeout = await client.transportLogIDForTesting()
+        XCTAssertEqual(firstInvocationCount, 1, "A stream timeout retried the request automatically")
+        XCTAssertEqual(
+            transportAfterTimeout,
+            originalTransport,
+            "A stream timeout replaced the entire QUIC connection"
+        )
+
+        let metadata = try await client.metadata(path: "hello.txt")
+        XCTAssertEqual(metadata.size, UInt64(Data("fresh connection".utf8).count))
+        let invocationCount = await delay.invocationCount
+        let finalTransport = await client.transportLogIDForTesting()
+        XCTAssertEqual(invocationCount, 2)
+        XCTAssertEqual(finalTransport, originalTransport)
+    }
+
+    func testUnresponsiveQUICPeerFailsWithinConnectionDeadline() async throws {
+        let queue = DispatchQueue(label: "org.ghostvm.ghostfile.tests.silent-udp")
+        let listener = try NWListener(using: .udp, on: .any)
+        let ready = expectation(description: "silent UDP listener ready")
+        listener.stateUpdateHandler = { state in
+            if case .ready = state { ready.fulfill() }
+        }
+        listener.newConnectionHandler = { connection in
+            // Accept UDP datagrams but intentionally never answer the QUIC handshake.
+            connection.start(queue: queue)
+        }
+        listener.start(queue: queue)
+        defer { listener.cancel() }
+        await fulfillment(of: [ready], timeout: 2)
+        guard let port = listener.port else { throw TestError.missingShareURL }
+
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: port,
+            accessKey: "deadline-test",
+            publicKeyPin: "not-a-real-pin",
+            resourceBasePath: "/v1/shares/00000000-0000-0000-0000-000000000001",
+            connectionTimeout: .milliseconds(250),
+            requestTimeout: .seconds(1)
+        )
+
+        let clock = ContinuousClock()
+        let started = clock.now
+        do {
+            _ = try await transport.request(
+                operation: "capabilities",
+                relativePath: nil,
+                offset: nil,
+                length: nil
+            )
+            XCTFail("An unresponsive QUIC peer unexpectedly completed a request")
+        } catch {
+            XCTAssertLessThan(started.duration(to: clock.now), .seconds(2))
+        }
+    }
+
+    func testCancellingRequestDuringQUICHandshakeFinishesPromptly() async throws {
+        let queue = DispatchQueue(label: "org.ghostvm.ghostfile.tests.cancel-handshake-udp")
+        let listener = try NWListener(using: .udp, on: .any)
+        let ready = expectation(description: "silent UDP listener ready")
+        let receivedInitialDatagram = expectation(description: "silent peer received initial QUIC datagram")
+        listener.stateUpdateHandler = { state in
+            if case .ready = state { ready.fulfill() }
+        }
+        listener.newConnectionHandler = { connection in
+            // A UDP listener creates this flow only after the client's first
+            // datagram arrives. Keep the peer silent so the QUIC handshake
+            // remains pending at a deterministic cancellation point.
+            receivedInitialDatagram.fulfill()
+            connection.start(queue: queue)
+        }
+        listener.start(queue: queue)
+        defer { listener.cancel() }
+        await fulfillment(of: [ready], timeout: 2)
+        guard let port = listener.port else { throw TestError.missingShareURL }
+
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: port,
+            accessKey: "cancel-handshake-test",
+            publicKeyPin: "not-a-real-pin",
+            resourceBasePath: "/v1/shares/00000000-0000-0000-0000-000000000001",
+            connectionTimeout: .seconds(10),
+            requestTimeout: .seconds(10)
+        )
+
+        let completed = expectation(description: "handshake-waiting request completed after cancellation")
+        let requestTask = Task { () -> GhostFileCancellationOutcome in
+            defer { completed.fulfill() }
+            do {
+                _ = try await transport.request(
+                    operation: "capabilities",
+                    relativePath: nil,
+                    offset: nil,
+                    length: nil
+                )
+                return .succeeded
+            } catch is CancellationError {
+                return .cancelled
+            } catch {
+                return .failed(String(describing: error))
+            }
+        }
+
+        await fulfillment(of: [receivedInitialDatagram], timeout: 2)
+        let clock = ContinuousClock()
+        let cancelledAt = clock.now
+        requestTask.cancel()
+        await fulfillment(of: [completed], timeout: 0.5)
+        let cancellationLatency = cancelledAt.duration(to: clock.now)
+
+        // Unblock the deliberately broken implementation after the timeout
+        // assertion so the test never waits for the ten-second deadline.
+        await transport.invalidateForTesting()
+        let outcome = await requestTask.value
+        XCTAssertEqual(outcome, .cancelled)
+        XCTAssertLessThan(
+            cancellationLatency,
+            .milliseconds(500),
+            "Caller cancellation remained stuck in QUIC handshake readiness"
+        )
+    }
+
+    func testSmallFileInlineCacheExpiresAndRefreshes() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-cache-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        let fileURL = fixture.appendingPathComponent("tiny.txt")
+        try Data("before".utf8).write(to: fileURL)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "quic-cache-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileCacheIntegration",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey)
+        )
+        let listing = try await client.directory(path: "")
+        XCTAssertEqual(listing.inlineContents?.first(where: { $0.name == "tiny.txt" })?.data, Data("before".utf8))
+
+        try Data("after!".utf8).write(to: fileURL, options: .atomic)
+        let cachedContents = try await client.read(path: "tiny.txt", offset: 0, length: 64)
+        XCTAssertEqual(cachedContents, Data("before".utf8))
+
+        try await Task.sleep(for: .milliseconds(5_100))
+        let refreshed = try await client.metadata(path: "tiny.txt")
+        XCTAssertEqual(refreshed.size, 6)
+        let refreshedContents = try await client.read(path: "tiny.txt", offset: 0, length: 64)
+        XCTAssertEqual(refreshedContents, Data("after!".utf8))
+    }
+
+    func testZeroCacheTTLReadsAtomicHostReplacementImmediately() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-live-cache-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        let fileURL = fixture.appendingPathComponent("live.txt")
+        try Data("before".utf8).write(to: fileURL)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "quic-live-cache-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileLiveCacheIntegration",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        var components = try XCTUnwrap(URLComponents(
+            url: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey),
+            resolvingAgainstBaseURL: false
+        ))
+        var queryItems = components.queryItems ?? []
+        queryItems.append(URLQueryItem(name: GhostFileProtocol.cacheTTLQueryName, value: "0"))
+        components.queryItems = queryItems
+        let client = try GhostFileHTTP3Client(resourceURL: try XCTUnwrap(components.url))
+
+        let initialContents = try await client.read(path: "live.txt", offset: 0, length: 64)
+        XCTAssertEqual(initialContents, Data("before".utf8))
+        try Data("after!".utf8).write(to: fileURL, options: .atomic)
+        let replacedContents = try await client.read(path: "live.txt", offset: 0, length: 64)
+        XCTAssertEqual(replacedContents, Data("after!".utf8))
+    }
+
+    func testDesktopSizedDirectoryListingCompletesOnOneHTTP3Connection() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-large-directory-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        // The real Desktop failure returned roughly 22 KiB. Use enough long
+        // directory names to force the response across multiple UDP send
+        // batches without introducing file-content I/O into this test.
+        for index in 0..<128 {
+            let name = String(format: "%03d-%@", index, String(repeating: "directory-entry-", count: 5))
+            try FileManager.default.createDirectory(
+                at: fixture.appendingPathComponent(name, isDirectory: true),
+                withIntermediateDirectories: false
+            )
+        }
+
+        let accessKey = "large-directory-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "LargeDirectoryTest",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey),
+            connectionTimeout: .seconds(2),
+            requestTimeout: .seconds(2)
+        )
+        let initialTransport = await client.transportLogIDForTesting()
+        let originalTransport = try XCTUnwrap(initialTransport)
+        let started = ContinuousClock.now
+        let listing = try await client.directory(path: "")
+        let elapsed = started.duration(to: .now)
+        let finalTransport = await client.transportLogIDForTesting()
+
+        XCTAssertEqual(listing.entries.count, 128)
+        XCTAssertEqual(finalTransport, originalTransport)
+        XCTAssertLessThan(elapsed, .seconds(1))
+    }
+
+    func testDesktopSizedDirectoryListingSurvivesMinimumQUICPathMTU() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-minimum-pmtu-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        for index in 0..<128 {
+            let name = String(format: "%03d-%@", index, String(repeating: "directory-entry-", count: 5))
+            try FileManager.default.createDirectory(
+                at: fixture.appendingPathComponent(name, isDirectory: true),
+                withIntermediateDirectories: false
+            )
+        }
+
+        let accessKey = "minimum-pmtu-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "MinimumPMTUTest",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForLoopbackShareURL(server)
+        guard let serverPortValue = shareURL.port,
+              let serverPort = NWEndpoint.Port(rawValue: UInt16(serverPortValue)),
+              var components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false) else {
+            throw TestError.missingShareURL
+        }
+        let proxy = try GhostFilePathMTUProxy(upstreamPort: serverPort, maximumDatagramSize: 1_200)
+        let proxyPort = try await proxy.start()
+        defer { proxy.stop() }
+
+        components.host = "127.0.0.1"
+        components.port = Int(proxyPort.rawValue)
+        components.queryItems = (components.queryItems ?? []) + [
+            URLQueryItem(name: "access_key", value: accessKey)
+        ]
+        let resourceURL = try XCTUnwrap(components.url)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: resourceURL,
+            connectionTimeout: .seconds(2),
+            requestTimeout: .seconds(2)
+        )
+
+        let listing = try await client.directory(path: "")
+        XCTAssertEqual(listing.entries.count, 128)
+        XCTAssertGreaterThan(proxy.droppedDatagramCount, 0, "The PMTU proxy did not reject a probe")
+    }
+
+    func testBulkTransferBenchmarkWhenRequested() async throws {
+        let environment = ProcessInfo.processInfo.environment
+        guard environment["GHOSTFILE_RUN_BULK_BENCHMARK"] == "1" else {
+            throw XCTSkip("Set GHOSTFILE_RUN_BULK_BENCHMARK=1 to run the HTTP/3 bulk benchmark")
+        }
+        guard let fixturePath = environment["GHOSTFILE_BENCHMARK_FILE"] else {
+            throw XCTSkip("Set GHOSTFILE_BENCHMARK_FILE to the source fixture path")
+        }
+
+        let fixtureURL = URL(fileURLWithPath: fixturePath).standardizedFileURL
+        let payload = try Data(contentsOf: fixtureURL, options: .mappedIfSafe)
+        let accessKey = "quic-bulk-benchmark-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixtureURL.deletingLastPathComponent(),
+                shareName: "GhostFileHTTP3BulkBenchmark",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        let resourceURL = try loopbackResourceURL(
+            shareURL: shareURL,
+            accessKey: accessKey
+        )
+        let client = try GhostFileHTTP3Client(resourceURL: resourceURL)
+        let relativePath = fixtureURL.lastPathComponent
+        let chunkSize = GhostFileProtocol.maximumReadLength
+        let chunks = stride(from: 0, to: payload.count, by: chunkSize).map { offset in
+            (offset: offset, length: min(chunkSize, payload.count - offset))
+        }
+
+        // Establish the connection before either timed transfer.
+        _ = try await client.read(path: relativePath, offset: 0, length: 1)
+
+        let sequential = try await timedTransfer {
+            var responses: [(Int, Data)] = []
+            responses.reserveCapacity(chunks.count)
+            for chunk in chunks {
+                let data = try await client.read(
+                    path: relativePath,
+                    offset: UInt64(chunk.offset),
+                    length: chunk.length
+                )
+                responses.append((chunk.offset, data))
+            }
+            return responses
+        }
+        try verify(sequential.result, against: payload)
+
+        let parallel = try await timedTransfer {
+            var responses: [(Int, Data)] = []
+            responses.reserveCapacity(chunks.count)
+            for batchStart in stride(from: 0, to: chunks.count, by: 16) {
+                let batchEnd = min(batchStart + 16, chunks.count)
+                try await withThrowingTaskGroup(of: (Int, Data).self) { group in
+                    for chunk in chunks[batchStart.. (NWEndpoint.Port, String) in
+            guard let portNumber = shareURL.port,
+                  let port = NWEndpoint.Port(rawValue: UInt16(portNumber)),
+                  let components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false),
+                  let pin = components.queryItems?.first(where: { $0.name == "pk" })?.value else {
+                throw TestError.missingShareURL
+            }
+            return (port, pin)
+        }()
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: connectionDetails.0,
+            accessKey: accessKey,
+            publicKeyPin: connectionDetails.1,
+            resourceBasePath: shareURL.path
+        )
+
+        async let pausedResponse = transport.request(
+            operation: "metadata",
+            relativePath: "slow.txt",
+            offset: nil,
+            length: nil
+        )
+        try await Task.sleep(for: .milliseconds(100))
+
+        let clock = ContinuousClock()
+        let started = clock.now
+        let fastResponse = try await transport.request(
+            operation: "metadata",
+            relativePath: "hello.txt",
+            offset: nil,
+            length: nil
+        )
+        let elapsed = started.duration(to: clock.now)
+
+        XCTAssertEqual(fastResponse.status, 200)
+        XCTAssertLessThan(elapsed, .seconds(1), "A paused HTTP/3 request blocked an independent stream")
+        _ = try await pausedResponse
+        await MainActor.run { server.stop() }
+    }
+
+    func testTimedOutRequestDoesNotPoisonSiblingHTTP3Streams() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-quic-timeout-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("still responsive".utf8).write(to: fixture.appendingPathComponent("hello.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "quic-timeout-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileHTTP3Timeout",
+                accessKey: accessKey,
+                requestDelay: { request in
+                    if request.path == "slow.txt" {
+                        try? await Task.sleep(for: .seconds(2))
+                    }
+                }
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForShareURL(server)
+        guard let portNumber = shareURL.port,
+              let port = NWEndpoint.Port(rawValue: UInt16(portNumber)),
+              let components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false),
+              let pin = components.queryItems?.first(where: { $0.name == "pk" })?.value else {
+            throw TestError.missingShareURL
+        }
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: port,
+            accessKey: accessKey,
+            publicKeyPin: pin,
+            resourceBasePath: shareURL.path,
+            connectionTimeout: .seconds(2),
+            requestTimeout: .milliseconds(250)
+        )
+
+        do {
+            _ = try await transport.request(
+                operation: "metadata",
+                relativePath: "slow.txt",
+                offset: nil,
+                length: nil
+            )
+            XCTFail("The deliberately stalled request unexpectedly completed")
+        } catch {}
+
+        let response = try await transport.request(
+            operation: "metadata",
+            relativePath: "hello.txt",
+            offset: nil,
+            length: nil
+        )
+        XCTAssertEqual(response.status, 200)
+    }
+
+    func testConcurrentRangeReadsUseOneHTTP3Connection() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-quic-load-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        let payload = Data((0..<(2 * 1024 * 1024)).map { UInt8(truncatingIfNeeded: $0) })
+        try payload.write(to: fixture.appendingPathComponent("payload.bin"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let accessKey = "quic-load-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileHTTP3Load",
+                accessKey: accessKey
+            )
+            try server.start()
+            return server
+        }
+
+        let shareURL = try await waitForShareURL(server)
+        let resourceURL = try loopbackResourceURL(shareURL: shareURL, accessKey: accessKey)
+        let client = try GhostFileHTTP3Client(resourceURL: resourceURL)
+
+        let chunkSize = 64 * 1024
+        try await withThrowingTaskGroup(of: Void.self) { group in
+            for chunkIndex in 0..<32 {
+                group.addTask {
+                    let offset = chunkIndex * chunkSize
+                    let data = try await client.read(
+                        path: "payload.bin",
+                        offset: UInt64(offset),
+                        length: chunkSize
+                    )
+                    XCTAssertEqual(data, payload.subdata(in: offset..<(offset + chunkSize)))
+                }
+            }
+            try await group.waitForAll()
+        }
+        await MainActor.run { server.stop() }
+    }
+
+    func testRequestsWaitForHTTP3StreamCreditInsteadOfFailing() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-quic-stream-credit-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("stream credit".utf8).write(to: fixture.appendingPathComponent("hello.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let gate = GhostFileRequestGate()
+        let accessKey = "quic-stream-credit-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileHTTP3StreamCredit-\(UUID().uuidString)",
+                accessKey: accessKey,
+                requestDelay: { request in
+                    guard request.operation == "metadata" else { return }
+                    await gate.wait()
+                }
+            )
+            try server.start()
+            return server
+        }
+        defer { Task { @MainActor in server.stop() } }
+
+        let shareURL = try await waitForLoopbackShareURL(server)
+        guard let portNumber = shareURL.port,
+              let port = NWEndpoint.Port(rawValue: UInt16(portNumber)),
+              let components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false),
+              let pin = components.queryItems?.first(where: { $0.name == "pk" })?.value else {
+            throw TestError.missingShareURL
+        }
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: port,
+            accessKey: accessKey,
+            publicKeyPin: pin,
+            resourceBasePath: shareURL.path,
+            requestTimeout: .seconds(5)
+        )
+
+        _ = try await transport.request(
+            operation: "capabilities",
+            relativePath: nil,
+            offset: nil,
+            length: nil
+        )
+
+        let release = Task {
+            try await Task.sleep(for: .milliseconds(250))
+            await gate.open()
+        }
+        defer { release.cancel() }
+
+        let results = await withTaskGroup(of: Result.self) { group in
+            for _ in 0..<80 {
+                group.addTask {
+                    do {
+                        return .success(try await transport.request(
+                            operation: "metadata",
+                            relativePath: "hello.txt",
+                            offset: nil,
+                            length: nil
+                        ).status)
+                    } catch {
+                        return .failure(error)
+                    }
+                }
+            }
+            return await group.reduce(into: []) { $0.append($1) }
+        }
+
+        let statuses = results.compactMap { try? $0.get() }
+        let failures = results.compactMap { result -> String? in
+            guard case .failure(let error) = result else { return nil }
+            return String(describing: error)
+        }
+        XCTAssertEqual(failures, [], "Requests failed instead of waiting for HTTP/3 stream credit")
+        XCTAssertEqual(statuses.count, 80)
+        XCTAssertTrue(statuses.allSatisfy { $0 == 200 })
+    }
+
+    func testCancellingOpenedRequestFinishesPromptly() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-quic-cancellation-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("cancel me".utf8).write(to: fixture.appendingPathComponent("cancel.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let gate = GhostFileRequestGate()
+        let accessKey = "quic-cancellation-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileHTTP3Cancellation-\(UUID().uuidString)",
+                accessKey: accessKey,
+                requestDelay: { request in
+                    guard request.operation == "metadata", request.path == "cancel.txt" else { return }
+                    await gate.wait()
+                }
+            )
+            try server.start()
+            return server
+        }
+        defer {
+            Task {
+                await gate.open()
+                await MainActor.run { server.stop() }
+            }
+        }
+
+        let shareURL = try await waitForLoopbackShareURL(server)
+        guard let portNumber = shareURL.port,
+              let port = NWEndpoint.Port(rawValue: UInt16(portNumber)),
+              let components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false),
+              let pin = components.queryItems?.first(where: { $0.name == "pk" })?.value else {
+            throw TestError.missingShareURL
+        }
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: port,
+            accessKey: accessKey,
+            publicKeyPin: pin,
+            resourceBasePath: shareURL.path,
+            requestTimeout: .seconds(10)
+        )
+
+        let completed = expectation(description: "cancelled HTTP/3 request completed")
+        let requestTask = Task { () -> GhostFileCancellationOutcome in
+            defer { completed.fulfill() }
+            do {
+                _ = try await transport.request(
+                    operation: "metadata",
+                    relativePath: "cancel.txt",
+                    offset: nil,
+                    length: nil
+                )
+                return .succeeded
+            } catch is CancellationError {
+                return .cancelled
+            } catch {
+                return .failed(String(describing: error))
+            }
+        }
+
+        await gate.waitForArrival()
+        let clock = ContinuousClock()
+        let cancelledAt = clock.now
+        requestTask.cancel()
+        await fulfillment(of: [completed], timeout: 0.5)
+        let cancellationLatency = cancelledAt.duration(to: clock.now)
+
+        // Always release the server barrier so a broken implementation can
+        // drain cleanly after the timeout assertion instead of leaking a task.
+        await gate.open()
+        let outcome = await requestTask.value
+        XCTAssertEqual(outcome, .cancelled)
+        XCTAssertLessThan(
+            cancellationLatency,
+            .milliseconds(500),
+            "Caller cancellation waited for the HTTP/3 response or request deadline"
+        )
+    }
+
+    func testCancellingOpenedRequestCancelsServerRoutingWithoutBlockingSibling() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-quic-server-cancellation-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("cancel me".utf8).write(to: fixture.appendingPathComponent("cancel.txt"))
+        try Data("still responsive".utf8).write(to: fixture.appendingPathComponent("sibling.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let gate = GhostFileRequestGate()
+        let serverRoutingCancelled = expectation(description: "server routing task cancelled after peer reset")
+        let accessKey = "quic-server-cancellation-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileHTTP3ServerCancellation-\(UUID().uuidString)",
+                accessKey: accessKey,
+                requestDelay: { request in
+                    guard request.operation == "metadata", request.path == "cancel.txt" else { return }
+                    await withTaskCancellationHandler {
+                        await gate.wait()
+                    } onCancel: {
+                        serverRoutingCancelled.fulfill()
+                    }
+                }
+            )
+            try server.start()
+            return server
+        }
+        defer {
+            Task {
+                await gate.open()
+                await MainActor.run { server.stop() }
+            }
+        }
+
+        let shareURL = try await waitForLoopbackShareURL(server)
+        guard let portNumber = shareURL.port,
+              let port = NWEndpoint.Port(rawValue: UInt16(portNumber)),
+              let components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false),
+              let pin = components.queryItems?.first(where: { $0.name == "pk" })?.value else {
+            throw TestError.missingShareURL
+        }
+        let transport = try GhostFileHTTP3Transport(
+            host: "127.0.0.1",
+            port: port,
+            accessKey: accessKey,
+            publicKeyPin: pin,
+            resourceBasePath: shareURL.path
+        )
+
+        let slowRequest = Task { () -> GhostFileCancellationOutcome in
+            do {
+                _ = try await transport.request(
+                    operation: "metadata",
+                    relativePath: "cancel.txt",
+                    offset: nil,
+                    length: nil
+                )
+                return .succeeded
+            } catch is CancellationError {
+                return .cancelled
+            } catch {
+                return .failed(String(describing: error))
+            }
+        }
+
+        await gate.waitForArrival()
+        slowRequest.cancel()
+        let slowOutcome = await slowRequest.value
+        XCTAssertEqual(slowOutcome, .cancelled)
+
+        let sibling = try await transport.request(
+            operation: "metadata",
+            relativePath: "sibling.txt",
+            offset: nil,
+            length: nil
+        )
+        XCTAssertEqual(sibling.status, 200)
+
+        await fulfillment(of: [serverRoutingCancelled], timeout: 0.5)
+        await gate.open()
+    }
+
+    func testStoppingShareNotifiesInFlightHTTP3RequestBeforeItsDeadline() async throws {
+        let fixture = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostfile-quic-share-stop-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: fixture, withIntermediateDirectories: true)
+        try Data("stop me".utf8).write(to: fixture.appendingPathComponent("stop.txt"))
+        defer { try? FileManager.default.removeItem(at: fixture) }
+
+        let gate = GhostFileRequestGate()
+        let accessKey = "quic-share-stop-key"
+        let server = try await MainActor.run {
+            let server = GhostFileShareServer(
+                rootURL: fixture,
+                shareName: "GhostFileHTTP3ShareStop-\(UUID().uuidString)",
+                accessKey: accessKey,
+                requestDelay: { request in
+                    guard request.operation == "metadata", request.path == "stop.txt" else { return }
+                    await gate.wait()
+                }
+            )
+            try server.start()
+            return server
+        }
+        defer {
+            Task {
+                await gate.open()
+                await MainActor.run { server.stop() }
+            }
+        }
+
+        let shareURL = try await waitForLoopbackShareURL(server)
+        let client = try GhostFileHTTP3Client(
+            resourceURL: loopbackResourceURL(shareURL: shareURL, accessKey: accessKey),
+            connectionTimeout: .seconds(2),
+            requestTimeout: .seconds(4)
+        )
+
+        let request = Task { () -> GhostFileCancellationOutcome in
+            do {
+                _ = try await client.metadata(path: "stop.txt")
+                return .succeeded
+            } catch is CancellationError {
+                return .cancelled
+            } catch {
+                return .failed(String(describing: error))
+            }
+        }
+
+        await gate.waitForArrival()
+        let clock = ContinuousClock()
+        let stoppedAt = clock.now
+        await MainActor.run { server.stop() }
+        let outcome = await request.value
+        let elapsed = stoppedAt.duration(to: clock.now)
+
+        await gate.open()
+        guard case .failed = outcome else {
+            return XCTFail("An in-flight request unexpectedly survived share shutdown: \(outcome)")
+        }
+        XCTAssertLessThan(
+            elapsed,
+            .seconds(3),
+            "The client learned about share shutdown only from its request deadline"
+        )
+    }
+
+    private enum TestError: Error {
+        case missingShareURL
+        case shareDidNotStop
+        case responseMismatch
+    }
+
+    private func loopbackResourceURL(shareURL: URL, accessKey: String) throws -> URL {
+        guard var components = URLComponents(url: shareURL, resolvingAgainstBaseURL: false) else {
+            throw TestError.missingShareURL
+        }
+        components.host = "127.0.0.1"
+        components.queryItems = (components.queryItems ?? []) + [
+            URLQueryItem(name: "access_key", value: accessKey)
+        ]
+        guard let url = components.url else { throw TestError.missingShareURL }
+        return url
+    }
+
+    private func timedTransfer(
+        _ operation: () async throws -> Result
+    ) async rethrows -> (seconds: Double, result: Result) {
+        let clock = ContinuousClock()
+        let started = clock.now
+        let result = try await operation()
+        let elapsed = started.duration(to: clock.now)
+        let components = elapsed.components
+        let seconds = Double(components.seconds) + Double(components.attoseconds) / 1e18
+        return (seconds, result)
+    }
+
+    private func verify(_ responses: [(Int, Data)], against payload: Data) throws {
+        var expectedOffset = 0
+        for (offset, data) in responses.sorted(by: { $0.0 < $1.0 }) {
+            guard offset == expectedOffset, offset + data.count <= payload.count else {
+                throw TestError.responseMismatch
+            }
+            guard payload[offset..<(offset + data.count)].elementsEqual(data) else {
+                throw TestError.responseMismatch
+            }
+            expectedOffset += data.count
+        }
+        guard expectedOffset == payload.count else {
+            throw TestError.responseMismatch
+        }
+    }
+
+    private func printBenchmark(_ label: String, bytes: Int, seconds: Double) {
+        let throughput = Double(bytes) / seconds / (1024 * 1024)
+        print("GHOSTFILE_BENCHMARK \(label): \(String(format: "%.1f", throughput)) MiB/s " +
+              "(\(String(format: "%.3f", seconds)) s)")
+    }
+
+    private func waitForShareURL(_ server: GhostFileShareServer) async throws -> URL {
+        for _ in 0..<200 {
+            if let url = await MainActor.run(body: { server.shareURL }) {
+                return url
+            }
+            try await Task.sleep(for: .milliseconds(10))
+        }
+        throw TestError.missingShareURL
+    }
+
+    private func waitForLoopbackShareURL(_ server: GhostFileShareServer) async throws -> URL {
+        for _ in 0..<200 {
+            if let url = await MainActor.run(body: { server.loopbackShareURLForTesting }) {
+                return url
+            }
+            try await Task.sleep(for: .milliseconds(10))
+        }
+        throw TestError.missingShareURL
+    }
+
+    private func waitForShareToStop(_ server: GhostFileShareServer) async throws {
+        for _ in 0..<500 {
+            let stopped = await MainActor.run { !server.isRunning && server.port == 0 }
+            if stopped { return }
+            try await Task.sleep(for: .milliseconds(10))
+        }
+        throw TestError.shareDidNotStop
+    }
+}
+
+private actor GhostFileOneShotRequestDelay {
+    private(set) var invocationCount = 0
+    private var shouldDelay = true
+
+    func consume() -> Bool {
+        invocationCount += 1
+        defer { shouldDelay = false }
+        return shouldDelay
+    }
+}
+
+private actor GhostFileRequestGate {
+    private var isOpen = false
+    private var hasArrival = false
+    private var waiters: [CheckedContinuation] = []
+    private var arrivalWaiters: [CheckedContinuation] = []
+
+    func wait() async {
+        if !hasArrival {
+            hasArrival = true
+            let currentArrivalWaiters = arrivalWaiters
+            arrivalWaiters.removeAll()
+            currentArrivalWaiters.forEach { $0.resume() }
+        }
+        guard !isOpen else { return }
+        await withCheckedContinuation { waiters.append($0) }
+    }
+
+    func waitForArrival() async {
+        guard !hasArrival else { return }
+        await withCheckedContinuation { arrivalWaiters.append($0) }
+    }
+
+    func open() {
+        isOpen = true
+        let currentWaiters = waiters
+        waiters.removeAll()
+        currentWaiters.forEach { $0.resume() }
+    }
+}
+
+private enum GhostFileCancellationOutcome: Equatable {
+    case succeeded
+    case cancelled
+    case failed(String)
+}
+
+private final class GhostFilePathMTUProxy: @unchecked Sendable {
+    private let upstreamPort: NWEndpoint.Port
+    private let maximumDatagramSize: Int
+    private let listener: NWListener
+    private let queue = DispatchQueue(label: "org.ghostvm.ghostfile.tests.pmtu-proxy")
+    private let lock = NSLock()
+    private var downstream: NWConnection?
+    private var upstream: NWConnection?
+    private var dropped = 0
+
+    init(upstreamPort: NWEndpoint.Port, maximumDatagramSize: Int) throws {
+        self.upstreamPort = upstreamPort
+        self.maximumDatagramSize = maximumDatagramSize
+        listener = try NWListener(using: .udp, on: .any)
+    }
+
+    var droppedDatagramCount: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return dropped
+    }
+
+    func start() async throws -> NWEndpoint.Port {
+        try await withCheckedThrowingContinuation { continuation in
+            let completion = GhostFileProxyStartCompletion(continuation: continuation)
+            listener.stateUpdateHandler = { [weak self] state in
+                guard let self else { return }
+                switch state {
+                case .ready:
+                    if let port = self.listener.port {
+                        completion.succeed(port)
+                    }
+                case .failed(let error):
+                    completion.fail(error)
+                case .cancelled:
+                    completion.fail(CancellationError())
+                default:
+                    break
+                }
+            }
+            listener.newConnectionHandler = { [weak self] connection in
+                self?.accept(connection)
+            }
+            listener.start(queue: queue)
+        }
+    }
+
+    func stop() {
+        listener.cancel()
+        lock.lock()
+        let downstream = self.downstream
+        let upstream = self.upstream
+        self.downstream = nil
+        self.upstream = nil
+        lock.unlock()
+        downstream?.cancel()
+        upstream?.cancel()
+    }
+
+    private func accept(_ downstream: NWConnection) {
+        let upstream = NWConnection(host: "127.0.0.1", port: upstreamPort, using: .udp)
+        lock.lock()
+        guard self.downstream == nil else {
+            lock.unlock()
+            downstream.cancel()
+            return
+        }
+        self.downstream = downstream
+        self.upstream = upstream
+        lock.unlock()
+
+        downstream.start(queue: queue)
+        upstream.start(queue: queue)
+        forward(from: downstream, to: upstream)
+        forward(from: upstream, to: downstream)
+    }
+
+    private func forward(from source: NWConnection, to destination: NWConnection) {
+        source.receiveMessage { [weak self, weak source, weak destination] content, _, _, error in
+            guard let self, let source, let destination, error == nil, let content else { return }
+            if content.count <= self.maximumDatagramSize {
+                destination.send(content: content, completion: .contentProcessed { _ in })
+            } else {
+                self.lock.lock()
+                self.dropped += 1
+                self.lock.unlock()
+            }
+            self.forward(from: source, to: destination)
+        }
+    }
+}
+
+private final class GhostFileProxyStartCompletion: @unchecked Sendable {
+    private let lock = NSLock()
+    private var continuation: CheckedContinuation?
+
+    init(continuation: CheckedContinuation) {
+        self.continuation = continuation
+    }
+
+    func succeed(_ port: NWEndpoint.Port) {
+        complete(.success(port))
+    }
+
+    func fail(_ error: Error) {
+        complete(.failure(error))
+    }
+
+    private func complete(_ result: Result) {
+        lock.lock()
+        let continuation = self.continuation
+        self.continuation = nil
+        lock.unlock()
+        continuation?.resume(with: result)
+    }
+}
diff --git a/macOS/GhostHTTP3/Patches/quiche-darwin-send-time.patch b/macOS/GhostHTTP3/Patches/quiche-darwin-send-time.patch
new file mode 100644
index 0000000..05a2539
--- /dev/null
+++ b/macOS/GhostHTTP3/Patches/quiche-darwin-send-time.patch
@@ -0,0 +1,41 @@
+diff --git a/quiche/src/ffi.rs b/quiche/src/ffi.rs
+--- a/quiche/src/ffi.rs
++++ b/quiche/src/ffi.rs
+@@ -2161,11 +2161,30 @@ fn std_time_to_c(time: &Instant, out: &mut timespec) {
+     out.tv_nsec = raw_time.subsec_nanos() as libc::c_long;
+ }
+-
++
+-#[cfg(any(target_os = "macos", target_os = "ios", target_os = "windows"))]
+-fn std_time_to_c(_time: &Instant, out: &mut timespec) {
+-    // TODO: implement Instant conversion for systems that don't use timespec.
+-    out.tv_sec = 0;
+-    out.tv_nsec = 0;
++#[cfg(any(target_os = "macos", target_os = "ios"))]
++fn std_time_to_c(time: &Instant, out: &mut timespec) {
++    // Rust's Instant has no stable absolute representation on Darwin. Preserve
++    // the pacing delay in Instant's clock domain, then project that relative
++    // delay onto CLOCK_MONOTONIC, which is also used by GhostFile's sender.
++    let delay = time.saturating_duration_since(Instant::now());
++    let mut now = std::mem::MaybeUninit::::uninit();
++    if unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, now.as_mut_ptr()) } != 0 {
++        out.tv_sec = 0;
++        out.tv_nsec = 0;
++        return;
++    }
++    let now = unsafe { now.assume_init() };
++    let nanoseconds = now.tv_nsec as u64 + delay.subsec_nanos() as u64;
++    out.tv_sec = now.tv_sec
++        + delay.as_secs() as libc::time_t
++        + (nanoseconds / 1_000_000_000) as libc::time_t;
++    out.tv_nsec = (nanoseconds % 1_000_000_000) as libc::c_long;
++}
++
++#[cfg(target_os = "windows")]
++fn std_time_to_c(_time: &Instant, out: &mut timespec) {
++    out.tv_sec = 0;
++    out.tv_nsec = 0;
+ }
+-
++
+ #[cfg(test)]
diff --git a/macOS/GhostHTTP3/README.md b/macOS/GhostHTTP3/README.md
new file mode 100644
index 0000000..8ba6974
--- /dev/null
+++ b/macOS/GhostHTTP3/README.md
@@ -0,0 +1,196 @@
+# GhostHTTP3
+
+GhostHTTP3 packages Cloudflare's production QUIC and RFC 9114 HTTP/3 stack as a
+single arm64 dynamic macOS framework. The framework executable is a Mach-O
+dylib that exposes quiche's complete C API (QUIC, HTTP/3, and QPACK) plus a
+tiny, versioned GhostHTTP3 wrapper API.
+
+This is a transport library, not the GhostFile protocol. GhostFile will use
+ordinary HTTP request semantics (`GET`, `HEAD`, status codes, headers, and body
+data) over the `h3` ALPN. There is no GhostFile-specific wire framing here.
+
+## Build
+
+Requirements:
+
+- Xcode command-line tools
+- Rust 1.88 or newer via `rustup`
+- CMake and Ninja (used while building quiche's BoringSSL dependency)
+- `libev` and `uthash` for the upstream C interoperability test
+
+The native build/test dependencies can be installed with:
+
+```sh
+brew install cmake ninja libev uthash
+```
+
+Run:
+
+```sh
+macOS/GhostHTTP3/scripts/build-with-rust-dmg.sh
+```
+
+That command creates a reusable sparse read/write macOS disk image at
+`macOS/GhostHTTP3/.build/toolchains/Rust-1.88.0-macOS-arm64.sparseimage`, mounts it at
+`macOS/GhostHTTP3/.build/mount/GhostHTTP3Rust188`, installs the toolchain and the arm64 macOS Rust target
+inside the image, then builds and tests the framework. Its logical capacity is
+4 GB, but it consumes only the space actually written. It can be detached with:
+
+```sh
+hdiutil detach macOS/GhostHTTP3/.build/mount/GhostHTTP3Rust188
+```
+
+If an appropriate `rustup` toolchain is already on `PATH`, the lower-level
+`build-framework.sh`, `test-framework.sh`, `test-stress.sh`, `test-http3.sh`,
+and `test-chaos.sh` scripts can be run directly. The disk-image build command
+runs them automatically after building the framework.
+
+`test-http3.sh` compiles Cloudflare's C client and server against the generated
+framework, exchanges `GET /` and an HTTP `200` response over loopback UDP, and
+asserts that ALPN negotiated `h3`. This exercises HTTP/3 HEADERS, SETTINGS,
+QPACK, DATA, and QUIC stream handling through the packaged library.
+
+`test-stress.sh` links a deterministic two-endpoint harness against the same
+framework. It establishes TLS over QUIC and exercises a 12 KiB QPACK header
+block, an empty response, 96 multiplexed requests while an earlier request is
+paused, 16 parallel 512 KiB response bodies with byte-for-byte validation,
+single-stream cancellation, server-initiated stream reset, GOAWAY rejection,
+bidi stream limit enforcement, application-level CONNECTION_CLOSE with peer-error
+inspection, and an oversized-header rejection path that asserts the peer receives
+`HTTP_EXCESSIVE_LOAD` (0x107). Application traffic is delivered in reversed
+datagram batches to exercise QUIC packet reordering throughout those scenarios.
+Set `GHOST_HTTP3_TEST_SANITIZERS=1` to compile the C harness with AddressSanitizer
+and UndefinedBehaviorSanitizer.
+
+`test-framework.sh` links and runs C and Swift consumers against the dynamic
+framework, verifies its arm64-only architecture and `@rpath` install name, and
+checks its ad-hoc build signature. A shipping app should embed the framework in
+`Contents/Frameworks` and sign it with the app during the normal code-signing
+phase.
+
+`test-chaos.sh` builds a user-space UDP impairment proxy
+(`Tests/udp-chaos-proxy.c`) and replays conservative, deterministic, seeded
+impairments through the upstream C quiche examples over loopback. The five
+gated impairment scenarios are: a transparency baseline, two-sided datagram
+loss (4% c2s / 5% s2c), 10% duplication, delay+jitter+reorder, and a
+deterministic 1350-byte MTU filter check. Each scenario asserts BOTH ends: the `http3-client` log proves
+HTTP/3 success over QUIC (`200 "byez"`) AND the proxy's machine-parseable
+`stats` lines prove each impairment actually fired (loss, dup, delayed,
+reordered, drop_mtu). The MTU check completes real HTTP/3 exchanges and then
+injects a harmless 1400-byte UDP sentinel to prove over-limit packets are
+dropped without claiming flaky live-traffic black-hole recovery. The proxy's per-direction delayed-packet queues are
+hard-bounded (`--queue`, default 256) with counted overflow drops, and every
+test process terminates within `GHOST_HTTP3_CHAOS_PROXY_MAX_DURATION` (300s
+default) plus a per-client watchdog. The gate also rejects forwarding errors
+and any delayed datagrams still queued at shutdown.
+
+`soak-chaos.sh` is an opt-in seed-progression soak that re-runs the chaos
+scenarios across an advancing seed range with a wall-clock budget checked
+between seeds. It is
+explicitly off the gated path (enable with `GHOST_HTTP3_SOAK=1`).
+
+## Environment variables
+
+`GHOST_HTTP3_TEST_SANITIZERS=1` builds the C harness and the proxy with
+AddressSanitizer and UndefinedBehaviorSanitizer.
+
+`GHOST_HTTP3_BUILD_DIR` (all scripts) overrides the default
+`.build` directory under the project root.
+
+`GHOST_HTTP3_BUILD_DIR`, `MACOSX_DEPLOYMENT_TARGET`, and the rust toolchain
+mount path (`GHOST_HTTP3_RUST_MOUNT`) affect `build-framework.sh` only.
+
+`test-chaos.sh` knobs (read alongside the script for the full list):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `GHOST_HTTP3_CHAOS_SEED` | `7` | impairment PRNG seed; seed 7 is validated as stable |
+| `GHOST_HTTP3_CHAOS_ITERATIONS` | `3` | client exchanges per scenario |
+| `GHOST_HTTP3_CHAOS_PORT_BASE` | PID-derived | first candidate UDP port pair |
+| `GHOST_HTTP3_CHAOS_SERVER_PORT` / `GHOST_HTTP3_CHAOS_PROXY_PORT` | unset | pin both ports (skip the scan) |
+| `GHOST_HTTP3_CHAOS_CLIENT_TIMEOUT` | `25` | per-client watchdog (must exceed quiche's 5s idle timeout) |
+| `GHOST_HTTP3_CHAOS_PROXY_MAX_DURATION` | `300` | proxy self-termination bound |
+| `GHOST_HTTP3_CHAOS_HARSH` | `0` | opt-in harsh-loss reproducer documenting the example's idle-timeout limit |
+| `GHOST_HTTP3_CHAOS_TOLERATE_STALL` | `0` | diagnostic escape hatch; when 1, stalls are counted and the run is explicitly not reported as a recovery gate |
+| `GHOST_HTTP3_TEST_SANITIZERS` | `0` | build the proxy with ASan/UBSan |
+
+`soak-chaos.sh` knobs:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `GHOST_HTTP3_SOAK_SEED_START` | `7` | first seed in the advancing range |
+| `GHOST_HTTP3_SOAK_SEED_COUNT` | `5` | how many successive seeds to run |
+| `GHOST_HTTP3_SOAK_MAX_SECONDS` | `240` | wall-clock budget checked between seeds (one in-flight seed can overshoot) |
+| `GHOST_HTTP3_SOAK_MAX_ITERATIONS` | `0` | hard seed-count cap (0 = no cap) |
+| `GHOST_HTTP3_SOAK_ITERATIONS` | `3` | per-seed chaos iterations |
+| `GHOST_HTTP3_SOAK_SANITIZERS` | `0` | build the proxy with ASan/UBSan |
+| `GHOST_HTTP3_SOAK_HARSH` | `0` | also run the harsh reproducer per seed |
+| `GHOST_HTTP3_SOAK_QUIET` | `0` | suppress per-seed chaos output |
+
+## Limitations (read before extending)
+
+- The included driver is IPv4 / loopback only; both endpoints are on
+  `127.0.0.1`. There is no second host involved and no need for elevated
+  privileges. The proxy accepts remote listen/target addresses, but tracks one
+  active client address at a time.
+- The stock quiche `http3-server.c` / `http3-client.c` examples hard-code
+  `max_idle_timeout = 5000ms`. When two-sided loss or an aggressive MTU
+  black hole hits a
+  handshake-critical flight, the example can stall until that timeout fires;
+  `test-chaos.sh` uses a validated conservative profile, and `GHOST_HTTP3_CHAOS_HARSH=1`
+  documents the failing edge as a reproducer rather than a regression. The
+  soak classifies the same stall mode as STALLED (informational), not as a
+  failure, so seed progression can advance across seeds that exercise the
+  quiche example's hard limit without false-positive soak alarms.
+- quiche's own `lost=` counter is `0` for the very short recovered flows used
+  here; it is printed for information but not asserted. The proxy's own
+  `drop_loss` counter is the source of truth.
+- The combined multi-impairment scenario was pulled from the gated set on
+  purpose: as soon as loss, dup, jitter, and MTU drop happen together, any of
+  them can land on the 1-RTT flight inside the 5s idle window and stall the
+  handshake non-deterministically across OS scheduling jitter. The five
+  individual scenarios each prove one impairment class cleanly.
+- The soak does not exercise the harsh-loss reproducer unless
+  `GHOST_HTTP3_SOAK_HARSH=1` is set; enabling it widens the per-seed timeout.
+
+## What remains for multi-host / GitHub Actions
+
+- Cross-host UDP impairment via the real network (not loopback) would catch
+  reception-path behaviors the loopback simulator cannot (OS receive-buffer
+  pressure, ICMP source quench, etc.). The proxy already supports
+  `--listen-host` / `--target-host`; what is missing is the test driver that
+  runs the client on one host and the server on another.
+- A "multi-impairment at once" deterministic profile that survives without a
+  handshake stall likely needs a request-padding profile or a patched
+  example with a longer idle timeout; the harsh reproducer above is the
+  placeholder until then.
+- For GitHub Actions: gate `test-chaos.sh` (it is already wired into
+  `build-with-rust-dmg.sh`); make `GHOST_HTTP3_SOAK=1` opt-in per matrix
+  because the seed-progression adds non-trivial wall-clock.
+- A long-horizon multi-hour soak run from CI on a quiet dedicated runner
+  would further tighten the leak-detection evidence on the proxy.
+
+Artifacts are written to `macOS/GhostHTTP3/.build/artifacts/`:
+
+- `GhostHTTP3.framework`: arm64 dynamic framework. Its executable has install
+  name `@rpath/GhostHTTP3.framework/Versions/A/GhostHTTP3`.
+
+There is no x86 slice, static release library, or XCFramework. The build asks
+Cargo for a `cdylib` only and links the GhostHTTP3 wrapper into that same dylib.
+System dependencies such as libc++ and libiconv are recorded by the dylib and
+do not require separate bundled copies.
+
+## Upstream
+
+The build pins quiche 0.29.3 to commit
+`55886df3be579579207104c8e645825b6347a209`. The upstream header is copied into
+the generated framework so C, Objective-C, C++, and Swift targets can use the
+full HTTP/3 API.
+
+quiche intentionally excludes `Cargo.lock` from its repository. This wrapper
+checks in the resolved `quiche-0.29.3.Cargo.lock` used by the build and passes
+Cargo's `--locked` flag, so transitive Rust dependencies cannot drift.
+
+See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for licensing.
+See [RESEARCH.md](RESEARCH.md) for the Google QUICHE, Mozilla Neqo, and
+Cloudflare quiche selection rationale.
diff --git a/macOS/GhostHTTP3/RESEARCH.md b/macOS/GhostHTTP3/RESEARCH.md
new file mode 100644
index 0000000..897cd1f
--- /dev/null
+++ b/macOS/GhostHTTP3/RESEARCH.md
@@ -0,0 +1,54 @@
+# HTTP/3 implementation selection
+
+Decision recorded 2026-07-31: package Cloudflare quiche behind the standalone
+GhostHTTP3 framework boundary.
+
+## Candidates
+
+### Google QUICHE
+
+[Google QUICHE](https://quiche.googlesource.com/quiche/) is Google's
+production-ready QUIC and HTTP/3 implementation and powers Google servers,
+Chromium, and Envoy. It is reputable, but its upstream embedding instructions
+say that embedders currently need to implement platform APIs and create build
+files. Its documented standalone binaries target Linux. That makes it a poor
+first fit for a small, signed macOS app framework despite the strength of the
+implementation.
+
+### Mozilla Neqo
+
+[Mozilla Neqo](https://github.com/mozilla/neqo) is Firefox's Rust QUIC, HTTP/3,
+and QPACK implementation. Mozilla states that its server functionality is
+experimental, not used in production by Mozilla, not optimized for performance
+or resource use, and should not be used in production. GhostFile needs a server
+as a primary role, so Neqo was not selected.
+
+### Cloudflare quiche
+
+[Cloudflare quiche](https://github.com/cloudflare/quiche) implements IETF QUIC
+and HTTP/3, powers Cloudflare's production edge, is used by Android's DNS
+resolver, and can be integrated into curl. Its supported build emits native
+library targets, including a `cdylib`, with a thin C FFI. The FFI includes the complete
+HTTP/3 surface needed here: ALPN `h3`, SETTINGS, QPACK, request/response HEADERS,
+DATA bodies, GOAWAY, stream events, and transport statistics.
+
+This combination gives GhostFile a production-proven implementation with a
+small and testable macOS integration surface. GhostHTTP3 builds quiche's
+supported `cdylib` output for arm64 and packages that one dylib as a dynamic
+framework; the backend can be upgraded or replaced without changing
+GhostFile's HTTP resource model.
+
+## GhostFile integration boundary
+
+GhostFile will use regular RFC 9114 semantics over UDP/QUIC:
+
+- standard HTTP methods and pseudoheaders;
+- HTTP status codes and response headers;
+- request and response bodies in HTTP/3 DATA frames;
+- one HTTP request stream per independent filesystem operation;
+- no GhostFile transport framing inside QUIC streams.
+
+The existing mDNS discovery remains appropriate for the LAN. Its service
+metadata should advertise `alpn=h3` and `transport=http3`; the discovered
+endpoint feeds either this framework's client API or Apple's HTTP/3-capable
+`URLSession` client.
diff --git a/macOS/GhostHTTP3/Sources/GhostHTTP3.c b/macOS/GhostHTTP3/Sources/GhostHTTP3.c
new file mode 100644
index 0000000..e338444
--- /dev/null
+++ b/macOS/GhostHTTP3/Sources/GhostHTTP3.c
@@ -0,0 +1,36 @@
+#include 
+
+uint32_t ghost_http3_api_version(void) {
+    return GHOST_HTTP3_API_VERSION;
+}
+
+const char *ghost_http3_backend_version(void) {
+    return quiche_version();
+}
+
+const uint8_t *ghost_http3_application_protocol(size_t *length) {
+    static const uint8_t protocol[] = QUICHE_H3_APPLICATION_PROTOCOL;
+
+    if (length != NULL) {
+        *length = sizeof(protocol) - 1;
+    }
+
+    return protocol;
+}
+
+bool ghost_http3_backend_is_ready(void) {
+    quiche_config *quic = quiche_config_new(QUICHE_PROTOCOL_VERSION);
+    if (quic == NULL) {
+        return false;
+    }
+
+    quiche_h3_config *http3 = quiche_h3_config_new();
+    if (http3 == NULL) {
+        quiche_config_free(quic);
+        return false;
+    }
+
+    quiche_h3_config_free(http3);
+    quiche_config_free(quic);
+    return true;
+}
diff --git a/macOS/GhostHTTP3/THIRD_PARTY_NOTICES.md b/macOS/GhostHTTP3/THIRD_PARTY_NOTICES.md
new file mode 100644
index 0000000..0eab9a8
--- /dev/null
+++ b/macOS/GhostHTTP3/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,26 @@
+# Third-party notices
+
+GhostHTTP3 incorporates [Cloudflare quiche](https://github.com/cloudflare/quiche),
+which is distributed under the BSD 2-Clause License:
+
+Copyright (C) 2018-2019, Cloudflare, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/macOS/GhostHTTP3/Tests/smoke.c b/macOS/GhostHTTP3/Tests/smoke.c
new file mode 100644
index 0000000..9536864
--- /dev/null
+++ b/macOS/GhostHTTP3/Tests/smoke.c
@@ -0,0 +1,28 @@
+#include 
+
+#include 
+#include 
+
+int main(void) {
+    size_t alpn_length = 0;
+    const uint8_t *alpn = ghost_http3_application_protocol(&alpn_length);
+
+    if (ghost_http3_api_version() != GHOST_HTTP3_API_VERSION) {
+        fprintf(stderr, "GhostHTTP3 API version mismatch\n");
+        return 1;
+    }
+
+    if (!ghost_http3_backend_is_ready()) {
+        fprintf(stderr, "quiche QUIC/HTTP3 backend failed its runtime check\n");
+        return 2;
+    }
+
+    if (alpn_length != 3 || alpn[0] != 2 || memcmp(alpn + 1, "h3", 2) != 0) {
+        fprintf(stderr, "unexpected HTTP/3 ALPN bytes\n");
+        return 3;
+    }
+
+    printf("GhostHTTP3 API %u, quiche %s, ALPN h3\n",
+           ghost_http3_api_version(), ghost_http3_backend_version());
+    return 0;
+}
diff --git a/macOS/GhostHTTP3/Tests/smoke.swift b/macOS/GhostHTTP3/Tests/smoke.swift
new file mode 100644
index 0000000..01dc115
--- /dev/null
+++ b/macOS/GhostHTTP3/Tests/smoke.swift
@@ -0,0 +1,8 @@
+import GhostHTTP3
+
+guard ghost_http3_backend_is_ready() else {
+    fatalError("GhostHTTP3 backend is not ready")
+}
+
+let backend = String(cString: ghost_http3_backend_version())
+print("Swift linked GhostHTTP3 API \(ghost_http3_api_version()), quiche \(backend)")
diff --git a/macOS/GhostHTTP3/Tests/stress.c b/macOS/GhostHTTP3/Tests/stress.c
new file mode 100644
index 0000000..d7c952e
--- /dev/null
+++ b/macOS/GhostHTTP3/Tests/stress.c
@@ -0,0 +1,1197 @@
+// Exercises the packaged GhostHTTP3/quiche library without a TCP or HTTP/1.x
+// fallback. Two HTTP/3 endpoints exchange QUIC datagrams in memory so the
+// test is deterministic while still traversing TLS, QUIC, QPACK, and RFC 9114.
+
+#include 
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#define CID_LEN 16
+#define DATAGRAM_CAPACITY 65535
+#define WIRE_DATAGRAM_CAPACITY 2048
+#define REORDER_BATCH_SIZE 4
+#define MAX_REQUESTS 256
+#define BODY_CHUNK 16384
+#define FAST_REQUEST_COUNT 96
+#define LARGE_REQUEST_COUNT 16
+#define LARGE_BODY_LENGTH (512 * 1024)
+#define CANCEL_BODY_LENGTH (32 * 1024 * 1024)
+// RFC 9114 §4.2 error codes for the wire-level application close that quiche
+// raises when a peer exceeds SETTINGS_MAX_FIELD_SECTION_SIZE: the QPACK
+// decoder reports HeaderListTooLarge and the h3 layer converts that to
+// Error::ExcessiveLoad, surfaced as a CONNECTION_CLOSE error code on the
+// wire. Used to verify rejection rather than "no crash" only.
+#define H3_EXCESSIVE_LOAD_ERROR 0x107
+#define H3_REQUEST_CANCELLED_ERROR 0x10c
+#define SERVER_RESET_ERROR 0x201
+#define CONNECTION_CLOSE_ERROR 0x102
+#define STREAM_LIMIT_TEST_COUNT 4
+#define MAX_FIELD_SECTION_SIZE_LIMIT 128
+
+#define CHECK(condition, ...) do { \
+    if (!(condition)) { \
+        fprintf(stderr, "FAIL: "); \
+        fprintf(stderr, __VA_ARGS__); \
+        fprintf(stderr, "\n"); \
+        exit(1); \
+    } \
+} while (0)
+
+typedef struct {
+    quiche_conn *quic;
+    quiche_h3_conn *h3;
+    struct sockaddr_storage local;
+    socklen_t local_len;
+    struct sockaddr_storage peer;
+    socklen_t peer_len;
+} endpoint;
+
+typedef struct {
+    endpoint client;
+    endpoint server;
+    quiche_config *client_config;
+    quiche_config *server_config;
+    quiche_h3_config *client_h3_config;
+    quiche_h3_config *server_h3_config;
+    size_t datagrams;
+    bool reorder_datagrams;
+    size_t reordered_batches;
+} test_pair;
+
+typedef struct {
+    uint8_t bytes[WIRE_DATAGRAM_CAPACITY];
+    size_t length;
+    quiche_send_info send_info;
+} queued_packet;
+
+typedef struct {
+    uint64_t stream_id;
+    char path[16384];
+    bool headers_sent;
+    bool finished;
+    bool abandoned;
+    bool server_reset_after_partial;
+    bool server_reset_sent;
+    size_t body_length;
+    size_t body_sent;
+    uint8_t seed;
+} server_response;
+
+typedef struct {
+    server_response responses[MAX_REQUESTS];
+    size_t response_count;
+    int64_t paused_stream;
+    int64_t blackholed_stream;
+    bool paused_released;
+    bool goaway_sent;
+    size_t reset_count;
+} server_state;
+
+typedef struct {
+    uint64_t stream_id;
+    char path[128];
+    size_t expected_length;
+    size_t body_received;
+    uint8_t seed;
+    int status;
+    bool saw_headers;
+    bool finished;
+    bool cancel_on_headers;
+    bool cancellation_sent;
+    bool expect_server_reset;
+    bool saw_reset;
+} client_request;
+
+typedef struct {
+    client_request requests[MAX_REQUESTS];
+    size_t request_count;
+    bool saw_goaway;
+} client_state;
+
+typedef struct {
+    char path[16384];
+    int status;
+    size_t content_length;
+    bool saw_path;
+    bool saw_status;
+    bool saw_content_length;
+} parsed_headers;
+
+static size_t future_pacing_packets = 0;
+
+static bool send_time_is_future(const struct timespec *send_time) {
+    struct timespec now;
+    CHECK(clock_gettime(CLOCK_MONOTONIC, &now) == 0,
+          "could not read Darwin monotonic clock");
+    return send_time->tv_sec > now.tv_sec ||
+        (send_time->tv_sec == now.tv_sec && send_time->tv_nsec > now.tv_nsec);
+}
+
+static void make_address(struct sockaddr_storage *storage, socklen_t *length,
+                         uint16_t port) {
+    struct sockaddr_in *address = (struct sockaddr_in *) storage;
+    memset(storage, 0, sizeof(*storage));
+    address->sin_family = AF_INET;
+    address->sin_port = htons(port);
+    address->sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    *length = sizeof(*address);
+}
+
+static quiche_config *make_config_with_stream_limit(bool server,
+                                                     const char *cert_path,
+                                                     const char *key_path,
+                                                     uint64_t max_streams_bidi) {
+    quiche_config *config = quiche_config_new(QUICHE_PROTOCOL_VERSION);
+    CHECK(config != NULL, "could not create QUIC config");
+    CHECK(quiche_config_set_application_protos(
+              config, (const uint8_t *) QUICHE_H3_APPLICATION_PROTOCOL,
+              sizeof(QUICHE_H3_APPLICATION_PROTOCOL) - 1) == 0,
+          "could not configure h3 ALPN");
+
+    if (server) {
+        CHECK(quiche_config_load_cert_chain_from_pem_file(config, cert_path) == 0,
+              "could not load test certificate at %s", cert_path);
+        CHECK(quiche_config_load_priv_key_from_pem_file(config, key_path) == 0,
+              "could not load test private key at %s", key_path);
+    } else {
+        quiche_config_verify_peer(config, false);
+    }
+
+    quiche_config_set_max_idle_timeout(config, 30000);
+    quiche_config_set_max_recv_udp_payload_size(config, 1350);
+    quiche_config_set_max_send_udp_payload_size(config, 1350);
+    // BBR2 is enabled only in this in-memory framework test to force observable
+    // future deadlines and verify the packaged Darwin send-time conversion.
+    // GhostFile production traffic retains quiche's default CUBIC controller.
+    quiche_config_set_cc_algorithm(config, QUICHE_CC_BBR2_GCONGESTION);
+    quiche_config_enable_pacing(config, true);
+    quiche_config_set_max_pacing_rate(config, 64 * 1024);
+    quiche_config_set_initial_max_data(config, 64 * 1024 * 1024);
+    quiche_config_set_initial_max_stream_data_bidi_local(config, 2 * 1024 * 1024);
+    quiche_config_set_initial_max_stream_data_bidi_remote(config, 2 * 1024 * 1024);
+    quiche_config_set_initial_max_stream_data_uni(config, 2 * 1024 * 1024);
+    quiche_config_set_initial_max_streams_bidi(config, max_streams_bidi);
+    quiche_config_set_initial_max_streams_uni(config, 16);
+    quiche_config_set_disable_active_migration(config, true);
+    return config;
+}
+
+static quiche_config *make_config(bool server, const char *cert_path,
+                                  const char *key_path) {
+    return make_config_with_stream_limit(server, cert_path, key_path, MAX_REQUESTS);
+}
+
+static ssize_t deliver_first_client_packet(test_pair *pair, uint8_t *packet,
+                                           quiche_send_info *send_info) {
+    ssize_t length = quiche_conn_send(pair->client.quic, packet,
+                                      DATAGRAM_CAPACITY, send_info);
+    CHECK(length > 0, "client did not produce an Initial packet: %zd", length);
+    CHECK(send_info->at.tv_sec > 0 || send_info->at.tv_nsec > 0,
+          "quiche returned no usable send timestamp on Darwin");
+
+    uint32_t version = 0;
+    uint8_t type = 0;
+    uint8_t scid[QUICHE_MAX_CONN_ID_LEN];
+    uint8_t dcid[QUICHE_MAX_CONN_ID_LEN];
+    uint8_t token[256];
+    size_t scid_len = sizeof(scid);
+    size_t dcid_len = sizeof(dcid);
+    size_t token_len = sizeof(token);
+    CHECK(quiche_header_info(packet, (size_t) length, CID_LEN, &version, &type,
+                             scid, &scid_len, dcid, &dcid_len,
+                             token, &token_len) == 0,
+          "could not parse client Initial packet");
+
+    uint8_t server_scid[CID_LEN];
+    for (size_t i = 0; i < sizeof(server_scid); i++) {
+        server_scid[i] = (uint8_t) (0xa0 + i);
+    }
+    pair->server.quic = quiche_accept(
+        server_scid, sizeof(server_scid), dcid, dcid_len,
+        (const struct sockaddr *) &pair->server.local, pair->server.local_len,
+        (const struct sockaddr *) &pair->server.peer, pair->server.peer_len,
+        pair->server_config);
+    CHECK(pair->server.quic != NULL, "could not create server QUIC connection");
+
+    quiche_recv_info receive_info = {
+        .from = (struct sockaddr *) &send_info->from,
+        .from_len = send_info->from_len,
+        .to = (struct sockaddr *) &send_info->to,
+        .to_len = send_info->to_len,
+    };
+    CHECK(quiche_conn_recv(pair->server.quic, packet, (size_t) length,
+                           &receive_info) == length,
+          "server rejected client Initial packet");
+    pair->datagrams++;
+    return length;
+}
+
+static void deliver_packet(endpoint *to, queued_packet *packet) {
+    quiche_recv_info receive_info = {
+        .from = (struct sockaddr *) &packet->send_info.from,
+        .from_len = packet->send_info.from_len,
+        .to = (struct sockaddr *) &packet->send_info.to,
+        .to_len = packet->send_info.to_len,
+    };
+    ssize_t accepted = quiche_conn_recv(to->quic, packet->bytes,
+                                        packet->length, &receive_info);
+    CHECK(accepted == (ssize_t) packet->length,
+          "peer rejected QUIC packet: %zd", accepted);
+}
+
+static size_t transfer(endpoint *from, endpoint *to, bool reorder,
+                       size_t *reordered_batches) {
+    size_t transferred = 0;
+    for (;;) {
+        queued_packet batch[REORDER_BATCH_SIZE];
+        size_t batch_count = 0;
+        while (batch_count < REORDER_BATCH_SIZE) {
+            queued_packet *packet = &batch[batch_count];
+            ssize_t length = quiche_conn_send(
+                from->quic, packet->bytes, sizeof(packet->bytes),
+                &packet->send_info);
+            if (length == QUICHE_ERR_DONE) {
+                break;
+            }
+            CHECK(length > 0, "QUIC packet generation failed: %zd", length);
+            packet->length = (size_t) length;
+            if (send_time_is_future(&packet->send_info.at)) {
+                future_pacing_packets++;
+            }
+            batch_count++;
+        }
+        if (batch_count == 0) {
+            break;
+        }
+        if (reorder && batch_count > 1) {
+            for (size_t i = batch_count; i > 0; i--) {
+                deliver_packet(to, &batch[i - 1]);
+            }
+            (*reordered_batches)++;
+        } else {
+            for (size_t i = 0; i < batch_count; i++) {
+                deliver_packet(to, &batch[i]);
+            }
+        }
+        transferred += batch_count;
+        CHECK(transferred < 100000, "QUIC transfer loop did not quiesce");
+    }
+    return transferred;
+}
+
+static size_t pump_transport(test_pair *pair) {
+    size_t total = 0;
+    for (size_t round = 0; round < 10000; round++) {
+        size_t moved = transfer(&pair->client, &pair->server,
+                                pair->reorder_datagrams,
+                                &pair->reordered_batches);
+        moved += transfer(&pair->server, &pair->client,
+                          pair->reorder_datagrams,
+                          &pair->reordered_batches);
+        total += moved;
+        if (moved == 0) {
+            pair->datagrams += total;
+            return total;
+        }
+    }
+    CHECK(false, "QUIC transport did not quiesce");
+    return 0;
+}
+
+static void assert_h3_alpn(endpoint *value, const char *side) {
+    const uint8_t *protocol = NULL;
+    size_t protocol_length = 0;
+    quiche_conn_application_proto(value->quic, &protocol, &protocol_length);
+    CHECK(protocol_length == 2 && memcmp(protocol, "h3", 2) == 0,
+          "%s negotiated unexpected ALPN", side);
+}
+
+static void pair_create_internal(test_pair *pair, const char *cert_path,
+                                  const char *key_path,
+                                  uint64_t server_max_streams_bidi,
+                                  uint64_t max_field_section_size,
+                                  uint16_t client_port) {
+    memset(pair, 0, sizeof(*pair));
+    make_address(&pair->client.local, &pair->client.local_len, client_port);
+    make_address(&pair->client.peer, &pair->client.peer_len, client_port + 1);
+    pair->server.local = pair->client.peer;
+    pair->server.local_len = pair->client.peer_len;
+    pair->server.peer = pair->client.local;
+    pair->server.peer_len = pair->client.local_len;
+
+    pair->client_config = make_config(false, cert_path, key_path);
+    pair->server_config = make_config_with_stream_limit(
+        true, cert_path, key_path, server_max_streams_bidi);
+
+    uint8_t client_scid[CID_LEN];
+    for (size_t i = 0; i < sizeof(client_scid); i++) {
+        client_scid[i] = (uint8_t) (0x10 + i);
+    }
+    pair->client.quic = quiche_connect(
+        "localhost", client_scid, sizeof(client_scid),
+        (const struct sockaddr *) &pair->client.local, pair->client.local_len,
+        (const struct sockaddr *) &pair->client.peer, pair->client.peer_len,
+        pair->client_config);
+    CHECK(pair->client.quic != NULL, "could not create client QUIC connection");
+
+    uint8_t first_packet[DATAGRAM_CAPACITY];
+    quiche_send_info first_send_info;
+    deliver_first_client_packet(pair, first_packet, &first_send_info);
+
+    for (size_t round = 0; round < 1000; round++) {
+        pump_transport(pair);
+        if (quiche_conn_is_established(pair->client.quic) &&
+            quiche_conn_is_established(pair->server.quic)) {
+            break;
+        }
+    }
+    CHECK(quiche_conn_is_established(pair->client.quic),
+          "client QUIC handshake did not complete");
+    CHECK(quiche_conn_is_established(pair->server.quic),
+          "server QUIC handshake did not complete");
+    assert_h3_alpn(&pair->client, "client");
+    assert_h3_alpn(&pair->server, "server");
+
+    pair->client_h3_config = quiche_h3_config_new();
+    pair->server_h3_config = quiche_h3_config_new();
+    CHECK(pair->client_h3_config != NULL && pair->server_h3_config != NULL,
+          "could not create HTTP/3 configs");
+    quiche_h3_config_set_qpack_max_table_capacity(pair->client_h3_config, 4096);
+    quiche_h3_config_set_qpack_blocked_streams(pair->client_h3_config, 100);
+    quiche_h3_config_set_qpack_max_table_capacity(pair->server_h3_config, 4096);
+    quiche_h3_config_set_qpack_blocked_streams(pair->server_h3_config, 100);
+    if (max_field_section_size > 0) {
+        quiche_h3_config_set_max_field_section_size(
+            pair->server_h3_config, max_field_section_size);
+    }
+
+    pair->client.h3 = quiche_h3_conn_new_with_transport(
+        pair->client.quic, pair->client_h3_config);
+    pair->server.h3 = quiche_h3_conn_new_with_transport(
+        pair->server.quic, pair->server_h3_config);
+    CHECK(pair->client.h3 != NULL && pair->server.h3 != NULL,
+          "could not create HTTP/3 connections");
+    pump_transport(pair);
+}
+
+static void pair_create(test_pair *pair, const char *cert_path,
+                        const char *key_path) {
+    pair_create_internal(pair, cert_path, key_path, MAX_REQUESTS, 0, 41000);
+}
+
+static void pair_free(test_pair *pair) {
+    quiche_h3_conn_free(pair->client.h3);
+    quiche_h3_conn_free(pair->server.h3);
+    quiche_conn_free(pair->client.quic);
+    quiche_conn_free(pair->server.quic);
+    quiche_h3_config_free(pair->client_h3_config);
+    quiche_h3_config_free(pair->server_h3_config);
+    quiche_config_free(pair->client_config);
+    quiche_config_free(pair->server_config);
+}
+
+static int parse_header(uint8_t *name, size_t name_length, uint8_t *value,
+                        size_t value_length, void *context) {
+    parsed_headers *headers = context;
+    if (name_length == 5 && memcmp(name, ":path", 5) == 0) {
+        CHECK(value_length < sizeof(headers->path), "request path is too large");
+        memcpy(headers->path, value, value_length);
+        headers->path[value_length] = '\0';
+        headers->saw_path = true;
+    } else if (name_length == 7 && memcmp(name, ":status", 7) == 0) {
+        char status[4] = {0};
+        CHECK(value_length == 3, "malformed :status value");
+        memcpy(status, value, value_length);
+        headers->status = atoi(status);
+        headers->saw_status = true;
+    } else if (name_length == 14 &&
+               memcmp(name, "content-length", 14) == 0) {
+        char length[32] = {0};
+        CHECK(value_length < sizeof(length), "content-length is too large");
+        memcpy(length, value, value_length);
+        headers->content_length = (size_t) strtoull(length, NULL, 10);
+        headers->saw_content_length = true;
+    }
+    return 0;
+}
+
+static uint8_t body_byte(uint8_t seed, size_t offset) {
+    return (uint8_t) (seed + (offset * 31u) + (offset >> 8));
+}
+
+static server_response *server_find(server_state *state, uint64_t stream_id) {
+    for (size_t i = 0; i < state->response_count; i++) {
+        if (state->responses[i].stream_id == stream_id) {
+            return &state->responses[i];
+        }
+    }
+    return NULL;
+}
+
+static server_response *server_add(server_state *state, uint64_t stream_id,
+                                   const char *path) {
+    CHECK(state->response_count < MAX_REQUESTS, "too many server requests");
+    server_response *response = &state->responses[state->response_count++];
+    memset(response, 0, sizeof(*response));
+    response->stream_id = stream_id;
+    CHECK(strlen(path) < sizeof(response->path), "server path overflow");
+    strcpy(response->path, path);
+    return response;
+}
+
+static void configure_server_response(server_state *state,
+                                      server_response *response) {
+    unsigned index = 0;
+    if (strcmp(response->path, "/paused") == 0) {
+        state->paused_stream = (int64_t) response->stream_id;
+        response->body_length = 11;
+        response->seed = 0x71;
+        return;
+    }
+    if (strcmp(response->path, "/blackhole") == 0) {
+        state->blackholed_stream = (int64_t) response->stream_id;
+        // Model an application that accepted a request but never generated
+        // headers or a body. Other HTTP/3 streams must remain independent.
+        response->abandoned = true;
+        return;
+    }
+    if (strcmp(response->path, "/empty") == 0) {
+        response->body_length = 0;
+        response->seed = 0;
+        return;
+    }
+    if (strcmp(response->path, "/cancel") == 0) {
+        response->body_length = CANCEL_BODY_LENGTH;
+        response->seed = 0xc1;
+        return;
+    }
+    if (strcmp(response->path, "/server-reset") == 0) {
+        response->body_length = LARGE_BODY_LENGTH;
+        response->seed = 0xd1;
+        response->server_reset_after_partial = true;
+        return;
+    }
+    if (sscanf(response->path, "/fast/%u", &index) == 1) {
+        response->body_length = 257 + (index % 127);
+        response->seed = (uint8_t) index;
+        return;
+    }
+    if (sscanf(response->path, "/large/%u", &index) == 1) {
+        response->body_length = LARGE_BODY_LENGTH;
+        response->seed = (uint8_t) (0x40 + index);
+        return;
+    }
+    CHECK(false, "server received unknown path: %s", response->path);
+}
+
+static bool send_response_headers(test_pair *pair, server_response *response) {
+    char length[32];
+    snprintf(length, sizeof(length), "%zu", response->body_length);
+    const char *status = response->body_length == 0 ? "204" : "200";
+    quiche_h3_header headers[] = {
+        {(const uint8_t *) ":status", 7,
+         (const uint8_t *) status, strlen(status)},
+        {(const uint8_t *) "content-length", 14,
+         (const uint8_t *) length, strlen(length)},
+        {(const uint8_t *) "server", 6,
+         (const uint8_t *) "ghost-http3-stress", 18},
+    };
+    int result = quiche_h3_send_response(
+        pair->server.h3, pair->server.quic, response->stream_id,
+        headers, sizeof(headers) / sizeof(headers[0]),
+        response->body_length == 0);
+    if (result == QUICHE_H3_ERR_DONE ||
+        result == QUICHE_H3_ERR_STREAM_BLOCKED) {
+        return false;
+    }
+    CHECK(result == 0, "could not send response headers on stream %" PRIu64
+          ": %d", response->stream_id, result);
+    response->headers_sent = true;
+    response->finished = response->body_length == 0;
+    return true;
+}
+
+static void server_poll(test_pair *pair, server_state *state) {
+    for (size_t count = 0; count < 10000; count++) {
+        quiche_h3_event *event = NULL;
+        int64_t stream_id = quiche_h3_conn_poll(
+            pair->server.h3, pair->server.quic, &event);
+        if (stream_id < 0) {
+            return;
+        }
+
+        switch (quiche_h3_event_type(event)) {
+        case QUICHE_H3_EVENT_HEADERS: {
+            parsed_headers headers = {0};
+            CHECK(quiche_h3_event_for_each_header(event, parse_header,
+                                                   &headers) == 0,
+                  "could not parse request headers");
+            CHECK(headers.saw_path, "request omitted :path");
+            if (server_find(state, (uint64_t) stream_id) == NULL) {
+                server_response *response = server_add(
+                    state, (uint64_t) stream_id, headers.path);
+                configure_server_response(state, response);
+            }
+            break;
+        }
+        case QUICHE_H3_EVENT_DATA: {
+            uint8_t discard[4096];
+            while (quiche_h3_recv_body(pair->server.h3, pair->server.quic,
+                                       (uint64_t) stream_id, discard,
+                                       sizeof(discard)) > 0) {}
+            break;
+        }
+        case QUICHE_H3_EVENT_RESET:
+            state->reset_count++;
+            break;
+        case QUICHE_H3_EVENT_FINISHED:
+        case QUICHE_H3_EVENT_GOAWAY:
+        case QUICHE_H3_EVENT_PRIORITY_UPDATE:
+            break;
+        }
+        quiche_h3_event_free(event);
+    }
+    CHECK(false, "server HTTP/3 event loop did not quiesce");
+}
+
+static void server_flush(test_pair *pair, server_state *state) {
+    uint8_t body[BODY_CHUNK];
+    for (size_t i = 0; i < state->response_count; i++) {
+        server_response *response = &state->responses[i];
+        if (response->finished || response->abandoned) {
+            continue;
+        }
+        if (!response->headers_sent) {
+            if ((int64_t) response->stream_id == state->paused_stream &&
+                !state->paused_released) {
+                continue;
+            }
+            if (!send_response_headers(pair, response)) {
+                continue;
+            }
+            if (response->finished) {
+                continue;
+            }
+        }
+
+        if (response->server_reset_after_partial && !response->server_reset_sent) {
+            if (response->body_sent >= BODY_CHUNK) {
+                int result = quiche_conn_stream_shutdown(
+                    pair->server.quic, response->stream_id,
+                    QUICHE_SHUTDOWN_WRITE, SERVER_RESET_ERROR);
+                CHECK(result == 0, "server stream reset failed on %" PRIu64
+                      ": %d", response->stream_id, result);
+                response->server_reset_sent = true;
+                response->abandoned = true;
+                state->reset_count++;
+                continue;
+            }
+        }
+
+        size_t remaining = response->body_length - response->body_sent;
+        size_t length = remaining < sizeof(body) ? remaining : sizeof(body);
+        for (size_t j = 0; j < length; j++) {
+            body[j] = body_byte(response->seed, response->body_sent + j);
+        }
+        bool final = length == remaining;
+        ssize_t sent = quiche_h3_send_body(
+            pair->server.h3, pair->server.quic, response->stream_id,
+            body, length, final);
+        if (sent == QUICHE_H3_ERR_DONE || sent == QUICHE_H3_ERR_STREAM_BLOCKED) {
+            continue;
+        }
+        if (sent == QUICHE_H3_TRANSPORT_ERR_STREAM_STOPPED ||
+            sent == QUICHE_H3_TRANSPORT_ERR_STREAM_RESET) {
+            response->abandoned = true;
+            state->reset_count++;
+            continue;
+        }
+        CHECK(sent > 0, "body send failed on stream %" PRIu64 ": %zd",
+              response->stream_id, sent);
+        response->body_sent += (size_t) sent;
+        if (response->body_sent == response->body_length) {
+            response->finished = true;
+        }
+    }
+}
+
+static client_request *client_find(client_state *state, uint64_t stream_id) {
+    for (size_t i = 0; i < state->request_count; i++) {
+        if (state->requests[i].stream_id == stream_id) {
+            return &state->requests[i];
+        }
+    }
+    return NULL;
+}
+
+static size_t client_send(test_pair *pair, client_state *state,
+                          const char *path, size_t expected_length,
+                          uint8_t seed, bool cancel_on_headers,
+                          bool padded_headers, bool expect_server_reset) {
+    CHECK(state->request_count < MAX_REQUESTS, "too many client requests");
+    static uint8_t padding[12 * 1024];
+    static bool padding_ready = false;
+    if (!padding_ready) {
+        memset(padding, 'p', sizeof(padding));
+        padding_ready = true;
+    }
+    quiche_h3_header headers[] = {
+        {(const uint8_t *) ":method", 7, (const uint8_t *) "GET", 3},
+        {(const uint8_t *) ":scheme", 7, (const uint8_t *) "https", 5},
+        {(const uint8_t *) ":authority", 10,
+         (const uint8_t *) "ghostfile.test", 14},
+        {(const uint8_t *) ":path", 5,
+         (const uint8_t *) path, strlen(path)},
+        {(const uint8_t *) "user-agent", 10,
+         (const uint8_t *) "ghost-http3-stress", 18},
+        {(const uint8_t *) "x-ghost-padding", 15,
+         padding, padded_headers ? sizeof(padding) : 0},
+    };
+    size_t header_count = padded_headers ? 6 : 5;
+    int64_t stream_id = quiche_h3_send_request(
+        pair->client.h3, pair->client.quic, headers, header_count, true);
+    CHECK(stream_id >= 0, "could not send %s: %" PRId64, path, stream_id);
+
+    size_t index = state->request_count++;
+    client_request *request = &state->requests[index];
+    memset(request, 0, sizeof(*request));
+    request->stream_id = (uint64_t) stream_id;
+    snprintf(request->path, sizeof(request->path), "%s", path);
+    request->expected_length = expected_length;
+    request->seed = seed;
+    request->cancel_on_headers = cancel_on_headers;
+    request->expect_server_reset = expect_server_reset;
+    return index;
+}
+
+static void client_poll(test_pair *pair, client_state *state) {
+    for (size_t count = 0; count < 10000; count++) {
+        quiche_h3_event *event = NULL;
+        int64_t stream_id = quiche_h3_conn_poll(
+            pair->client.h3, pair->client.quic, &event);
+        if (stream_id < 0) {
+            return;
+        }
+
+        if (quiche_h3_event_type(event) == QUICHE_H3_EVENT_GOAWAY) {
+            state->saw_goaway = true;
+            quiche_h3_event_free(event);
+            continue;
+        }
+
+        client_request *request = client_find(state, (uint64_t) stream_id);
+        CHECK(request != NULL, "event for unknown client stream %" PRId64,
+              stream_id);
+
+        switch (quiche_h3_event_type(event)) {
+        case QUICHE_H3_EVENT_HEADERS: {
+            parsed_headers headers = {0};
+            CHECK(quiche_h3_event_for_each_header(event, parse_header,
+                                                   &headers) == 0,
+                  "could not parse response headers");
+            CHECK(headers.saw_status && headers.saw_content_length,
+                  "response omitted required headers on %s", request->path);
+            if (!request->expect_server_reset) {
+                CHECK(headers.content_length == request->expected_length,
+                      "content-length mismatch on %s: %zu != %zu",
+                      request->path, headers.content_length,
+                      request->expected_length);
+            }
+            request->status = headers.status;
+            request->saw_headers = true;
+            if (request->cancel_on_headers && !request->cancellation_sent) {
+                int result = quiche_conn_stream_shutdown(
+                    pair->client.quic, request->stream_id,
+                    QUICHE_SHUTDOWN_READ, H3_REQUEST_CANCELLED_ERROR);
+                CHECK(result == 0, "could not cancel stream %" PRIu64 ": %d",
+                      request->stream_id, result);
+                request->cancellation_sent = true;
+            }
+            break;
+        }
+        case QUICHE_H3_EVENT_DATA: {
+            if (request->cancellation_sent) {
+                break;
+            }
+            uint8_t body[32768];
+            for (;;) {
+                ssize_t received = quiche_h3_recv_body(
+                    pair->client.h3, pair->client.quic, request->stream_id,
+                    body, sizeof(body));
+                if (received <= 0) {
+                    break;
+                }
+                if (!request->expect_server_reset) {
+                    for (ssize_t i = 0; i < received; i++) {
+                        uint8_t expected = body_byte(
+                            request->seed, request->body_received + (size_t) i);
+                        CHECK(body[i] == expected,
+                              "body corruption on %s at offset %zu",
+                              request->path,
+                              request->body_received + (size_t) i);
+                    }
+                }
+                request->body_received += (size_t) received;
+                CHECK(request->body_received <= request->expected_length,
+                      "body overflow on %s", request->path);
+            }
+            break;
+        }
+        case QUICHE_H3_EVENT_FINISHED:
+            CHECK(request->saw_headers, "stream finished before headers: %s",
+                  request->path);
+            CHECK(request->body_received == request->expected_length,
+                  "short body on %s: %zu != %zu", request->path,
+                  request->body_received, request->expected_length);
+            request->finished = true;
+            break;
+        case QUICHE_H3_EVENT_RESET:
+            CHECK(request->cancellation_sent || request->expect_server_reset,
+                  "unexpected reset on %s", request->path);
+            request->saw_reset = true;
+            break;
+        case QUICHE_H3_EVENT_GOAWAY:
+        case QUICHE_H3_EVENT_PRIORITY_UPDATE:
+            break;
+        }
+        quiche_h3_event_free(event);
+    }
+    CHECK(false, "client HTTP/3 event loop did not quiesce");
+}
+
+static void drive_round(test_pair *pair, server_state *server,
+                        client_state *client) {
+    pump_transport(pair);
+    server_poll(pair, server);
+    server_flush(pair, server);
+    pump_transport(pair);
+    client_poll(pair, client);
+}
+
+static bool requests_finished(client_state *state, size_t first, size_t count) {
+    for (size_t i = first; i < first + count; i++) {
+        if (!state->requests[i].finished) {
+            return false;
+        }
+    }
+    return true;
+}
+
+static void drive_until_finished(test_pair *pair, server_state *server,
+                                 client_state *client, size_t first,
+                                 size_t count, const char *label) {
+    for (size_t round = 0; round < 200000; round++) {
+        drive_round(pair, server, client);
+        if (requests_finished(client, first, count)) {
+            return;
+        }
+        CHECK(!quiche_conn_is_closed(pair->client.quic) &&
+              !quiche_conn_is_closed(pair->server.quic),
+              "connection closed during %s", label);
+    }
+    CHECK(false, "%s timed out", label);
+}
+
+int main(int argc, char **argv) {
+    CHECK(argc == 3, "usage: %s cert.crt cert.key", argv[0]);
+    CHECK(ghost_http3_backend_is_ready(), "GhostHTTP3 backend is not ready");
+
+    test_pair pair;
+    server_state server = {.paused_stream = -1, .blackholed_stream = -1};
+    client_state client = {0};
+    pair_create(&pair, argv[1], argv[2]);
+    printf("PASS handshake: TLS over QUIC negotiated ALPN h3\n");
+    pair.reorder_datagrams = true;
+
+    size_t empty = client_send(&pair, &client, "/empty", 0, 0,
+                               false, true, false);
+    drive_until_finished(&pair, &server, &client, empty, 1,
+                         "empty response and oversized request headers");
+    CHECK(client.requests[empty].status == 204,
+          "empty response had status %d", client.requests[empty].status);
+    printf("PASS edge headers: 12 KiB header block and zero-byte 204 response\n");
+
+    size_t paused = client_send(&pair, &client, "/paused", 11, 0x71,
+                                false, false, false);
+    size_t fast_first = client.request_count;
+    for (unsigned i = 0; i < FAST_REQUEST_COUNT; i++) {
+        char path[64];
+        snprintf(path, sizeof(path), "/fast/%u", i);
+        client_send(&pair, &client, path, 257 + (i % 127), (uint8_t) i,
+                    false, (i % 19) == 0, false);
+        if ((i % 8) == 7) {
+            drive_round(&pair, &server, &client);
+        }
+    }
+    drive_until_finished(&pair, &server, &client, fast_first,
+                         FAST_REQUEST_COUNT, "multiplexed fast requests");
+    CHECK(server.paused_stream == (int64_t) client.requests[paused].stream_id,
+          "server did not observe the paused stream");
+    CHECK(!client.requests[paused].saw_headers &&
+          !client.requests[paused].finished,
+          "paused request unexpectedly completed before fast requests");
+    printf("PASS multiplexing: %d requests completed while an earlier stream was paused\n",
+           FAST_REQUEST_COUNT);
+
+    server.paused_released = true;
+    drive_until_finished(&pair, &server, &client, paused, 1,
+                         "released paused request");
+    printf("PASS stream resumption: paused request completed after release\n");
+
+    size_t blackholed = client_send(&pair, &client, "/blackhole", 0, 0,
+                                    false, false, false);
+    size_t after_blackhole_first = client.request_count;
+    for (unsigned i = 2000; i < 2016; i++) {
+        char path[64];
+        snprintf(path, sizeof(path), "/fast/%u", i);
+        client_send(&pair, &client, path, 257 + (i % 127), (uint8_t) i,
+                    false, false, false);
+    }
+    drive_until_finished(&pair, &server, &client, after_blackhole_first, 16,
+                         "requests after a black-holed stream");
+    CHECK(server.blackholed_stream ==
+              (int64_t) client.requests[blackholed].stream_id,
+          "server did not observe the black-holed stream");
+    CHECK(!client.requests[blackholed].saw_headers &&
+              !client.requests[blackholed].finished,
+          "black-holed request unexpectedly produced a response");
+    int cancel_blackhole = quiche_conn_stream_shutdown(
+        pair.client.quic, client.requests[blackholed].stream_id,
+        QUICHE_SHUTDOWN_READ, H3_REQUEST_CANCELLED_ERROR);
+    CHECK(cancel_blackhole == 0,
+          "could not cancel black-holed stream %" PRIu64 ": %d",
+          client.requests[blackholed].stream_id, cancel_blackhole);
+    client.requests[blackholed].cancellation_sent = true;
+    for (size_t round = 0; round < 32; round++) {
+        drive_round(&pair, &server, &client);
+    }
+    ssize_t stopped_capacity = quiche_conn_stream_capacity(
+        pair.server.quic, client.requests[blackholed].stream_id);
+    CHECK(stopped_capacity == QUICHE_ERR_STREAM_STOPPED,
+          "server did not observe STOP_SENDING for cancelled stream %" PRIu64
+          ": %zd",
+          client.requests[blackholed].stream_id, stopped_capacity);
+    CHECK(!quiche_conn_is_closed(pair.client.quic) &&
+              !quiche_conn_is_closed(pair.server.quic),
+          "black-holed stream cancellation closed the connection");
+    printf("PASS black-holed stream: 16 later requests completed and the stalled stream was cancelled independently\n");
+
+    size_t large_first = client.request_count;
+    for (unsigned i = 0; i < LARGE_REQUEST_COUNT; i++) {
+        char path[64];
+        snprintf(path, sizeof(path), "/large/%u", i);
+        client_send(&pair, &client, path, LARGE_BODY_LENGTH,
+                    (uint8_t) (0x40 + i), false, false, false);
+        if ((i % 8) == 7) {
+            drive_round(&pair, &server, &client);
+        }
+    }
+    drive_until_finished(&pair, &server, &client, large_first,
+                         LARGE_REQUEST_COUNT, "parallel large bodies");
+    CHECK(future_pacing_packets > 0,
+          "quiche produced no future pacing deadlines during large responses");
+    printf("PASS parallel bodies: %d x %d KiB verified byte-for-byte\n",
+           LARGE_REQUEST_COUNT, LARGE_BODY_LENGTH / 1024);
+    printf("PASS Darwin pacing timestamps: %zu future packet deadlines observed\n",
+           future_pacing_packets);
+
+    size_t cancelled = client_send(&pair, &client, "/cancel",
+                                    CANCEL_BODY_LENGTH, 0xc1, true, false,
+                                    false);
+    size_t post_cancel_first = client.request_count;
+    for (unsigned i = 1000; i < 1016; i++) {
+        char path[64];
+        snprintf(path, sizeof(path), "/fast/%u", i);
+        client_send(&pair, &client, path, 257 + (i % 127), (uint8_t) i,
+                    false, false, false);
+        if ((i % 8) == 7) {
+            drive_round(&pair, &server, &client);
+        }
+    }
+    drive_until_finished(&pair, &server, &client, post_cancel_first, 16,
+                         "requests after cancellation");
+    CHECK(client.requests[cancelled].cancellation_sent,
+          "large response was not cancelled");
+    CHECK(!quiche_conn_is_closed(pair.client.quic),
+          "cancelling one stream closed the connection");
+    printf("PASS cancellation: reset a 32 MiB stream; 16 sibling requests survived\n");
+
+    size_t reuse = client_send(&pair, &client, "/fast/4242",
+                               257 + (4242 % 127), (uint8_t) 4242,
+                               false, true, false);
+    drive_until_finished(&pair, &server, &client, reuse, 1,
+                         "connection reuse");
+    CHECK(pair.reordered_batches > 0,
+          "test traffic never produced a reorderable packet batch");
+
+    quiche_stats stats;
+    quiche_conn_stats(pair.client.quic, &stats);
+    printf("PASS connection reuse: %zu request streams on one h3 connection\n",
+           client.request_count);
+    printf("PASS packet reordering: %zu datagram batches delivered in reverse order\n",
+           pair.reordered_batches);
+    printf("PASS GhostHTTP3 stress: datagrams=%zu sent=%zu recv=%zu lost=%zu\n",
+           pair.datagrams, stats.sent, stats.recv, stats.lost);
+
+    size_t reset_idx = client_send(&pair, &client, "/server-reset",
+                                    LARGE_BODY_LENGTH, 0xd1, false, false,
+                                    true);
+    for (size_t round = 0; round < 200000; round++) {
+        drive_round(&pair, &server, &client);
+        if (client.requests[reset_idx].saw_reset) {
+            break;
+        }
+        CHECK(!quiche_conn_is_closed(pair.client.quic) &&
+              !quiche_conn_is_closed(pair.server.quic),
+              "connection closed during server-initiated reset");
+    }
+    CHECK(client.requests[reset_idx].saw_reset,
+          "client did not observe server reset");
+    CHECK(client.requests[reset_idx].saw_headers,
+          "client did not see headers before server reset");
+    CHECK(client.requests[reset_idx].body_received > 0,
+          "client received no body before server reset");
+    CHECK(client.requests[reset_idx].body_received < LARGE_BODY_LENGTH,
+          "client received full body despite expecting server reset");
+    printf("PASS server reset: stream reset mid-response after %" PRId64 " bytes\n",
+           (int64_t) client.requests[reset_idx].body_received);
+
+    size_t normal_after_reset = client_send(&pair, &client, "/fast/9999",
+                                             257 + (9999 % 127),
+                                             (uint8_t) 9999, false, false,
+                                             false);
+    drive_until_finished(&pair, &server, &client, normal_after_reset, 1,
+                         "request after server-initiated reset");
+    printf("PASS post-reset recovery: new request completed on same connection\n");
+
+    size_t pre_goaway = client_send(&pair, &client, "/fast/7777",
+                                     257 + (7777 % 127),
+                                     (uint8_t) 7777, false, false, false);
+    int goaway_result = quiche_h3_send_goaway(pair.server.h3, pair.server.quic,
+                                               0);
+    CHECK(goaway_result == 0, "could not send GOAWAY: %d", goaway_result);
+    server.goaway_sent = true;
+    drive_until_finished(&pair, &server, &client, pre_goaway, 1,
+                         "in-flight request after GOAWAY");
+    CHECK(client.requests[pre_goaway].finished,
+          "in-flight request did not complete after GOAWAY");
+    for (size_t round = 0; round < 1000; round++) {
+        drive_round(&pair, &server, &client);
+        if (client.saw_goaway) {
+            break;
+        }
+    }
+    CHECK(client.saw_goaway, "client did not receive GOAWAY event");
+    printf("PASS GOAWAY: in-flight request completed; client received GOAWAY\n");
+
+    quiche_h3_header goaway_reject_headers[] = {
+        {(const uint8_t *) ":method", 7, (const uint8_t *) "GET", 3},
+        {(const uint8_t *) ":scheme", 7, (const uint8_t *) "https", 5},
+        {(const uint8_t *) ":authority", 10,
+         (const uint8_t *) "ghostfile.test", 14},
+        {(const uint8_t *) ":path", 5,
+         (const uint8_t *) "/fast/8888", 10},
+    };
+    int64_t post_goaway_stream = quiche_h3_send_request(
+        pair.client.h3, pair.client.quic, goaway_reject_headers, 4, true);
+    CHECK(post_goaway_stream == QUICHE_H3_ERR_FRAME_UNEXPECTED,
+          "post-GOAWAY request should be rejected with FRAME_UNEXPECTED, got %"
+          PRId64, post_goaway_stream);
+    printf("PASS GOAWAY rejection: new request rejected after GOAWAY (err=%"
+           PRId64 ")\n", post_goaway_stream);
+
+    pair_free(&pair);
+
+    /* ---- Stream limit / backpressure ---- */
+    static test_pair limit_pair;
+    static server_state limit_server;
+    static client_state limit_client;
+    memset(&limit_pair, 0, sizeof(limit_pair));
+    memset(&limit_server, 0, sizeof(limit_server));
+    memset(&limit_client, 0, sizeof(limit_client));
+    limit_server.paused_stream = -1;
+    pair_create_internal(&limit_pair, argv[1], argv[2],
+                          STREAM_LIMIT_TEST_COUNT, 0, 41200);
+    CHECK(quiche_conn_peer_streams_left_bidi(limit_pair.client.quic)
+            == STREAM_LIMIT_TEST_COUNT,
+          "client should see %u peer bidi streams, got %" PRIu64,
+          STREAM_LIMIT_TEST_COUNT,
+          quiche_conn_peer_streams_left_bidi(limit_pair.client.quic));
+
+    for (unsigned i = 0; i < STREAM_LIMIT_TEST_COUNT; i++) {
+        char path[64];
+        snprintf(path, sizeof(path), "/fast/%u", 10000 + i);
+        client_send(&limit_pair, &limit_client, path,
+                    257 + ((10000 + i) % 127),
+                    (uint8_t) (10000 + i), false, false, false);
+        CHECK(quiche_conn_peer_streams_left_bidi(limit_pair.client.quic)
+                == STREAM_LIMIT_TEST_COUNT - (uint64_t)(i + 1),
+              "stream budget mismatch after %u opens: got %" PRIu64,
+              i + 1,
+              quiche_conn_peer_streams_left_bidi(limit_pair.client.quic));
+    }
+
+    quiche_h3_header over_limit_headers[] = {
+        {(const uint8_t *) ":method", 7, (const uint8_t *) "GET", 3},
+        {(const uint8_t *) ":scheme", 7, (const uint8_t *) "https", 5},
+        {(const uint8_t *) ":authority", 10,
+         (const uint8_t *) "ghostfile.test", 14},
+        {(const uint8_t *) ":path", 5, (const uint8_t *) "/fast/99999", 11},
+    };
+    int64_t over_limit_stream = quiche_h3_send_request(
+        limit_pair.client.h3, limit_pair.client.quic, over_limit_headers, 4,
+        true);
+    CHECK(over_limit_stream == QUICHE_H3_TRANSPORT_ERR_STREAM_LIMIT,
+          "over-limit request should return STREAM_LIMIT, got %" PRId64,
+          over_limit_stream);
+
+    drive_until_finished(&limit_pair, &limit_server, &limit_client, 0,
+                          STREAM_LIMIT_TEST_COUNT, "stream-limit requests");
+    printf("PASS stream limit: %d streams allowed, over-limit rejected (err=%"
+           PRId64 ")\n", STREAM_LIMIT_TEST_COUNT, over_limit_stream);
+    pair_free(&limit_pair);
+
+    /* ---- Connection close with peer error ---- */
+    static test_pair close_pair;
+    pair_create(&close_pair, argv[1], argv[2]);
+    const char *close_reason = "ga-shutdown";
+    int close_result = quiche_conn_close(
+        close_pair.server.quic, true, (uint64_t) CONNECTION_CLOSE_ERROR,
+        (const uint8_t *) close_reason, strlen(close_reason));
+    CHECK(close_result == 0, "quiche_conn_close failed: %d", close_result);
+    bool client_saw_close = false;
+    for (size_t round = 0; round < 5000; round++) {
+        pump_transport(&close_pair);
+        if (quiche_conn_is_closed(close_pair.client.quic) ||
+            quiche_conn_is_draining(close_pair.client.quic)) {
+            client_saw_close = true;
+            break;
+        }
+    }
+    CHECK(client_saw_close, "client did not detect connection close");
+    CHECK(quiche_conn_is_closed(close_pair.server.quic) ||
+          quiche_conn_is_draining(close_pair.server.quic),
+          "server should be closed or draining after close");
+
+    bool peer_is_app = false;
+    uint64_t peer_error_code = 0;
+    const uint8_t *peer_reason = NULL;
+    size_t peer_reason_len = 0;
+    CHECK(quiche_conn_peer_error(close_pair.client.quic, &peer_is_app,
+                                  &peer_error_code, &peer_reason,
+                                  &peer_reason_len),
+          "client should have peer error after close");
+    CHECK(peer_is_app, "peer error should be app-level");
+    CHECK(peer_error_code == CONNECTION_CLOSE_ERROR,
+          "peer error code mismatch: %" PRIu64, peer_error_code);
+    CHECK(peer_reason_len == strlen(close_reason),
+          "peer reason length mismatch: %zu", peer_reason_len);
+    CHECK(memcmp(peer_reason, close_reason, peer_reason_len) == 0,
+          "peer reason text mismatch");
+
+    bool local_is_app = false;
+    uint64_t local_error_code = 0;
+    const uint8_t *local_reason = NULL;
+    size_t local_reason_len = 0;
+    CHECK(quiche_conn_local_error(close_pair.server.quic, &local_is_app,
+                                   &local_error_code, &local_reason,
+                                   &local_reason_len),
+          "server should have local error after initiating close");
+    CHECK(local_is_app, "local error should be app-level");
+    CHECK(local_error_code == CONNECTION_CLOSE_ERROR,
+          "local error code mismatch: %" PRIu64, local_error_code);
+    CHECK(local_reason_len == strlen(close_reason),
+          "local reason length mismatch: %zu", local_reason_len);
+    CHECK(memcmp(local_reason, close_reason, local_reason_len) == 0,
+          "local reason text mismatch");
+    printf("PASS connection close: app=%d code=%" PRIu64 " reason=%.*s "
+           "(client draining=%d server draining=%d)\n",
+           peer_is_app, peer_error_code, (int) peer_reason_len,
+           (const char *) peer_reason,
+           quiche_conn_is_draining(close_pair.client.quic),
+           quiche_conn_is_draining(close_pair.server.quic));
+    pair_free(&close_pair);
+
+    /* ---- Oversized headers / max_field_section_size ---- */
+    static test_pair field_pair;
+    static server_state field_server;
+    static client_state field_client;
+    memset(&field_pair, 0, sizeof(field_pair));
+    memset(&field_server, 0, sizeof(field_server));
+    memset(&field_client, 0, sizeof(field_client));
+    field_server.paused_stream = -1;
+    pair_create_internal(&field_pair, argv[1], argv[2], MAX_REQUESTS,
+                          MAX_FIELD_SECTION_SIZE_LIMIT, 41300);
+    static uint8_t oversized_value[4 * 1024];
+    memset(oversized_value, 'x', sizeof(oversized_value));
+    quiche_h3_header oversized_headers[] = {
+        {(const uint8_t *) ":method", 7, (const uint8_t *) "GET", 3},
+        {(const uint8_t *) ":scheme", 7, (const uint8_t *) "https", 5},
+        {(const uint8_t *) ":authority", 10,
+         (const uint8_t *) "ghostfile.test", 14},
+        {(const uint8_t *) ":path", 5, (const uint8_t *) "/oversized", 10},
+        {(const uint8_t *) "x-oversized", 11,
+         oversized_value, sizeof(oversized_value)},
+    };
+    int64_t oversized_stream = quiche_h3_send_request(
+        field_pair.client.h3, field_pair.client.quic, oversized_headers, 5,
+        true);
+    CHECK(oversized_stream >= 0,
+          "oversized header request should be accepted for sending: %" PRId64,
+          oversized_stream);
+    // RFC 9114 §4.2.2: client-side header enforcement is not done at encode
+    // time, so quiche accepts the 4 KiB request. The receiver (server) is
+    // the one bound by SETTINGS_MAX_FIELD_SECTION_SIZE; on decode quiche
+    // raises HeaderListTooLarge → Error::ExcessiveLoad and tears down the
+    // h3 connection with code 0x107. The loop drives until both endpoints
+    // reach a terminal transport state (closed or draining).
+    bool client_terminal = false;
+    bool server_terminal = false;
+    for (size_t round = 0; round < 5000; round++) {
+        drive_round(&field_pair, &field_server, &field_client);
+        if (quiche_conn_is_closed(field_pair.client.quic) ||
+            quiche_conn_is_draining(field_pair.client.quic)) {
+            client_terminal = true;
+        }
+        if (quiche_conn_is_closed(field_pair.server.quic) ||
+            quiche_conn_is_draining(field_pair.server.quic)) {
+            server_terminal = true;
+        }
+        if (client_terminal && server_terminal) {
+            break;
+        }
+    }
+    CHECK(client_terminal,
+          "client should reach terminal state after the server rejected the "
+          "oversized header");
+    CHECK(server_terminal,
+          "server should reach terminal state after rejecting the oversized "
+          "header");
+    bool oversize_peer_is_app = false;
+    uint64_t peer_code = 0;
+    const uint8_t *peer_close_reason = NULL;
+    size_t peer_close_reason_len = 0;
+    CHECK(quiche_conn_peer_error(field_pair.client.quic, &oversize_peer_is_app,
+                                  &peer_code, &peer_close_reason,
+                                  &peer_close_reason_len),
+          "client should observe the server's CONNECTION_CLOSE error");
+    CHECK(oversize_peer_is_app,
+          "rejection close should be application-level (HTTP/3)");
+    CHECK(peer_code == H3_EXCESSIVE_LOAD_ERROR,
+          "peer error code should be HTTP_EXCESSIVE_LOAD (0x107), got 0x%"
+          PRIx64, peer_code);
+    printf("PASS oversized headers: 4 KiB field rejected by "
+           "max_field_section_size=%d via HTTP_EXCESSIVE_LOAD=0x%" PRIx64
+           " (app=%d); transport drained cleanly without framework crash\n",
+           MAX_FIELD_SECTION_SIZE_LIMIT, peer_code, oversize_peer_is_app);
+    pair_free(&field_pair);
+
+    return 0;
+}
diff --git a/macOS/GhostHTTP3/Tests/udp-chaos-proxy.c b/macOS/GhostHTTP3/Tests/udp-chaos-proxy.c
new file mode 100644
index 0000000..31ed48c
--- /dev/null
+++ b/macOS/GhostHTTP3/Tests/udp-chaos-proxy.c
@@ -0,0 +1,767 @@
+// Deterministic user-space UDP impairment proxy ("chaos proxy") for the
+// GhostHTTP3 HTTP/3 test phases. Requires no root privileges: it relays
+// loopback UDP datagrams between one client and one server through two
+// sockets and applies configurable impairments in each direction.
+//
+// Impairments per direction (client->server "c2s" and server->client "s2c"):
+//   - random loss            (--c2s-loss / --s2c-loss, percent)
+//   - random duplication     (--c2s-dup / --s2c-dup, percent)
+//   - fixed delay + uniform jitter (--c2s-delay / --c2s-jitter, milliseconds)
+//   - reordering             (--c2s-reorder percent, --c2s-reorder-ms range)
+//   - drop above MTU         (--mtu bytes, applies to both directions)
+//
+// All impairment decisions are drawn from a SplitMix64 PRNG seeded with
+// --seed; each direction consumes an independent stream keyed only by that
+// direction's packet sequence, so a fixed seed replays the same decision
+// pattern for the same offered traffic. Delayed packets sit in a bounded
+// per-direction queue (--queue); overflow drops are counted, never silent.
+//
+// The proxy prints one machine-parseable stats line per direction on exit
+// (SIGINT/SIGTERM or --max-duration) and optionally every --stats-interval
+// seconds. --probe-port provides a bind probe the driver uses for
+// collision-resistant port selection and server-readiness detection.
+
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+#define MAX_DATAGRAM 65536
+#define MAX_QUEUE_CAPACITY 4096
+#define DEFAULT_QUEUE_CAPACITY 256
+#define DEFAULT_MAX_DURATION_SEC 300
+
+#define CHECK(condition, ...) do { \
+    if (!(condition)) { \
+        fprintf(stderr, "FAIL: "); \
+        fprintf(stderr, __VA_ARGS__); \
+        fprintf(stderr, "\n"); \
+        exit(1); \
+    } \
+} while (0)
+
+typedef enum {
+    DIR_C2S = 0,
+    DIR_S2C = 1,
+} direction;
+
+typedef struct {
+    double loss_pct;
+    double dup_pct;
+    double reorder_pct;
+    uint32_t delay_ms;
+    uint32_t jitter_ms;
+    uint32_t reorder_ms;
+} impairment_config;
+
+typedef struct {
+    uint64_t rx;
+    uint64_t tx;
+    uint64_t drop_loss;
+    uint64_t drop_mtu;
+    uint64_t drop_full;
+    uint64_t drop_nopeer;
+    uint64_t send_error;
+    uint64_t duplicated;
+    uint64_t delayed;
+    uint64_t reordered;
+    uint64_t max_queue;
+} direction_stats;
+
+typedef struct {
+    uint64_t sequence;
+    uint64_t release_at_ms;
+    size_t length;
+    uint8_t *data;
+    bool duplicate;
+} queued_packet;
+
+typedef struct {
+    impairment_config config;
+    direction_stats stats;
+    uint64_t prng_state;
+    uint64_t next_sequence;
+    uint64_t max_released_sequence;
+    queued_packet *queue;
+    size_t queue_length;
+    size_t queue_capacity;
+} direction_state;
+
+typedef struct {
+    const char *listen_host;
+    uint16_t listen_port;
+    const char *target_host;
+    uint16_t target_port;
+    uint64_t seed;
+    size_t queue_capacity;
+    uint16_t mtu;
+    uint32_t max_duration_sec;
+    uint32_t stats_interval_sec;
+    bool verbose;
+    direction_state directions[2];
+} proxy;
+
+static volatile sig_atomic_t stop_requested = 0;
+
+static void handle_signal(int signal_number) {
+    (void) signal_number;
+    stop_requested = 1;
+}
+
+static uint64_t monotonic_ms(void) {
+    struct timespec now;
+    CHECK(clock_gettime(CLOCK_MONOTONIC, &now) == 0,
+          "clock_gettime failed: %s", strerror(errno));
+    return (uint64_t) now.tv_sec * 1000 + (uint64_t) now.tv_nsec / 1000000;
+}
+
+// SplitMix64: small, deterministic, and independent of libc rand().
+static uint64_t prng_next(direction_state *state) {
+    state->prng_state += 0x9e3779b97f4a7c15ULL;
+    uint64_t value = state->prng_state;
+    value = (value ^ (value >> 30)) * 0xbf58476d1ce4e5b9ULL;
+    value = (value ^ (value >> 27)) * 0x94d049bb133111ebULL;
+    return value ^ (value >> 31);
+}
+
+static double prng_double(direction_state *state) {
+    return (double) (prng_next(state) >> 11) * (1.0 / 9007199254740992.0);
+}
+
+static uint32_t prng_range(direction_state *state, uint32_t inclusive_max) {
+    return (uint32_t) (prng_double(state) * (double) (inclusive_max + 1));
+}
+
+static bool prng_roll(direction_state *state, double pct) {
+    return pct > 0.0 && prng_double(state) < pct / 100.0;
+}
+
+static const char *direction_name(direction dir) {
+    return dir == DIR_C2S ? "c2s" : "s2c";
+}
+
+static void print_stats_line(const proxy *config, direction dir) {
+    const direction_state *state = &config->directions[dir];
+    const direction_stats *stats = &state->stats;
+    printf("stats dir=%s rx=%" PRIu64 " tx=%" PRIu64
+           " drop_loss=%" PRIu64 " drop_mtu=%" PRIu64
+           " drop_full=%" PRIu64 " drop_nopeer=%" PRIu64
+           " send_error=%" PRIu64
+           " dup=%" PRIu64 " delayed=%" PRIu64
+           " reordered=%" PRIu64 " queued=%zu max_queue=%" PRIu64 "\n",
+           direction_name(dir), stats->rx, stats->tx,
+           stats->drop_loss, stats->drop_mtu,
+           stats->drop_full, stats->drop_nopeer,
+           stats->send_error,
+           stats->duplicated, stats->delayed,
+           stats->reordered, state->queue_length, stats->max_queue);
+    fflush(stdout);
+}
+
+static void print_stats(const proxy *config) {
+    print_stats_line(config, DIR_C2S);
+    print_stats_line(config, DIR_S2C);
+}
+
+static bool queue_enqueue(proxy *config, direction dir, uint64_t release_at_ms,
+                          const uint8_t *data, size_t length,
+                          bool duplicate) {
+    direction_state *state = &config->directions[dir];
+    if (state->queue_length == state->queue_capacity) {
+        state->stats.drop_full++;
+        if (config->verbose) {
+            fprintf(stderr, "%s #%" PRIu64 " %zuB drop(queue full)\n",
+                    direction_name(dir), state->next_sequence, length);
+        }
+        return false;
+    }
+
+    queued_packet *entry = &state->queue[state->queue_length++];
+    entry->sequence = state->next_sequence;
+    entry->release_at_ms = release_at_ms;
+    entry->length = length;
+    entry->duplicate = duplicate;
+    entry->data = malloc(length == 0 ? 1 : length);
+    CHECK(entry->data != NULL, "out of memory queueing %zu bytes", length);
+    memcpy(entry->data, data, length);
+
+    if (state->queue_length > state->stats.max_queue) {
+        state->stats.max_queue = state->queue_length;
+    }
+    return true;
+}
+
+// Releases every due packet in (release time, arrival sequence) order.
+static void queue_release_due(proxy *config, direction dir, int send_socket,
+                              const struct sockaddr_storage *destination,
+                              socklen_t destination_length) {
+    direction_state *state = &config->directions[dir];
+    uint64_t now = monotonic_ms();
+
+    while (state->queue_length > 0) {
+        size_t earliest = 0;
+        for (size_t index = 1; index < state->queue_length; index++) {
+            queued_packet *candidate = &state->queue[index];
+            queued_packet *current = &state->queue[earliest];
+            if (candidate->release_at_ms < current->release_at_ms ||
+                (candidate->release_at_ms == current->release_at_ms &&
+                 candidate->sequence < current->sequence)) {
+                earliest = index;
+            }
+        }
+
+        queued_packet *entry = &state->queue[earliest];
+        if (entry->release_at_ms > now) {
+            return;
+        }
+
+        if (destination == NULL) {
+            state->stats.drop_nopeer++;
+        } else {
+            ssize_t sent = sendto(send_socket, entry->data, entry->length, 0,
+                                  (const struct sockaddr *) destination,
+                                  destination_length);
+            if (sent < 0 || (size_t) sent != entry->length) {
+                state->stats.send_error++;
+                fprintf(stderr, "%s sendto failed: %s\n",
+                        direction_name(dir),
+                        sent < 0 ? strerror(errno) : "short datagram send");
+            } else {
+                state->stats.tx++;
+                // Duplicates ride the original's sequence number and are
+                // excluded from reorder accounting: a late copy is an
+                // artifact of duplication, not of packet reordering.
+                if (!entry->duplicate) {
+                    if (entry->sequence < state->max_released_sequence) {
+                        state->stats.reordered++;
+                        if (config->verbose) {
+                            fprintf(stderr, "%s #%" PRIu64
+                                    " released out of order\n",
+                                    direction_name(dir), entry->sequence);
+                        }
+                    } else {
+                        state->max_released_sequence = entry->sequence;
+                    }
+                }
+            }
+        }
+
+        free(entry->data);
+        if (earliest + 1 < state->queue_length) {
+            memmove(entry, entry + 1,
+                    (state->queue_length - earliest - 1) *
+                    sizeof(queued_packet));
+        }
+        state->queue_length--;
+        now = monotonic_ms();
+    }
+}
+
+static uint64_t queue_next_release_ms(const direction_state *state) {
+    if (state->queue_length == 0) {
+        return UINT64_MAX;
+    }
+    uint64_t earliest = UINT64_MAX;
+    for (size_t index = 0; index < state->queue_length; index++) {
+        if (state->queue[index].release_at_ms < earliest) {
+            earliest = state->queue[index].release_at_ms;
+        }
+    }
+    return earliest;
+}
+
+// Applies the configured impairment pipeline to one received datagram.
+static void impair_and_queue(proxy *config, direction dir,
+                             const uint8_t *data, size_t length) {
+    direction_state *state = &config->directions[dir];
+    const impairment_config *impairment = &state->config;
+    uint64_t sequence = state->next_sequence;
+    uint64_t now = monotonic_ms();
+
+    state->stats.rx++;
+
+    if (config->mtu > 0 && length > config->mtu) {
+        state->stats.drop_mtu++;
+        if (config->verbose) {
+            fprintf(stderr, "%s #%" PRIu64 " %zuB drop(mtu %u)\n",
+                    direction_name(dir), sequence, length,
+                    (unsigned) config->mtu);
+        }
+        state->next_sequence++;
+        return;
+    }
+
+    if (prng_roll(state, impairment->loss_pct)) {
+        state->stats.drop_loss++;
+        if (config->verbose) {
+            fprintf(stderr, "%s #%" PRIu64 " %zuB drop(loss)\n",
+                    direction_name(dir), sequence, length);
+        }
+        state->next_sequence++;
+        return;
+    }
+
+    uint64_t hold_ms = impairment->delay_ms;
+    if (impairment->jitter_ms > 0) {
+        hold_ms += prng_range(state, impairment->jitter_ms);
+    }
+    if (prng_roll(state, impairment->reorder_pct)) {
+        hold_ms += 1 + prng_range(state, impairment->reorder_ms);
+    }
+
+    uint64_t release_at_ms = now + hold_ms;
+    if (hold_ms > 0) {
+        state->stats.delayed++;
+    }
+    if (config->verbose) {
+        fprintf(stderr, "%s #%" PRIu64 " %zuB fwd hold=%" PRIu64 "ms\n",
+                direction_name(dir), sequence, length, hold_ms);
+    }
+    queue_enqueue(config, dir, release_at_ms, data, length, false);
+
+    if (prng_roll(state, impairment->dup_pct)) {
+        // The duplicate rides the same impairment decision 1 ms behind the
+        // original so arrival order between the two is deterministic. Count
+        // only successfully-queued dups; if the queue is full queue_enqueue
+        // has already accounted it as drop_full, so do not double-count.
+        if (queue_enqueue(config, dir, release_at_ms + 1, data, length, true)) {
+            state->stats.duplicated++;
+            if (config->verbose) {
+                fprintf(stderr, "%s #%" PRIu64 " %zuB dup\n",
+                        direction_name(dir), sequence, length);
+            }
+        } else if (config->verbose) {
+            fprintf(stderr, "%s #%" PRIu64 " %zuB dup dropped (queue full)\n",
+                    direction_name(dir), sequence, length);
+        }
+    }
+
+    state->next_sequence++;
+}
+
+static int make_udp_socket(void) {
+    int fd = socket(AF_INET, SOCK_DGRAM, 0);
+    CHECK(fd >= 0, "socket failed: %s", strerror(errno));
+
+    int flags = fcntl(fd, F_GETFL, 0);
+    CHECK(flags >= 0 && fcntl(fd, F_SETFL, flags | O_NONBLOCK) == 0,
+          "failed to make socket non-blocking: %s", strerror(errno));
+    return fd;
+}
+
+static void resolve_ipv4(const char *host, uint16_t port,
+                         struct sockaddr_storage *address,
+                         socklen_t *address_length) {
+    char service[8];
+    snprintf(service, sizeof(service), "%u", (unsigned) port);
+
+    const struct addrinfo hints = {
+        .ai_family = AF_INET,
+        .ai_socktype = SOCK_DGRAM,
+        .ai_protocol = IPPROTO_UDP,
+    };
+
+    struct addrinfo *result = NULL;
+    int rc = getaddrinfo(host, service, &hints, &result);
+    CHECK(rc == 0, "failed to resolve %s:%s: %s", host, service,
+          gai_strerror(rc));
+    CHECK(result->ai_addrlen <= sizeof(*address),
+          "resolved address too large");
+    memcpy(address, result->ai_addr, result->ai_addrlen);
+    *address_length = result->ai_addrlen;
+    freeaddrinfo(result);
+}
+
+static uint16_t bound_port(int socket_fd) {
+    struct sockaddr_storage address;
+    socklen_t address_length = sizeof(address);
+    CHECK(getsockname(socket_fd, (struct sockaddr *) &address,
+                      &address_length) == 0,
+          "getsockname failed: %s", strerror(errno));
+    return ntohs(((struct sockaddr_in *) &address)->sin_port);
+}
+
+static void drain_socket(proxy *config, direction dir, int socket_fd) {
+    uint8_t buffer[MAX_DATAGRAM];
+    for (;;) {
+        ssize_t length = recvfrom(socket_fd, buffer, sizeof(buffer), 0,
+                                  NULL, NULL);
+        if (length < 0) {
+            if (errno == EWOULDBLOCK || errno == EAGAIN) {
+                return;
+            }
+            if (errno == EINTR) {
+                return;
+            }
+            fprintf(stderr, "%s recvfrom failed: %s\n",
+                    direction_name(dir), strerror(errno));
+            return;
+        }
+        impair_and_queue(config, dir, buffer, (size_t) length);
+    }
+}
+
+static void run_proxy(proxy *config) {
+    struct sockaddr_storage listen_address;
+    socklen_t listen_address_length;
+    resolve_ipv4(config->listen_host, config->listen_port,
+                 &listen_address, &listen_address_length);
+
+    struct sockaddr_storage target_address;
+    socklen_t target_address_length;
+    resolve_ipv4(config->target_host, config->target_port,
+                 &target_address, &target_address_length);
+
+    // client_sock faces the HTTP/3 client; server_sock faces the quiche
+    // server. Replies are sent from client_sock so the client sees a
+    // consistent peer address (the proxy), hiding the real server.
+    int client_sock = make_udp_socket();
+    CHECK(bind(client_sock, (struct sockaddr *) &listen_address,
+               listen_address_length) == 0,
+          "failed to bind %s:%u: %s", config->listen_host,
+          (unsigned) config->listen_port, strerror(errno));
+
+    int server_sock = make_udp_socket();
+
+    struct sockaddr_storage client_address;
+    socklen_t client_address_length = sizeof(client_address);
+    bool client_known = false;
+
+    printf("config listen=%s:%u target=%s:%u seed=%" PRIu64
+           " queue=%zu mtu=%u"
+           " c2s(loss=%.2f%% dup=%.2f%% delay=%ums jitter=%ums"
+           " reorder=%.2f%% reorder_ms=%ums)"
+           " s2c(loss=%.2f%% dup=%.2f%% delay=%ums jitter=%ums"
+           " reorder=%.2f%% reorder_ms=%ums)\n",
+           config->listen_host, (unsigned) config->listen_port,
+           config->target_host, (unsigned) config->target_port, config->seed,
+           config->queue_capacity, (unsigned) config->mtu,
+           config->directions[DIR_C2S].config.loss_pct,
+           config->directions[DIR_C2S].config.dup_pct,
+           config->directions[DIR_C2S].config.delay_ms,
+           config->directions[DIR_C2S].config.jitter_ms,
+           config->directions[DIR_C2S].config.reorder_pct,
+           config->directions[DIR_C2S].config.reorder_ms,
+           config->directions[DIR_S2C].config.loss_pct,
+           config->directions[DIR_S2C].config.dup_pct,
+           config->directions[DIR_S2C].config.delay_ms,
+           config->directions[DIR_S2C].config.jitter_ms,
+           config->directions[DIR_S2C].config.reorder_pct,
+           config->directions[DIR_S2C].config.reorder_ms);
+    printf("listening on %s:%u\n", config->listen_host,
+           (unsigned) bound_port(client_sock));
+    fflush(stdout);
+
+    uint64_t start_ms = monotonic_ms();
+    uint64_t deadline_ms = config->max_duration_sec > 0
+        ? start_ms + (uint64_t) config->max_duration_sec * 1000
+        : UINT64_MAX;
+    uint64_t next_stats_ms = config->stats_interval_sec > 0
+        ? start_ms + (uint64_t) config->stats_interval_sec * 1000
+        : UINT64_MAX;
+
+    while (!stop_requested) {
+        uint64_t now = monotonic_ms();
+        if (now >= deadline_ms) {
+            break;
+        }
+
+        queue_release_due(config, DIR_C2S, server_sock,
+                          &target_address, target_address_length);
+        queue_release_due(config, DIR_S2C, client_sock,
+                          client_known ? &client_address : NULL,
+                          client_address_length);
+
+        if (now >= next_stats_ms) {
+            print_stats(config);
+            next_stats_ms = now + (uint64_t) config->stats_interval_sec * 1000;
+        }
+
+        uint64_t wake_ms = deadline_ms;
+        uint64_t release_ms;
+        release_ms = queue_next_release_ms(&config->directions[DIR_C2S]);
+        if (release_ms < wake_ms) {
+            wake_ms = release_ms;
+        }
+        release_ms = queue_next_release_ms(&config->directions[DIR_S2C]);
+        if (release_ms < wake_ms) {
+            wake_ms = release_ms;
+        }
+        if (next_stats_ms < wake_ms) {
+            wake_ms = next_stats_ms;
+        }
+
+        int timeout_ms = -1;
+        if (wake_ms != UINT64_MAX) {
+            now = monotonic_ms();
+            timeout_ms = wake_ms <= now ? 0
+                : (wake_ms - now > INT32_MAX ? INT32_MAX
+                                             : (int) (wake_ms - now));
+        }
+
+        struct pollfd fds[2] = {
+            { .fd = client_sock, .events = POLLIN },
+            { .fd = server_sock, .events = POLLIN },
+        };
+
+        int ready = poll(fds, 2, timeout_ms);
+        if (ready < 0) {
+            if (errno == EINTR) {
+                continue;
+            }
+            fprintf(stderr, "poll failed: %s\n", strerror(errno));
+            break;
+        }
+        if (ready == 0) {
+            continue;
+        }
+
+        if (fds[0].revents & POLLIN) {
+            // Track the most recent client address so replies find the
+            // current client even across successive client processes.
+            uint8_t peek[MAX_DATAGRAM];
+            struct sockaddr_storage source;
+            socklen_t source_length = sizeof(source);
+            ssize_t length = recvfrom(client_sock, peek, sizeof(peek),
+                                      MSG_PEEK,
+                                      (struct sockaddr *) &source,
+                                      &source_length);
+            if (length >= 0) {
+                memcpy(&client_address, &source, source_length);
+                client_address_length = source_length;
+                client_known = true;
+            }
+            drain_socket(config, DIR_C2S, client_sock);
+        }
+        if (fds[1].revents & POLLIN) {
+            drain_socket(config, DIR_S2C, server_sock);
+        }
+    }
+
+    close(client_sock);
+    close(server_sock);
+
+    // Print before freeing so `queued` truthfully reports any datagrams that
+    // were still pending when the proxy stopped. The driver asserts zero for
+    // gated scenarios instead of mistaking cleanup for successful delivery.
+    print_stats(config);
+
+    for (direction dir = DIR_C2S; dir <= DIR_S2C; dir++) {
+        direction_state *state = &config->directions[dir];
+        for (size_t index = 0; index < state->queue_length; index++) {
+            free(state->queue[index].data);
+        }
+        state->queue_length = 0;
+    }
+
+}
+
+static double parse_percent(const char *option, const char *value) {
+    char *end = NULL;
+    double parsed = strtod(value, &end);
+    CHECK(end != value && *end == '\0' && parsed >= 0.0 && parsed <= 100.0,
+          "%s expects a percentage in [0, 100], got '%s'", option, value);
+    return parsed;
+}
+
+static uint64_t parse_u64(const char *option, const char *value,
+                          uint64_t maximum) {
+    char *end = NULL;
+    errno = 0;
+    uint64_t parsed = strtoull(value, &end, 10);
+    CHECK(errno == 0 && end != value && *end == '\0' && parsed <= maximum,
+          "%s expects an integer in [0, %" PRIu64 "], got '%s'",
+          option, maximum, value);
+    return parsed;
+}
+
+static void usage(const char *program) {
+    fprintf(stderr,
+        "usage: %s --listen-port PORT --target-port PORT [options]\n"
+        "       %s --probe-port PORT\n"
+        "\n"
+        "Relays UDP between a client and a target server, applying\n"
+        "deterministic seeded impairments in both directions.\n"
+        "\n"
+        "required:\n"
+        "  --listen-port PORT    UDP port the client connects to\n"
+        "  --target-port PORT    UDP port of the real server\n"
+        "\n"
+        "addressing:\n"
+        "  --listen-host ADDR    listen address (default 127.0.0.1)\n"
+        "  --target-host ADDR    server address (default 127.0.0.1)\n"
+        "\n"
+        "determinism and bounds:\n"
+        "  --seed N              impairment PRNG seed (default 1)\n"
+        "  --queue N             per-direction delayed-packet queue capacity\n"
+        "                        (default %d, max %d; overflow drops counted)\n"
+        "  --max-duration SEC    graceful self-termination deadline\n"
+        "                        (default %d, 0 disables)\n"
+        "\n"
+        "impairments (DIR is c2s or s2c):\n"
+        "  --DIR-loss PCT        random packet loss, 0-100\n"
+        "  --DIR-dup PCT         random duplication, 0-100\n"
+        "  --DIR-delay MS        fixed delay added to every packet\n"
+        "  --DIR-jitter MS       uniform extra delay in [0, MS]\n"
+        "  --DIR-reorder PCT     probability of holding a packet back\n"
+        "  --DIR-reorder-ms MS   reorder hold range in [1, MS] (default 30)\n"
+        "  --mtu BYTES           drop datagrams larger than this (0 disables)\n"
+        "\n"
+        "diagnostics:\n"
+        "  --stats-interval SEC  also print stats periodically (default off)\n"
+        "  -v, --verbose         log every packet decision to stderr\n"
+        "  --probe-port PORT     exit 0 if ADDR:PORT is bindable, 1 if busy\n"
+        "  --probe-host ADDR     probe address (default 127.0.0.1)\n",
+        program, program, DEFAULT_QUEUE_CAPACITY, MAX_QUEUE_CAPACITY,
+        DEFAULT_MAX_DURATION_SEC);
+}
+
+int main(int argc, char *argv[]) {
+    static const struct option options[] = {
+        { "listen-host",     required_argument, NULL, 'H' },
+        { "listen-port",     required_argument, NULL, 'p' },
+        { "target-host",     required_argument, NULL, 'T' },
+        { "target-port",     required_argument, NULL, 't' },
+        { "seed",            required_argument, NULL, 's' },
+        { "queue",           required_argument, NULL, 'q' },
+        { "mtu",             required_argument, NULL, 'm' },
+        { "max-duration",    required_argument, NULL, 'd' },
+        { "stats-interval",  required_argument, NULL, 'i' },
+        { "verbose",         no_argument,       NULL, 'v' },
+        { "probe-port",      required_argument, NULL, 'P' },
+        { "probe-host",      required_argument, NULL, 'B' },
+        { "help",            no_argument,       NULL, 'h' },
+        { "c2s-loss",        required_argument, NULL, 1000 },
+        { "c2s-dup",         required_argument, NULL, 1001 },
+        { "c2s-delay",       required_argument, NULL, 1002 },
+        { "c2s-jitter",      required_argument, NULL, 1003 },
+        { "c2s-reorder",     required_argument, NULL, 1004 },
+        { "c2s-reorder-ms",  required_argument, NULL, 1005 },
+        { "s2c-loss",        required_argument, NULL, 1006 },
+        { "s2c-dup",         required_argument, NULL, 1007 },
+        { "s2c-delay",       required_argument, NULL, 1008 },
+        { "s2c-jitter",      required_argument, NULL, 1009 },
+        { "s2c-reorder",     required_argument, NULL, 1010 },
+        { "s2c-reorder-ms",  required_argument, NULL, 1011 },
+        { NULL, 0, NULL, 0 },
+    };
+
+    proxy config = {
+        .listen_host = "127.0.0.1",
+        .listen_port = 0,
+        .target_host = "127.0.0.1",
+        .target_port = 0,
+        .seed = 1,
+        .queue_capacity = DEFAULT_QUEUE_CAPACITY,
+        .mtu = 0,
+        .max_duration_sec = DEFAULT_MAX_DURATION_SEC,
+        .stats_interval_sec = 0,
+        .verbose = false,
+    };
+
+    const char *probe_host = "127.0.0.1";
+    uint64_t probe_port = 0;
+
+    int option;
+    while ((option = getopt_long(argc, argv, "hvp:H:t:T:s:q:m:d:i:P:B:",
+                                 options, NULL)) != -1) {
+        impairment_config *c2s = &config.directions[DIR_C2S].config;
+        impairment_config *s2c = &config.directions[DIR_S2C].config;
+        switch (option) {
+            case 'H': config.listen_host = optarg; break;
+            case 'p': config.listen_port = (uint16_t) parse_u64("--listen-port", optarg, 65535); break;
+            case 'T': config.target_host = optarg; break;
+            case 't': config.target_port = (uint16_t) parse_u64("--target-port", optarg, 65535); break;
+            case 's': config.seed = parse_u64("--seed", optarg, UINT64_MAX); break;
+            case 'q': config.queue_capacity = (size_t) parse_u64("--queue", optarg, MAX_QUEUE_CAPACITY); break;
+            case 'm': config.mtu = (uint16_t) parse_u64("--mtu", optarg, 65535); break;
+            case 'd': config.max_duration_sec = (uint32_t) parse_u64("--max-duration", optarg, 86400); break;
+            case 'i': config.stats_interval_sec = (uint32_t) parse_u64("--stats-interval", optarg, 86400); break;
+            case 'v': config.verbose = true; break;
+            case 'P': probe_port = parse_u64("--probe-port", optarg, 65535); break;
+            case 'B': probe_host = optarg; break;
+            case 'h': usage(argv[0]); return 0;
+            case 1000: c2s->loss_pct = parse_percent("--c2s-loss", optarg); break;
+            case 1001: c2s->dup_pct = parse_percent("--c2s-dup", optarg); break;
+            case 1002: c2s->delay_ms = (uint32_t) parse_u64("--c2s-delay", optarg, 60000); break;
+            case 1003: c2s->jitter_ms = (uint32_t) parse_u64("--c2s-jitter", optarg, 60000); break;
+            case 1004: c2s->reorder_pct = parse_percent("--c2s-reorder", optarg); break;
+            case 1005: c2s->reorder_ms = (uint32_t) parse_u64("--c2s-reorder-ms", optarg, 60000); break;
+            case 1006: s2c->loss_pct = parse_percent("--s2c-loss", optarg); break;
+            case 1007: s2c->dup_pct = parse_percent("--s2c-dup", optarg); break;
+            case 1008: s2c->delay_ms = (uint32_t) parse_u64("--s2c-delay", optarg, 60000); break;
+            case 1009: s2c->jitter_ms = (uint32_t) parse_u64("--s2c-jitter", optarg, 60000); break;
+            case 1010: s2c->reorder_pct = parse_percent("--s2c-reorder", optarg); break;
+            case 1011: s2c->reorder_ms = (uint32_t) parse_u64("--s2c-reorder-ms", optarg, 60000); break;
+            default: usage(argv[0]); return 2;
+        }
+    }
+
+    if (probe_port > 0) {
+        struct sockaddr_storage address;
+        socklen_t address_length;
+        resolve_ipv4(probe_host, (uint16_t) probe_port, &address,
+                     &address_length);
+        int fd = socket(AF_INET, SOCK_DGRAM, 0);
+        CHECK(fd >= 0, "socket failed: %s", strerror(errno));
+        if (bind(fd, (struct sockaddr *) &address, address_length) == 0) {
+            close(fd);
+            printf("%s:%" PRIu64 " free\n", probe_host, probe_port);
+            return 0;
+        }
+        int bind_errno = errno;
+        close(fd);
+        if (bind_errno == EADDRINUSE) {
+            printf("%s:%" PRIu64 " busy\n", probe_host, probe_port);
+            return 1;
+        }
+        fprintf(stderr, "probe bind failed: %s\n", strerror(bind_errno));
+        return 2;
+    }
+
+    if (config.listen_port == 0 || config.target_port == 0) {
+        usage(argv[0]);
+        return 2;
+    }
+    CHECK(config.queue_capacity >= 1, "--queue must be at least 1");
+
+    // Distinct PRNG streams per direction so impairment decisions depend
+    // only on the seed and that direction's packet sequence, not on how
+    // the two directions happen to interleave in real time.
+    config.directions[DIR_C2S].prng_state = config.seed;
+    config.directions[DIR_S2C].prng_state =
+        config.seed ^ 0x9e3779b97f4a7c15ULL;
+
+    for (direction dir = DIR_C2S; dir <= DIR_S2C; dir++) {
+        config.directions[dir].queue_capacity = config.queue_capacity;
+        config.directions[dir].queue =
+            calloc(config.queue_capacity, sizeof(queued_packet));
+        CHECK(config.directions[dir].queue != NULL,
+              "out of memory allocating packet queue");
+    }
+
+    struct sigaction action = { .sa_handler = handle_signal };
+    sigemptyset(&action.sa_mask);
+    sigaction(SIGINT, &action, NULL);
+    sigaction(SIGTERM, &action, NULL);
+    sigaction(SIGHUP, &action, NULL);
+    signal(SIGPIPE, SIG_IGN);
+
+    run_proxy(&config);
+
+    free(config.directions[DIR_C2S].queue);
+    free(config.directions[DIR_S2C].queue);
+    return 0;
+}
diff --git a/macOS/GhostHTTP3/Tests/udp-datagram.c b/macOS/GhostHTTP3/Tests/udp-datagram.c
new file mode 100644
index 0000000..7911b96
--- /dev/null
+++ b/macOS/GhostHTTP3/Tests/udp-datagram.c
@@ -0,0 +1,87 @@
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+#include 
+
+static int parse_u16(const char *text, uint16_t *value) {
+    char *end = NULL;
+    errno = 0;
+    unsigned long parsed = strtoul(text, &end, 10);
+    if (errno != 0 || end == text || *end != '\0' || parsed > UINT16_MAX) {
+        return -1;
+    }
+    *value = (uint16_t) parsed;
+    return 0;
+}
+
+static int parse_size(const char *text, size_t *value) {
+    char *end = NULL;
+    errno = 0;
+    unsigned long parsed = strtoul(text, &end, 10);
+    if (errno != 0 || end == text || *end != '\0' || parsed == 0 ||
+        parsed > 65507UL) {
+        return -1;
+    }
+    *value = (size_t) parsed;
+    return 0;
+}
+
+int main(int argc, char **argv) {
+    if (argc != 4) {
+        fprintf(stderr, "usage: %s IPV4 PORT BYTES\n", argv[0]);
+        return 2;
+    }
+
+    uint16_t port = 0;
+    size_t payload_size = 0;
+    if (parse_u16(argv[2], &port) != 0 || port == 0 ||
+        parse_size(argv[3], &payload_size) != 0) {
+        fprintf(stderr, "invalid port or datagram size\n");
+        return 2;
+    }
+
+    struct sockaddr_in destination = {
+        .sin_family = AF_INET,
+        .sin_port = htons(port),
+    };
+    if (inet_pton(AF_INET, argv[1], &destination.sin_addr) != 1) {
+        fprintf(stderr, "invalid IPv4 address: %s\n", argv[1]);
+        return 2;
+    }
+
+    int fd = socket(AF_INET, SOCK_DGRAM, 0);
+    if (fd < 0) {
+        perror("socket");
+        return 1;
+    }
+
+    uint8_t *payload = calloc(payload_size, 1);
+    if (payload == NULL) {
+        perror("calloc");
+        close(fd);
+        return 1;
+    }
+
+    ssize_t sent = sendto(fd, payload, payload_size, 0,
+        (const struct sockaddr *) &destination, sizeof(destination));
+    if (sent < 0 || (size_t) sent != payload_size) {
+        if (sent < 0) {
+            perror("sendto");
+        } else {
+            fprintf(stderr, "short UDP send: %zd of %zu bytes\n", sent,
+                payload_size);
+        }
+        free(payload);
+        close(fd);
+        return 1;
+    }
+
+    free(payload);
+    close(fd);
+    return 0;
+}
diff --git a/macOS/GhostHTTP3/include/GhostHTTP3/GhostHTTP3.h b/macOS/GhostHTTP3/include/GhostHTTP3/GhostHTTP3.h
new file mode 100644
index 0000000..c168f06
--- /dev/null
+++ b/macOS/GhostHTTP3/include/GhostHTTP3/GhostHTTP3.h
@@ -0,0 +1,35 @@
+#ifndef GHOST_HTTP3_H
+#define GHOST_HTTP3_H
+
+#include 
+#include 
+#include 
+
+#include "quiche.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// The stable GhostHTTP3 wrapper API version.
+#define GHOST_HTTP3_API_VERSION 1
+
+/// Returns the GhostHTTP3 wrapper API version.
+uint32_t ghost_http3_api_version(void);
+
+/// Returns the version string reported by the linked quiche backend.
+const char *ghost_http3_backend_version(void);
+
+/// Returns quiche's length-prefixed HTTP/3 ALPN list (currently `h3`).
+/// The returned bytes have static storage duration.
+const uint8_t *ghost_http3_application_protocol(size_t *length);
+
+/// Performs a lightweight runtime check that both QUIC and HTTP/3
+/// configuration objects can be created by the linked backend.
+bool ghost_http3_backend_is_ready(void);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // GHOST_HTTP3_H
diff --git a/macOS/GhostHTTP3/include/module.modulemap b/macOS/GhostHTTP3/include/module.modulemap
new file mode 100644
index 0000000..3352c12
--- /dev/null
+++ b/macOS/GhostHTTP3/include/module.modulemap
@@ -0,0 +1,5 @@
+framework module GhostHTTP3 {
+    umbrella header "GhostHTTP3.h"
+    export *
+    module * { export * }
+}
diff --git a/macOS/GhostHTTP3/quiche-0.29.3.Cargo.lock b/macOS/GhostHTTP3/quiche-0.29.3.Cargo.lock
new file mode 100644
index 0000000..f28721a
--- /dev/null
+++ b/macOS/GhostHTTP3/quiche-0.29.3.Cargo.lock
@@ -0,0 +1,4497 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "addr2line"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b5d307320b3181d6d7954e663bd7c774a838b8220fe0593c86d9fb09f498b4b"
+dependencies = [
+ "gimli",
+]
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "allocator-api2"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
+
+[[package]]
+name = "arc-swap"
+version = "1.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c049c0be4daef0b145cb3555416b3b8ef5b7888a38aea1a3a155801fe7b0810b"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "assert_matches"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b34d609dfbaf33d6889b2b7106d3ca345eacad44200913df5ba02bfd31d2ba9"
+
+[[package]]
+name = "async-trait"
+version = "0.1.91"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "atty"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9b39be18770d11421cdb1b9947a45dd3f37e93092cbf377614828a319d5fee8"
+dependencies = [
+ "hermit-abi 0.1.19",
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "backtrace"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb531853791a215d7c62a30daf0dde835f381ab5de4589cfe7c649d2cbe92bd6"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-link",
+]
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags 2.13.1",
+ "cexpr",
+ "clang-sys",
+ "itertools 0.13.0",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex 1.3.0",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "boring"
+version = "4.22.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0e3bc837369e9e662d3845c374ac3771b054d4bc2dee5457591198d16d684c"
+dependencies = [
+ "bitflags 2.13.1",
+ "boring-sys",
+ "foreign-types",
+ "libc",
+ "openssl-macros",
+]
+
+[[package]]
+name = "boring-sys"
+version = "4.22.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15aad385759d3da2737772aefb391332227bef7cb71fb85c106cadd9d1e63a98"
+dependencies = [
+ "bindgen",
+ "cmake",
+ "fs_extra",
+ "fslock",
+]
+
+[[package]]
+name = "bs58"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf88ba1141d185c399bee5288d850d63b8369520c1eafc32a0430b5b6c287bf4"
+dependencies = [
+ "tinyvec",
+]
+
+[[package]]
+name = "buffer-pool"
+version = "0.2.1"
+dependencies = [
+ "crossbeam",
+ "foundations",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytecount"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
+[[package]]
+name = "byteorder"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex 2.0.1",
+]
+
+[[package]]
+name = "cdylib-link-lines"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d98eabef08bbdf5afd0b9c0cabb1ac335f7c70447ef095eed85dffd9628b20bc"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cf-rustracing"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e708e4e7bd0aa8f03edc6befeb0b40587c202c503f00a7cc20e612d14af55d3"
+dependencies = [
+ "backtrace",
+ "rand 0.10.2",
+ "tokio",
+ "trackable",
+]
+
+[[package]]
+name = "cf-rustracing-jaeger"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16c0e4d8cce27f6a6eaff58d2b66f063a18b8ed0d6ef0947ae7a263afa3b7c08"
+dependencies = [
+ "cf-rustracing",
+ "hostname",
+ "local-ip-address",
+ "percent-encoding",
+ "rand 0.10.2",
+ "thrift_codec",
+ "tokio",
+ "trackable",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
+
+[[package]]
+name = "chacha20"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "js-sys",
+ "num-traits",
+ "serde",
+ "wasm-bindgen",
+ "windows-link",
+]
+
+[[package]]
+name = "cidr"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6bdf600c45bd958cf2945c445264471cca8b6c8e67bc87b71affd6d7e5682621"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "clang-sys"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "157a8ba7b480713b56f4c09fd13fc3e0a22a5dfab8097ba61cbc5feef950788a"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "clap"
+version = "3.2.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ea181bf566f71cb9a5d17a59e1871af638180a18fb0035c92ae62b705207123"
+dependencies = [
+ "atty",
+ "bitflags 1.3.2",
+ "clap_lex 0.2.4",
+ "indexmap 1.9.3",
+ "strsim 0.10.0",
+ "termcolor",
+ "textwrap",
+]
+
+[[package]]
+name = "clap"
+version = "4.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "301b56658598e48f3648647ac6fc887be7e7108eddfa4e9b63fcf3ec58c0cadf"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94a65403d1a1bd28f7dc68eb8506e8874808ee5eecb59298de588e2e1407a078"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex 1.1.0",
+ "strsim 0.11.1",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "clap_lex"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2850f2f5a82cbf437dd5af4d49848fbdfc27c157c3d010345776f952765261c5"
+dependencies = [
+ "os_str_bytes",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "cmake"
+version = "0.1.58"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0f78a02292a74a88ac736019ab962ece0bc380e3f977bf72e376c5d78ff0678"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "const-hex"
+version = "1.19.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33e2a781ebdf4467d1428dc4593067825fb646f6871475098d8577421af73558"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "proptest",
+ "serde_core",
+]
+
+[[package]]
+name = "convert_case"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "core-graphics"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c07782be35f9e1140080c6b96f0d44b739e2278479f64e02fdab4e32dfd8b081"
+dependencies = [
+ "bitflags 1.3.2",
+ "core-foundation",
+ "core-graphics-types",
+ "foreign-types",
+ "libc",
+]
+
+[[package]]
+name = "core-graphics-types"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45390e6114f68f718cc7a830514a96f903cccd70d02a8f6d9f643ac4ba45afaf"
+dependencies = [
+ "bitflags 1.3.2",
+ "core-foundation",
+ "libc",
+]
+
+[[package]]
+name = "core-text"
+version = "20.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9d2790b5c08465d49f8dc05c8bcae9fea467855947db39b0f8145c091aaced5"
+dependencies = [
+ "core-foundation",
+ "core-graphics",
+ "foreign-types",
+ "libc",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1137cd7e7fc0fb5d3c5a8678be38ec56e819125d8d7907411fe24ccb943faca8"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-queue",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-channel"
+version = "0.5.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d85363c37faeca707aef026efa9f3b34d077bce547e48f770770625c6013679e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-queue"
+version = "0.3.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "803d13fb3b09d88be9f4dbc29062c66b19bf7170867ceb746d2a8689bf6c7a26"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags 2.13.1",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "mio",
+ "parking_lot",
+ "rustix 1.1.4",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "darling"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc7f46116c46ff9ab3eb1597a45688b6715c6e628b5c133e288e709a29bcb4ee"
+dependencies = [
+ "darling_core 0.20.11",
+ "darling_macro 0.20.11",
+]
+
+[[package]]
+name = "darling"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
+dependencies = [
+ "darling_core 0.23.0",
+ "darling_macro 0.23.0",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d00b9596d185e565c2207a0b01f8bd1a135483d02d9b7b0a54b11da8d53412e"
+dependencies = [
+ "fnv",
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim 0.11.1",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0"
+dependencies = [
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim 0.11.1",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.20.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead"
+dependencies = [
+ "darling_core 0.20.11",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
+dependencies = [
+ "darling_core 0.23.0",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "dashmap"
+version = "6.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6361d5c062261c78a176addb82d4c821ae42bed6089de0e12603cd25de2059c"
+dependencies = [
+ "cfg-if",
+ "crossbeam-utils",
+ "hashbrown 0.14.5",
+ "lock_api",
+ "once_cell",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "data-encoding"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"
+
+[[package]]
+name = "datagram-socket"
+version = "0.8.0"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "libc",
+ "smallvec",
+ "tokio",
+]
+
+[[package]]
+name = "debug_panic"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9377eb110cece2e9431deb8d7d2ec8c116510b896741f9f2bf02b352147aa2a6"
+
+[[package]]
+name = "defmt"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2953bfe4f93bbd20cc71198842756f77d161884c99ebbabc41d80231ded88d1"
+dependencies = [
+ "bitflags 1.3.2",
+ "defmt-macros",
+]
+
+[[package]]
+name = "defmt-macros"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bad9c72e7ca2137e0dc3813245a0d282fd6daad32fd800af018306a9169b5fe8"
+dependencies = [
+ "defmt-parser",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "defmt-parser"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10d60334b3b2e7c9d91ef8150abfb6fa4c1c39ebbcf4a81c2e346aad939fee3e"
+dependencies = [
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "deranged"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "derive_builder"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "507dfb09ea8b7fa618fcf76e953f4f5e192547945816d5358edffe39f6f94947"
+dependencies = [
+ "derive_builder_macro",
+]
+
+[[package]]
+name = "derive_builder_core"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d5bcf7b024d6835cfb3d473887cd966994907effbe9227e8c8219824d06c4e8"
+dependencies = [
+ "darling 0.20.11",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "derive_builder_macro"
+version = "0.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab63b0e2bf4d5928aff72e83a7dace85d7bba5fe12dcc3c5a572d78caffd3f3c"
+dependencies = [
+ "derive_builder_core",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "derive_more"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
+dependencies = [
+ "convert_case",
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "diff"
+version = "0.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56254986775e3233ffa9c4d7d3faaf6d36a2c09d30b20687e9f88bc8bafc16c8"
+
+[[package]]
+name = "dirs"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3e8aa94d75141228480295a7d0e7feb620b1a5ad9f12bc40be62411e38cce4e"
+dependencies = [
+ "dirs-sys",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
+dependencies = [
+ "libc",
+ "option-ext",
+ "redox_users",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "dlib"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab8ecd87370524b461f8557c119c405552c396ed91fc0a8eec68679eab26f94a"
+dependencies = [
+ "libloading",
+]
+
+[[package]]
+name = "docopt"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f3f119846c823f9eafcf953a8f6ffb6ed69bf6240883261a7f13b634579a51f"
+dependencies = [
+ "lazy_static",
+ "regex",
+ "serde",
+ "strsim 0.10.0",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "dtoa"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590"
+
+[[package]]
+name = "dwrote"
+version = "0.11.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1b35532432acc8b19ceed096e35dfa088d3ea037fe4f3c085f1f97f33b4d02"
+dependencies = [
+ "lazy_static",
+ "libc",
+ "winapi",
+ "wio",
+]
+
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
+[[package]]
+name = "either"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d"
+
+[[package]]
+name = "enum_dispatch"
+version = "0.3.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa18ce2bc66555b3218614519ac839ddb759a7d6720732f979ef8d13be147ecd"
+dependencies = [
+ "once_cell",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "env_filter"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "900d271a03799a1ee8d1ca9b19893b48ca674a9284fefcfb85f05e74ed314217"
+dependencies = [
+ "log",
+ "regex",
+]
+
+[[package]]
+name = "env_logger"
+version = "0.11.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de671bd27a75a797dc9ae289ba1e77276e75e2026408aab65185384e2d5cd3f6"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "env_filter",
+ "jiff",
+ "log",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "erased-serde"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c138974f9d5e7fe373eb04df7cae98833802ae4b11c24ac7039a21d5af4b26c"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "erased-serde"
+version = "0.4.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2add8a07dd6a8d93ff627029c51de145e12686fbc36ecb298ac22e74cf02dec"
+dependencies = [
+ "serde",
+ "serde_core",
+ "typeid",
+]
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "float-ord"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ce81f49ae8a0482e4c55ea62ebbd7e5a686af544c00b9d090bba3ff9be97b3d"
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "foldhash"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
+[[package]]
+name = "font-kit"
+version = "0.14.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c7e611d49285d4c4b2e1727b72cf05353558885cc5252f93707b845dfcaf3d3"
+dependencies = [
+ "bitflags 2.13.1",
+ "byteorder",
+ "core-foundation",
+ "core-graphics",
+ "core-text",
+ "dirs",
+ "dwrote",
+ "float-ord",
+ "freetype-sys",
+ "lazy_static",
+ "libc",
+ "log",
+ "pathfinder_geometry",
+ "pathfinder_simd",
+ "walkdir",
+ "winapi",
+ "yeslogic-fontconfig-sys",
+]
+
+[[package]]
+name = "foreign-types"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d737d9aa519fb7b749cbc3b962edcf310a8dd1f4b67c91c4f83975dbdd17d965"
+dependencies = [
+ "foreign-types-macros",
+ "foreign-types-shared",
+]
+
+[[package]]
+name = "foreign-types-macros"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea5190182e6915eb873ddbc16e23b711b6eb1f9c00a0d0a3a91b5f6228475225"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "foreign-types-shared"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "foundations"
+version = "5.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "490e0a8bc50e56156b4a73c6f634c8ff6d0e5b9caf35711d41e59272d636e018"
+dependencies = [
+ "anyhow",
+ "cf-rustracing",
+ "cf-rustracing-jaeger",
+ "crossbeam-utils",
+ "erased-serde 0.4.10",
+ "foundations-macros",
+ "futures-util",
+ "governor",
+ "http",
+ "indexmap 2.14.0",
+ "libc",
+ "opentelemetry-proto",
+ "parking_lot",
+ "pin-project-lite",
+ "prometheus",
+ "prometheus-client",
+ "prometools",
+ "rand 0.10.2",
+ "serde",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_with",
+ "serde_yaml",
+ "slab",
+ "slog",
+ "slog-async",
+ "slog-json",
+ "slog-term",
+ "thread_local",
+ "tokio",
+ "yaml-merge-keys",
+ "zeroize",
+]
+
+[[package]]
+name = "foundations-macros"
+version = "5.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36818af4b1a941c0f83adbf04b33e075a12ebac872fdda62f809ab74a9e7b189"
+dependencies = [
+ "darling 0.23.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "freetype-sys"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e7edc5b9669349acfda99533e9e0bcf26a51862ab43b08ee7745c55d28eb134"
+dependencies = [
+ "cc",
+ "libc",
+ "pkg-config",
+]
+
+[[package]]
+name = "fs_extra"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+
+[[package]]
+name = "fslock"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04412b8935272e3a9bae6f48c7bfff74c2911f60525404edfdd28e49884c3bfb"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "futures"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307"
+
+[[package]]
+name = "futures-task"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
+
+[[package]]
+name = "futures-timer"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af43fadb8a98512d547e37b4e92e0ced13e205c061b87b4623eff01d918d6968"
+
+[[package]]
+name = "futures-util"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "fuzzy-matcher"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54614a3312934d066701a80f20f15fa3b56d67ac7722b39eea5b4c9dd1d66c94"
+dependencies = [
+ "thread_local",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi 5.3.0",
+ "wasip2",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi 6.0.0",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "getset"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cf442baaabe4213ce7d1239afc26c039180b6456da2cededa316ae2c8a77a77"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "gif"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80792593675e051cf94a4b111980da2ba60d4a83e43e0048c5693baab3977045"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
+[[package]]
+name = "gimli"
+version = "0.32.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e629b9b98ef3dd8afe6ca2bd0f89306cec16d43d907889945bc5d6687f2f13c7"
+
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
+[[package]]
+name = "governor"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9efcab3c1958580ff1f25a2a41be1668f7603d849bb63af523b208a3cc1223b8"
+dependencies = [
+ "cfg-if",
+ "dashmap",
+ "futures-sink",
+ "futures-timer",
+ "futures-util",
+ "getrandom 0.3.4",
+ "hashbrown 0.16.1",
+ "nonzero_ext",
+ "parking_lot",
+ "portable-atomic",
+ "quanta",
+ "rand 0.9.5",
+ "smallvec",
+ "spinning_top",
+ "web-time",
+]
+
+[[package]]
+name = "h2"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap 2.14.0",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "h3i"
+version = "0.6.0"
+dependencies = [
+ "clap 3.2.25",
+ "env_logger",
+ "inquire",
+ "log",
+ "mio",
+ "multimap",
+ "octets",
+ "qlog",
+ "quiche",
+ "ring",
+ "serde",
+ "serde_json",
+ "serde_with",
+ "tokio",
+ "tokio-quiche",
+ "url",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
+
+[[package]]
+name = "hashbrown"
+version = "0.14.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+dependencies = [
+ "allocator-api2",
+ "equivalent",
+ "foldhash",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "hermit-abi"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62b467343b94ba476dcb2500d242dadbb39557df889310ac77c5d99100aaac33"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
+[[package]]
+name = "hex"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+
+[[package]]
+name = "hostname"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "617aaa3557aef3810a6369d0a99fac8a080891b68bd9f9812a1eeda0c0730cbd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "windows-link",
+]
+
+[[package]]
+name = "http"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e9f41fd6a08e4d4ec69df65976da761afd5ad5e58a9d4acb46bd1c953a9e3ff2"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "humantime"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15cdd26707701c53297e2fa6afb323d55fbc1d0810c3aec078ae3ef0424c3c15"
+
+[[package]]
+name = "hyper"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d22053281f852e11534f5198498373cbb59295120a20771d90f7ed1897490a72"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "h2",
+ "http",
+ "http-body",
+ "httparse",
+ "itoa",
+ "pin-project-lite",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-timeout"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b90d566bffbce6a75bd8b09a05aa8c2cb1fabb6cb348f8840c9e4c90a0d83b0"
+dependencies = [
+ "hyper",
+ "hyper-util",
+ "pin-project-lite",
+ "tokio",
+ "tower-service",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
+dependencies = [
+ "bytes",
+ "futures-channel",
+ "futures-util",
+ "http",
+ "http-body",
+ "hyper",
+ "libc",
+ "pin-project-lite",
+ "socket2",
+ "tokio",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "image"
+version = "0.24.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5690139d2f55868e080017335e4b94cb7414274c74f1669c84fb5feba2c9f69d"
+dependencies = [
+ "bytemuck",
+ "byteorder",
+ "color_quant",
+ "jpeg-decoder",
+ "num-traits",
+ "png",
+]
+
+[[package]]
+name = "indexmap"
+version = "1.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99"
+dependencies = [
+ "autocfg",
+ "hashbrown 0.12.3",
+ "serde",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
+dependencies = [
+ "equivalent",
+ "hashbrown 0.17.1",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "inquire"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6654738b8024300cf062d04a1c13c10c8e2cea598ec1c47dc9b6641159429756"
+dependencies = [
+ "bitflags 2.13.1",
+ "crossterm",
+ "dyn-clone",
+ "fuzzy-matcher",
+ "unicode-segmentation",
+ "unicode-width 0.2.2",
+]
+
+[[package]]
+name = "intrusive-collections"
+version = "0.9.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "189d0897e4cbe8c75efedf3502c18c887b05046e59d28404d4d8e46cbc4d1e86"
+dependencies = [
+ "memoffset",
+]
+
+[[package]]
+name = "ipnetwork"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf466541e9d546596ee94f9f69590f89473455f88372423e0008fc1a7daf100e"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "is-terminal"
+version = "0.4.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
+dependencies = [
+ "hermit-abi 0.5.2",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "jiff"
+version = "0.2.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "668b7183bd07af9a4885f5c35b0cc5c83c4607a913c16b7e17291832910d2dcc"
+dependencies = [
+ "defmt",
+ "jiff-core",
+ "jiff-static",
+ "log",
+ "portable-atomic",
+ "portable-atomic-util",
+ "serde_core",
+]
+
+[[package]]
+name = "jiff-core"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7feca88439efe53da3754500c1851dedf3cb36c524dd5cf8225cc0794de95d09"
+dependencies = [
+ "defmt",
+]
+
+[[package]]
+name = "jiff-static"
+version = "0.2.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a69dcb3a21cfb32ce1cd056169337ca284af0766dd766e7878819b251a49204"
+dependencies = [
+ "jiff-core",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "jobserver"
+version = "0.1.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1c00acbd29eabad4a2392fa0e921c874934dbbf4194312ad20f04a0ed67a3cb3"
+dependencies = [
+ "getrandom 0.4.3",
+ "libc",
+]
+
+[[package]]
+name = "jpeg-decoder"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00810f1d8b74be64b13dbf3db89ac67740615d6c891f0e7b6179326533011a07"
+
+[[package]]
+name = "js-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "libredox"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c943259e342f1e06ff2da7a83eabdfe7f92ce10262688dbf1895ff0b3e6e4652"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "linked-hash-map"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
+[[package]]
+name = "local-ip-address"
+version = "0.6.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aa08fb2b1ec3ea84575e94b489d06d4ce0cbf052d12acd515838f50e3c3d63e3"
+dependencies = [
+ "libc",
+ "neli",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memmem"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a64a92489e2744ce060c349162be1c5f33c6969234104dbd99ddb5feb08b8c15"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "mio"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427"
+dependencies = [
+ "libc",
+ "log",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "multimap"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d87ecb2933e8aeadb3e3a02b828fed80a7528047e68b4f424523a0981a3a084"
+dependencies = [
+ "serde",
+]
+
+[[package]]
+name = "neli"
+version = "0.7.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22f9786d56d972959e1408b6a93be6af13b9c1392036c5c1fafa08a1b0c6ee87"
+dependencies = [
+ "bitflags 2.13.1",
+ "byteorder",
+ "derive_builder",
+ "getset",
+ "libc",
+ "log",
+ "neli-proc-macros",
+ "parking_lot",
+]
+
+[[package]]
+name = "neli-proc-macros"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05d8d08c6e98f20a62417478ebf7be8e1425ec9acecc6f63e22da633f6b71609"
+dependencies = [
+ "either",
+ "proc-macro2",
+ "quote",
+ "serde",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "netlog"
+version = "0.1.0"
+dependencies = [
+ "log",
+ "regex",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "nix"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
+dependencies = [
+ "bitflags 2.13.1",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+ "memoffset",
+]
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "nonzero_ext"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38bf9645c8b145698bb0b18a4637dcacbc421ea49bef2317e4fd8065a387cf21"
+
+[[package]]
+name = "num-conv"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "object"
+version = "0.37.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff76201f031d8863c38aa7f905eca4f53abbfa15f609db4277d44cd8938f33fe"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "octets"
+version = "0.3.6"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "openssl-macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a948666b637a0f465e8564c73e89d4dde00d72d4d473cc972f390fc3dcee7d9c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "opentelemetry"
+version = "0.31.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b84bcd6ae87133e903af7ef497404dda70c60d0ea14895fc8a5e6722754fc2a0"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+ "js-sys",
+ "pin-project-lite",
+ "thiserror 2.0.19",
+ "tracing",
+]
+
+[[package]]
+name = "opentelemetry-proto"
+version = "0.31.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7175df06de5eaee9909d4805a3d07e28bb752c34cab57fa9cff549da596b30f"
+dependencies = [
+ "base64",
+ "const-hex",
+ "opentelemetry",
+ "opentelemetry_sdk",
+ "prost",
+ "serde",
+ "serde_json",
+ "tonic",
+ "tonic-prost",
+]
+
+[[package]]
+name = "opentelemetry_sdk"
+version = "0.31.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e14ae4f5991976fd48df6d843de219ca6d31b01daaab2dad5af2badeded372bd"
+dependencies = [
+ "futures-channel",
+ "futures-executor",
+ "futures-util",
+ "opentelemetry",
+ "percent-encoding",
+ "rand 0.9.5",
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "option-ext"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
+
+[[package]]
+name = "os_str_bytes"
+version = "6.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2355d85b9a3786f481747ced0e0ff2ba35213a1f9bd406ed906554d7af805a1"
+
+[[package]]
+name = "papergrid"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ad43c07024ef767f9160710b3a6773976194758c7919b17e63b863db0bdf7fb"
+dependencies = [
+ "bytecount",
+ "fnv",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "papergrid"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6978128c8b51d8f4080631ceb2302ab51e32cc6e8615f735ee2f83fd269ae3f1"
+dependencies = [
+ "bytecount",
+ "fnv",
+ "unicode-width 0.2.2",
+]
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pathfinder_geometry"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b7b7e7b4ea703700ce73ebf128e1450eb69c3a8329199ffbfb9b2a0418e5ad3"
+dependencies = [
+ "log",
+ "pathfinder_simd",
+]
+
+[[package]]
+name = "pathfinder_simd"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4500030c302e4af1d423f36f3b958d1aecb6c04184356ed5a833bf6b60435777"
+dependencies = [
+ "rustc_version",
+]
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project"
+version = "1.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2466b2336ed02bcdca6b294417127b90ec92038d1d5c4fbeac971a922e0e0924"
+dependencies = [
+ "pin-project-internal",
+]
+
+[[package]]
+name = "pin-project-internal"
+version = "1.1.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
+[[package]]
+name = "plotters"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aeb6f403d7a4911efb1e33402027fc44f29b5bf6def3effcc22d7bb75f2b747"
+dependencies = [
+ "chrono",
+ "font-kit",
+ "image",
+ "lazy_static",
+ "num-traits",
+ "pathfinder_geometry",
+ "plotters-backend",
+ "plotters-bitmap",
+ "plotters-svg",
+ "ttf-parser",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "plotters-backend"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df42e13c12958a16b3f7f4386b9ab1f3e7933914ecea48da7139435263a4172a"
+
+[[package]]
+name = "plotters-bitmap"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72ce181e3f6bf82d6c1dc569103ca7b1bd964c60ba03d7e6cdfbb3e3eb7f7405"
+dependencies = [
+ "gif",
+ "image",
+ "plotters-backend",
+]
+
+[[package]]
+name = "plotters-canvas"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9126f053e70c9a2f2dd6998912a3536071e909fd37bde74b671402bfa441fc00"
+dependencies = [
+ "js-sys",
+ "plotters-backend",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "plotters-svg"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51bae2ac328883f7acdfea3d66a7c35751187f870bc81f94563733a154d7a670"
+dependencies = [
+ "plotters-backend",
+]
+
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags 1.3.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "portable-atomic"
+version = "1.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d20d5497ef88037a52ff98267d066e7f11fcc5e99bbfbd58a42336193aacec3"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "powerfmt"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "pretty_assertions"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ae130e2f271fbc2ac3a40fb1d07180839cdbbe443c7a27e1e3c13c5cac0116d"
+dependencies = [
+ "diff",
+ "yansi",
+]
+
+[[package]]
+name = "proc-macro-crate"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
+dependencies = [
+ "toml_edit",
+]
+
+[[package]]
+name = "proc-macro-error"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da25490ff9892aab3fcf7c36f08cfb902dd3e71ca0f9f9517bea02a73a5ce38c"
+dependencies = [
+ "proc-macro-error-attr",
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+ "version_check",
+]
+
+[[package]]
+name = "proc-macro-error-attr"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1be40180e52ecc98ad80b184934baf3d0d29f979574e439af5a55274b35f869"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "version_check",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "procfs"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc5b72d8145275d844d4b5f6d4e1eef00c8cd889edb6035c21675d1bb1f45c9f"
+dependencies = [
+ "bitflags 2.13.1",
+ "hex",
+ "procfs-core",
+ "rustix 0.38.44",
+]
+
+[[package]]
+name = "procfs-core"
+version = "0.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "239df02d8349b06fc07398a3a1697b06418223b1c7725085e801e7c0fc6a12ec"
+dependencies = [
+ "bitflags 2.13.1",
+ "hex",
+]
+
+[[package]]
+name = "prometheus"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ca5326d8d0b950a9acd87e6a3f94745394f62e4dae1b1ee22b2bc0c394af43a"
+dependencies = [
+ "cfg-if",
+ "fnv",
+ "lazy_static",
+ "libc",
+ "memchr",
+ "parking_lot",
+ "procfs",
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "prometheus-client"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83cd1b99916654a69008fd66b4f9397fbe08e6e51dfe23d4417acf5d3b8cb87c"
+dependencies = [
+ "dtoa",
+ "itoa",
+ "parking_lot",
+ "prometheus-client-derive-text-encode",
+]
+
+[[package]]
+name = "prometheus-client-derive-text-encode"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "66a455fbcb954c1a7decf3c586e860fd7889cddf4b8e164be736dbac95a953cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
+[[package]]
+name = "prometools"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06c0f1b9189e7361a3e32ded803ab2ecb9a829d86cc32ce3fba8cff1b0cd4b69"
+dependencies = [
+ "itoa",
+ "parking_lot",
+ "prometheus-client",
+ "ryu",
+ "serde",
+]
+
+[[package]]
+name = "proptest"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
+dependencies = [
+ "bitflags 2.13.1",
+ "num-traits",
+ "rand 0.9.5",
+ "rand_chacha",
+ "rand_xorshift",
+ "regex-syntax",
+ "unarray",
+]
+
+[[package]]
+name = "prost"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "528ac67416ff8646872a3c02cad9cc4ee5dc9f9540c9b10771855c95cb2e5ae1"
+dependencies = [
+ "bytes",
+ "prost-derive",
+]
+
+[[package]]
+name = "prost-derive"
+version = "0.14.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b570b25f7617e43d59005d0990ccb79e950a423952cea19671b7a876da390adf"
+dependencies = [
+ "anyhow",
+ "itertools 0.14.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "qlog"
+version = "0.18.0"
+dependencies = [
+ "flate2",
+ "foundations",
+ "humantime",
+ "pretty_assertions",
+ "serde",
+ "serde_json",
+ "serde_with",
+ "tempfile",
+ "zstd",
+]
+
+[[package]]
+name = "qlog-dancer"
+version = "0.1.0"
+dependencies = [
+ "clap 4.6.5",
+ "env_logger",
+ "futures-util",
+ "getrandom 0.3.4",
+ "js-sys",
+ "log",
+ "netlog",
+ "plotters",
+ "plotters-canvas",
+ "qlog",
+ "regex",
+ "serde",
+ "serde-wasm-bindgen",
+ "serde_json",
+ "smallvec",
+ "table_to_html",
+ "tabled 0.15.0",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams",
+ "web-sys",
+ "wirefilter-engine",
+]
+
+[[package]]
+name = "quanta"
+version = "0.12.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3ab5a9d756f0d97bdc89019bd2e4ea098cf9cde50ee7564dde6b81ccc8f06c7"
+dependencies = [
+ "crossbeam-utils",
+ "libc",
+ "once_cell",
+ "raw-cpuid",
+ "wasi",
+ "web-sys",
+ "winapi",
+]
+
+[[package]]
+name = "quiche"
+version = "0.29.3"
+dependencies = [
+ "boring",
+ "bytes",
+ "cdylib-link-lines",
+ "debug_panic",
+ "either",
+ "enum_dispatch",
+ "foreign-types-shared",
+ "intrusive-collections",
+ "libc",
+ "libm",
+ "log",
+ "mio",
+ "octets",
+ "qlog",
+ "ring",
+ "rstest",
+ "serde",
+ "serde_json",
+ "serde_with",
+ "sfv",
+ "slab",
+ "smallvec",
+ "url",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "quiche_apps"
+version = "0.1.0"
+dependencies = [
+ "docopt",
+ "env_logger",
+ "libc",
+ "log",
+ "mio",
+ "nix",
+ "octets",
+ "quiche",
+ "ring",
+ "url",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "r-efi"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
+
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.3",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
+[[package]]
+name = "rand_xorshift"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
+dependencies = [
+ "rand_core 0.9.5",
+]
+
+[[package]]
+name = "raw-cpuid"
+version = "11.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "498cd0dc59d73224351ee52a95fee0f1a617a2eae0e7d9d720cc622c73a54186"
+dependencies = [
+ "bitflags 2.13.1",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags 2.13.1",
+]
+
+[[package]]
+name = "redox_users"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
+dependencies = [
+ "getrandom 0.2.17",
+ "libredox",
+ "thiserror 2.0.19",
+]
+
+[[package]]
+name = "ref-cast"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "216e8f773d7923bcba9ceb86a86c93cabb3903a11872fc3f138c49630e50b96d"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c9283685feec7d69af75fb0e858d5e7378f33fe4fc699383b2916ab9273e03c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "regex"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "relative-path"
+version = "1.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba39f3699c378cd8970968dcbff9c43159ea4cfbd88d43c00b22f2ef10a435d2"
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.17",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rstest"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5a3193c063baaa2a95a33f03035c8a72b83d97a54916055ba22d35ed3839d49"
+dependencies = [
+ "futures-timer",
+ "futures-util",
+ "rstest_macros",
+]
+
+[[package]]
+name = "rstest_macros"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c845311f0ff7951c5506121a9ad75aec44d083c31583b2ea5a30bcb0b0abba0"
+dependencies = [
+ "cfg-if",
+ "glob",
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "relative-path",
+ "rustc_version",
+ "syn 2.0.119",
+ "unicode-ident",
+]
+
+[[package]]
+name = "rust_decimal"
+version = "1.42.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be2a24f50780bc85f09cc6ac299bdf1424302742d77221106859c9d8b102126a"
+dependencies = [
+ "arrayvec",
+ "num-traits",
+]
+
+[[package]]
+name = "rustc-demangle"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b74b56ffa8bb2830709a538c2cbcae9aa062db0d2a42563bfb09bdaae44020eb"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustix"
+version = "0.38.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
+dependencies = [
+ "bitflags 2.13.1",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.4.15",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags 2.13.1",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.12.1",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "schemars"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cd191f9397d57d581cddd31014772520aa448f65ef991055d7f61582c65165f"
+dependencies = [
+ "dyn-clone",
+ "ref-cast",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "schemars"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "687274d293b6cdc6e73e0fee520bf2049650090d7164f87672d212a3c530cf4a"
+dependencies = [
+ "dyn-clone",
+ "ref-cast",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde-wasm-bindgen"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8302e169f0eddcc139c70f139d19d6467353af16f9fce27e8c30158036a1e16b"
+dependencies = [
+ "js-sys",
+ "serde",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "indexmap 2.14.0",
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+
+[[package]]
+name = "serde_with"
+version = "3.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a5c54c7310e7b8b9577c286d7e399ddd876c3e12b3ed917a8aabc4b96e9e8c"
+dependencies = [
+ "base64",
+ "bs58",
+ "chrono",
+ "hex",
+ "indexmap 1.9.3",
+ "indexmap 2.14.0",
+ "schemars 0.9.0",
+ "schemars 1.2.2",
+ "serde_core",
+ "serde_json",
+ "serde_with_macros",
+ "time",
+]
+
+[[package]]
+name = "serde_with_macros"
+version = "3.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "84d57bc0c8b9a17920c178daa6bb924850d54a9c97ab45194bb8c17ad66bb660"
+dependencies = [
+ "darling 0.23.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "serde_yaml"
+version = "0.8.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "578a7433b776b56a35785ed5ce9a7e777ac0598aac5a6dd1b4b18a307c7fc71b"
+dependencies = [
+ "indexmap 1.9.3",
+ "ryu",
+ "serde",
+ "yaml-rust",
+]
+
+[[package]]
+name = "sfv"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f27daf6ed3fc7ffd5ea3ce9f684fe351c47e50f2fdbb6236e2bad0b440dbe408"
+dependencies = [
+ "data-encoding",
+ "indexmap 2.14.0",
+ "rust_decimal",
+]
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "signal-hook"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "sliceslice"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "361b80c452f3f8cc2426bf996059740b4c78ef5a5aeb1c1852d8ac4f561b8b4c"
+dependencies = [
+ "cfg-if",
+ "memchr",
+ "paste",
+ "seq-macro",
+]
+
+[[package]]
+name = "slog"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b3b8565691b22d2bdfc066426ed48f837fc0c5f2c8cad8d9718f7f99d6995c1"
+dependencies = [
+ "anyhow",
+ "erased-serde 0.3.31",
+ "rustversion",
+ "serde_core",
+]
+
+[[package]]
+name = "slog-async"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72c8038f898a2c79507940990f05386455b3a317d8f18d4caea7cbc3d5096b84"
+dependencies = [
+ "crossbeam-channel",
+ "slog",
+ "take_mut",
+ "thread_local",
+]
+
+[[package]]
+name = "slog-json"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e1e53f61af1e3c8b852eef0a9dee29008f55d6dd63794f3f12cef786cf0f219"
+dependencies = [
+ "serde",
+ "serde_json",
+ "slog",
+ "time",
+]
+
+[[package]]
+name = "slog-scope"
+version = "4.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42b76cf645c92e7850d5a1c9205ebf2864bd32c0ab3e978e6daad51fedf7ef54"
+dependencies = [
+ "arc-swap",
+ "lazy_static",
+ "slog",
+]
+
+[[package]]
+name = "slog-stdlog"
+version = "4.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6706b2ace5bbae7291d3f8d2473e2bfab073ccd7d03670946197aec98471fa3e"
+dependencies = [
+ "log",
+ "slog",
+ "slog-scope",
+]
+
+[[package]]
+name = "slog-term"
+version = "2.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cb1fc680b38eed6fad4c02b3871c09d2c81db8c96aa4e9c0a34904c830f09b5"
+dependencies = [
+ "chrono",
+ "is-terminal",
+ "slog",
+ "term",
+ "thread_local",
+ "time",
+]
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "socket2"
+version = "0.6.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "spinning_top"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d96d2d1d716fb500937168cc09353ffdc7a012be8475ac7308e1bdf0e3923300"
+dependencies = [
+ "lock_api",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "strsim"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "1.0.109"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "table_to_html"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d3b254ecd96aa3863439e99bf7a1ab9226a74ebbeab5c45da3a025153b79c1d"
+dependencies = [
+ "tabled 0.20.0",
+]
+
+[[package]]
+name = "tabled"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c998b0c8b921495196a48aabaf1901ff28be0760136e31604f7967b0792050e"
+dependencies = [
+ "papergrid 0.11.0",
+ "tabled_derive",
+ "unicode-width 0.1.14",
+]
+
+[[package]]
+name = "tabled"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e39a2ee1fbcd360805a771e1b300f78cc88fec7b8d3e2f71cd37bbf23e725c7d"
+dependencies = [
+ "papergrid 0.17.0",
+ "testing_table",
+]
+
+[[package]]
+name = "tabled_derive"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c138f99377e5d653a371cdad263615634cfc8467685dfe8e73e2b8e98f44b17"
+dependencies = [
+ "heck 0.4.1",
+ "proc-macro-error",
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
+[[package]]
+name = "take_mut"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f764005d11ee5f36500a149ace24e00e3da98b0158b3e2d53a7495660d3f4d60"
+
+[[package]]
+name = "task-killswitch"
+version = "0.2.1"
+dependencies = [
+ "dashmap",
+ "futures-util",
+ "parking_lot",
+ "tokio",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom 0.4.3",
+ "once_cell",
+ "rustix 1.1.4",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "term"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8c27177b12a6399ffc08b98f76f7c9a1f4fe9fc967c784c5a071fa8d93cf7e1"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "termcolor"
+version = "1.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06794f8f6c5c898b3275aebefa6b8a1cb24cd2c6c79397ab15774837a0bc5755"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "testing_table"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f8daae29995a24f65619e19d8d31dea5b389f3d853d8bf297bbf607cd0014cc"
+dependencies = [
+ "unicode-width 0.2.2",
+]
+
+[[package]]
+name = "textwrap"
+version = "0.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c13547615a44dc9c452a8a534638acdf07120d4b6847c8178705da06306a3057"
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl 1.0.69",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
+dependencies = [
+ "thiserror-impl 2.0.19",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "thread_local"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "thrift_codec"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83d957f535b242b91aa9f47bde08080f9a6fef276477e55b0079979d002759d5"
+dependencies = [
+ "byteorder",
+ "trackable",
+]
+
+[[package]]
+name = "time"
+version = "0.3.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3e1d5e639ff6bab73cb6885cc7e7b1de96c3f32c68ec55f3952614bec1092244"
+dependencies = [
+ "deranged",
+ "num-conv",
+ "powerfmt",
+ "serde_core",
+ "time-core",
+ "time-macros",
+]
+
+[[package]]
+name = "time-core"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
+
+[[package]]
+name = "time-macros"
+version = "0.2.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85"
+dependencies = [
+ "num-conv",
+ "time-core",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
+[[package]]
+name = "tokio"
+version = "1.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "tokio-quiche"
+version = "0.19.0"
+dependencies = [
+ "anyhow",
+ "assert_matches",
+ "boring",
+ "bytes",
+ "clap 4.6.5",
+ "crossbeam",
+ "datagram-socket",
+ "env_logger",
+ "foundations",
+ "futures",
+ "futures-util",
+ "h3i",
+ "http",
+ "http-body",
+ "http-body-util",
+ "ipnetwork",
+ "libc",
+ "log",
+ "nix",
+ "octets",
+ "pin-project",
+ "qlog",
+ "quiche",
+ "regex",
+ "serde",
+ "serde_json",
+ "serde_with",
+ "slog-scope",
+ "slog-stdlog",
+ "smallvec",
+ "task-killswitch",
+ "tempfile",
+ "thiserror 2.0.19",
+ "tokio",
+ "tokio-stream",
+ "tokio-util",
+ "url",
+]
+
+[[package]]
+name = "tokio-stream"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b"
+dependencies = [
+ "futures-core",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-io",
+ "futures-sink",
+ "futures-util",
+ "libc",
+ "pin-project-lite",
+ "slab",
+ "tokio",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.25.13+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6975367e4d2ef766d86af01ffad14b622fecc8d4357a998fbc4deb6e9bacaf9b"
+dependencies = [
+ "indexmap 2.14.0",
+ "toml_datetime",
+ "toml_parser",
+ "winnow",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.3+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
+dependencies = [
+ "winnow",
+]
+
+[[package]]
+name = "tonic"
+version = "0.14.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
+dependencies = [
+ "async-trait",
+ "base64",
+ "bytes",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-timeout",
+ "hyper-util",
+ "percent-encoding",
+ "pin-project",
+ "sync_wrapper",
+ "tokio",
+ "tokio-stream",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "tonic-prost"
+version = "0.14.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
+dependencies = [
+ "bytes",
+ "prost",
+ "tonic",
+]
+
+[[package]]
+name = "tower"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "indexmap 2.14.0",
+ "pin-project-lite",
+ "slab",
+ "sync_wrapper",
+ "tokio",
+ "tokio-util",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "trackable"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b15bd114abb99ef8cee977e517c8f37aee63f184f2d08e3e6ceca092373369ae"
+dependencies = [
+ "trackable_derive",
+]
+
+[[package]]
+name = "trackable_derive"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebeb235c5847e2f82cfe0f07eb971d1e5f6804b18dac2ae16349cc604380f82f"
+dependencies = [
+ "quote",
+ "syn 1.0.109",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "ttf-parser"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17f77d76d837a7830fe1d4f12b7b4ba4192c1888001c7164257e4bc6d21d96b4"
+
+[[package]]
+name = "typeid"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc7d623258602320d5c55d1bc22793b57daff0ec7efc270ea7d55ce1d5f5471c"
+
+[[package]]
+name = "unarray"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c62df1340f32221cb9c54d6a27b030e3dba64361d4a95bed55f9aacb44da291d"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "wasm-streams"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8622dcb61c0bcc9fffa6938bed81210af2da9a7e4a1a834b2e37a59b6dfb6141"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
+[[package]]
+name = "wildcard"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36241ad0795516b55e3b60e55c7f979d4f324e4aaea4c70d56b548b9164ee4d2"
+dependencies = [
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "winnow"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "wio"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d129932f4644ac2396cb456385cbf9e63b5b30c6e8dc4820bdca4eb082037a5"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "wirefilter-engine"
+version = "0.7.0"
+source = "git+https://github.com/cloudflare/wirefilter.git?rev=f3116d9f244d10a2d9a37d036cfa7129c5e50d3b#f3116d9f244d10a2d9a37d036cfa7129c5e50d3b"
+dependencies = [
+ "backtrace",
+ "cfg-if",
+ "cidr",
+ "fnv",
+ "getrandom 0.3.4",
+ "memmem",
+ "rand 0.9.5",
+ "regex-automata",
+ "serde",
+ "serde_json",
+ "sliceslice",
+ "thiserror 1.0.69",
+ "wildcard",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
+[[package]]
+name = "yaml-merge-keys"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af47d205071caaef70ebce5e04e1d88eba944833f8a6626dacdda700f86c285a"
+dependencies = [
+ "lazy_static",
+ "serde_yaml",
+ "thiserror 1.0.69",
+ "yaml-rust",
+]
+
+[[package]]
+name = "yaml-rust"
+version = "0.4.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56c1936c4cc7a1c9ab21a1ebb602eb942ba868cbd44a99cb7cdc5892335e1c85"
+dependencies = [
+ "linked-hash-map",
+]
+
+[[package]]
+name = "yansi"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
+
+[[package]]
+name = "yeslogic-fontconfig-sys"
+version = "6.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d8b8abf912b9a29ff112e1671c97c33636903d13a69712037190e6805af4f76"
+dependencies = [
+ "dlib",
+ "once_cell",
+ "pkg-config",
+]
+
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zerocopy"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.55"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+
+[[package]]
+name = "zstd"
+version = "0.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e91ee311a569c327171651566e07972200e76fcfe2242a4fa446149a3881c08a"
+dependencies = [
+ "zstd-safe",
+]
+
+[[package]]
+name = "zstd-safe"
+version = "7.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f49c4d5f0abb602a93fb8736af2a4f4dd9512e36f7f570d66e65ff867ed3b9d"
+dependencies = [
+ "zstd-sys",
+]
+
+[[package]]
+name = "zstd-sys"
+version = "2.0.16+zstd.1.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e19ebc2adc8f83e43039e79776e3fda8ca919132d68a1fed6a5faca2683748"
+dependencies = [
+ "cc",
+ "pkg-config",
+]
diff --git a/macOS/GhostHTTP3/scripts/build-framework.sh b/macOS/GhostHTTP3/scripts/build-framework.sh
new file mode 100755
index 0000000..e15627a
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/build-framework.sh
@@ -0,0 +1,152 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+source_dir=${build_dir}/upstream/quiche
+output_dir=${build_dir}/artifacts
+deployment_target=${MACOSX_DEPLOYMENT_TARGET:-15.0}
+lock_file=${project_dir}/quiche-0.29.3.Cargo.lock
+pacing_patch=${project_dir}/Patches/quiche-darwin-send-time.patch
+
+# quiche 0.29.3. Keep this immutable so the framework is reproducible.
+quiche_revision=55886df3be579579207104c8e645825b6347a209
+quiche_repository=https://github.com/cloudflare/quiche.git
+
+if ! command -v cargo >/dev/null 2>&1 || ! command -v rustup >/dev/null 2>&1; then
+    print -u2 "error: Rust 1.88 or newer installed with rustup is required"
+    exit 1
+fi
+
+rust_version=$(rustc --version | awk '{ print $2 }')
+version_parts=(${(s:.:)rust_version})
+if (( ${#version_parts} < 2 )) || \
+   (( version_parts[1] < 1 )) || \
+   (( version_parts[1] == 1 && version_parts[2] < 88 )); then
+    print -u2 "error: could not determine the Rust compiler version"
+    exit 1
+fi
+
+mkdir -p "${build_dir}/upstream" "${build_dir}/dylib" "${output_dir}"
+
+if [[ ! -d ${source_dir}/.git ]]; then
+    git clone --filter=blob:none --no-checkout "${quiche_repository}" "${source_dir}"
+fi
+
+git -C "${source_dir}" fetch --depth 1 origin "${quiche_revision}"
+git -C "${source_dir}" checkout --detach --force "${quiche_revision}"
+git -C "${source_dir}" apply --check "${pacing_patch}"
+git -C "${source_dir}" apply "${pacing_patch}"
+cp "${lock_file}" "${source_dir}/Cargo.lock"
+
+actual_revision=$(git -C "${source_dir}" rev-parse HEAD)
+if [[ ${actual_revision} != ${quiche_revision} ]]; then
+    print -u2 "error: expected quiche ${quiche_revision}, got ${actual_revision}"
+    exit 1
+fi
+
+target=aarch64-apple-darwin
+cargo_target_dir=${build_dir}/cargo-dylib
+wrapper_object=${build_dir}/dylib/GhostHTTP3.o
+
+rustup target add "${target}" >/dev/null
+
+xcrun clang \
+    -arch arm64 \
+    -fPIC \
+    -mmacosx-version-min="${deployment_target}" \
+    -I"${project_dir}/include" \
+    -I"${source_dir}/quiche/include" \
+    -c "${project_dir}/Sources/GhostHTTP3.c" \
+    -o "${wrapper_object}"
+
+# Ask Cargo for only a cdylib. The wrapper object is linked into that same
+# image, producing one dynamic library that exports both the complete quiche C
+# API and the small versioned GhostHTTP3 API. The explicit export roots keep
+# the C wrapper visible through rustc's cdylib export list.
+(
+    cd "${source_dir}"
+    MACOSX_DEPLOYMENT_TARGET="${deployment_target}" \
+        cargo rustc \
+            --locked \
+            --release \
+            --package quiche \
+            --features ffi \
+            --target "${target}" \
+            --target-dir "${cargo_target_dir}" \
+            --crate-type cdylib \
+            -- \
+            -C "link-arg=${wrapper_object}" \
+            -C 'link-arg=-Wl,-u,_ghost_http3_api_version' \
+            -C 'link-arg=-Wl,-u,_ghost_http3_backend_version' \
+            -C 'link-arg=-Wl,-u,_ghost_http3_application_protocol' \
+            -C 'link-arg=-Wl,-u,_ghost_http3_backend_is_ready' \
+            -C 'link-arg=-Wl,-exported_symbol,_ghost_http3_api_version' \
+            -C 'link-arg=-Wl,-exported_symbol,_ghost_http3_backend_version' \
+            -C 'link-arg=-Wl,-exported_symbol,_ghost_http3_application_protocol' \
+            -C 'link-arg=-Wl,-exported_symbol,_ghost_http3_backend_is_ready'
+)
+
+dylib_path=${cargo_target_dir}/${target}/release/libquiche.dylib
+if [[ ! -f ${dylib_path} ]]; then
+    print -u2 "error: Cargo did not produce the arm64 quiche dylib"
+    exit 1
+fi
+
+framework_dir=${output_dir}/GhostHTTP3.framework
+rm -rf "${framework_dir}" "${output_dir}/GhostHTTP3.xcframework"
+mkdir -p \
+    "${framework_dir}/Versions/A/Headers" \
+    "${framework_dir}/Versions/A/Modules" \
+    "${framework_dir}/Versions/A/Resources"
+
+cp "${dylib_path}" "${framework_dir}/Versions/A/GhostHTTP3"
+
+cp "${project_dir}/include/GhostHTTP3/GhostHTTP3.h" "${framework_dir}/Versions/A/Headers/GhostHTTP3.h"
+cp "${source_dir}/quiche/include/quiche.h" "${framework_dir}/Versions/A/Headers/quiche.h"
+cp "${project_dir}/include/module.modulemap" "${framework_dir}/Versions/A/Modules/module.modulemap"
+
+info_plist=${framework_dir}/Versions/A/Resources/Info.plist
+plutil -create xml1 "${info_plist}"
+plutil -insert CFBundleDevelopmentRegion -string en "${info_plist}"
+plutil -insert CFBundleExecutable -string GhostHTTP3 "${info_plist}"
+plutil -insert CFBundleIdentifier -string com.ghostvm.GhostHTTP3 "${info_plist}"
+plutil -insert CFBundleInfoDictionaryVersion -string 6.0 "${info_plist}"
+plutil -insert CFBundleName -string GhostHTTP3 "${info_plist}"
+plutil -insert CFBundlePackageType -string FMWK "${info_plist}"
+plutil -insert CFBundleShortVersionString -string 0.1.0 "${info_plist}"
+plutil -insert CFBundleVersion -string 1 "${info_plist}"
+plutil -insert MinimumOSVersion -string "${deployment_target}" "${info_plist}"
+
+ln -s A "${framework_dir}/Versions/Current"
+ln -s Versions/Current/GhostHTTP3 "${framework_dir}/GhostHTTP3"
+ln -s Versions/Current/Headers "${framework_dir}/Headers"
+ln -s Versions/Current/Modules "${framework_dir}/Modules"
+ln -s Versions/Current/Resources "${framework_dir}/Resources"
+
+xcrun install_name_tool \
+    -id '@rpath/GhostHTTP3.framework/Versions/A/GhostHTTP3' \
+    "${framework_dir}/Versions/A/GhostHTTP3"
+codesign --force --sign - --timestamp=none "${framework_dir}"
+
+source_fingerprint=$(
+    shasum -a 256 \
+        "${project_dir}/Sources/GhostHTTP3.c" \
+        "${project_dir}/include/GhostHTTP3/GhostHTTP3.h" \
+        "${project_dir}/include/module.modulemap" \
+        "${project_dir}/quiche-0.29.3.Cargo.lock" \
+        "${pacing_patch}" \
+        "${project_dir}/scripts/build-framework.sh" \
+        "${project_dir}/scripts/ensure-framework.sh" | \
+        shasum -a 256 | awk '{ print $1 }'
+)
+print -r -- "${source_fingerprint}" > "${output_dir}/.source-fingerprint"
+
+file "${framework_dir}/GhostHTTP3" | rg -q 'Mach-O 64-bit dynamically linked shared library arm64'
+[[ $(lipo -archs "${framework_dir}/GhostHTTP3") == arm64 ]]
+otool -D "${framework_dir}/GhostHTTP3" | \
+    rg -q '^@rpath/GhostHTTP3\.framework/Versions/A/GhostHTTP3$'
+
+print "Built arm64 dynamic framework ${output_dir}/GhostHTTP3.framework"
diff --git a/macOS/GhostHTTP3/scripts/build-with-rust-dmg.sh b/macOS/GhostHTTP3/scripts/build-with-rust-dmg.sh
new file mode 100755
index 0000000..a7dd983
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/build-with-rust-dmg.sh
@@ -0,0 +1,29 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+mount_point=${GHOST_HTTP3_RUST_MOUNT:-${build_dir}/mount/GhostHTTP3Rust188}
+
+"${script_dir}/create-rust-toolchain-dmg.sh"
+
+export CARGO_HOME=${mount_point}/cargo
+export RUSTUP_HOME=${mount_point}/rustup
+export PATH=${CARGO_HOME}/bin:${PATH}
+
+"${script_dir}/build-framework.sh"
+"${script_dir}/test-framework.sh"
+"${script_dir}/test-stress.sh"
+"${script_dir}/test-http3.sh"
+"${script_dir}/test-chaos.sh"
+
+# Optional, bounded seed-progression soak. Off by default to keep CI builds
+# under the framework build budget; enable with GHOST_HTTP3_SOAK=1 (and see
+# the soak-chaos.sh env knobs for further tuning).
+if [[ ${GHOST_HTTP3_SOAK:-0} == 1 ]]; then
+    "${script_dir}/soak-chaos.sh"
+fi
+
+print "To detach the reusable toolchain: hdiutil detach ${mount_point}"
diff --git a/macOS/GhostHTTP3/scripts/create-rust-toolchain-dmg.sh b/macOS/GhostHTTP3/scripts/create-rust-toolchain-dmg.sh
new file mode 100755
index 0000000..d3c54ad
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/create-rust-toolchain-dmg.sh
@@ -0,0 +1,59 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+image_dir=${build_dir}/toolchains
+image_path=${GHOST_HTTP3_RUST_IMAGE:-${image_dir}/Rust-1.88.0-macOS-arm64.sparseimage}
+mount_point=${GHOST_HTTP3_RUST_MOUNT:-${build_dir}/mount/GhostHTTP3Rust188}
+volume_name=GhostHTTP3Rust188
+rust_version=1.88.0
+
+mkdir -p "${image_dir}"
+
+if [[ ! -f ${image_path} ]]; then
+    hdiutil create \
+        -size 4g \
+        -fs APFS \
+        -volname "${volume_name}" \
+        -type SPARSE \
+        "${image_path}"
+fi
+
+if ! mount | grep -Fq " on ${mount_point} ("; then
+    mkdir -p "${mount_point}"
+    hdiutil attach -nobrowse -mountpoint "${mount_point}" "${image_path}"
+fi
+
+mkdir -p "${mount_point}/cargo" "${mount_point}/rustup" "${mount_point}/bootstrap"
+
+rustup_init=${mount_point}/bootstrap/rustup-init
+if [[ ! -x ${rustup_init} ]]; then
+    curl --fail --location --show-error \
+        https://static.rust-lang.org/rustup/dist/aarch64-apple-darwin/rustup-init \
+        -o "${rustup_init}"
+    chmod 755 "${rustup_init}"
+fi
+
+if [[ ! -x ${mount_point}/cargo/bin/rustc ]]; then
+    CARGO_HOME="${mount_point}/cargo" \
+    RUSTUP_HOME="${mount_point}/rustup" \
+        "${rustup_init}" \
+            -y \
+            --no-modify-path \
+            --profile minimal \
+            --default-toolchain "${rust_version}"
+fi
+
+CARGO_HOME="${mount_point}/cargo" \
+RUSTUP_HOME="${mount_point}/rustup" \
+    "${mount_point}/cargo/bin/rustup" target add \
+        aarch64-apple-darwin
+
+print "Rust toolchain image: ${image_path}"
+print "Mounted at: ${mount_point}"
+CARGO_HOME="${mount_point}/cargo" \
+RUSTUP_HOME="${mount_point}/rustup" \
+    "${mount_point}/cargo/bin/rustc" --version
diff --git a/macOS/GhostHTTP3/scripts/ensure-framework.sh b/macOS/GhostHTTP3/scripts/ensure-framework.sh
new file mode 100755
index 0000000..1d52c5f
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/ensure-framework.sh
@@ -0,0 +1,42 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+framework=${project_dir}/.build/artifacts/GhostHTTP3.framework
+binary=${framework}/Versions/A/GhostHTTP3
+fingerprint_file=${project_dir}/.build/artifacts/.source-fingerprint
+source_fingerprint=$(
+    shasum -a 256 \
+        "${project_dir}/Sources/GhostHTTP3.c" \
+        "${project_dir}/include/GhostHTTP3/GhostHTTP3.h" \
+        "${project_dir}/include/module.modulemap" \
+        "${project_dir}/quiche-0.29.3.Cargo.lock" \
+        "${project_dir}/Patches/quiche-darwin-send-time.patch" \
+        "${project_dir}/scripts/build-framework.sh" \
+        "${project_dir}/scripts/ensure-framework.sh" | \
+        shasum -a 256 | awk '{ print $1 }'
+)
+
+if [[ -f ${binary} ]] && \
+   [[ $(lipo -archs "${binary}" 2>/dev/null) == arm64 ]] && \
+   [[ -f ${fingerprint_file} ]] && \
+   [[ $(<"${fingerprint_file}") == ${source_fingerprint} ]]; then
+    print "GhostHTTP3 framework already built; skipping."
+    exit 0
+fi
+
+if command -v cargo >/dev/null 2>&1 && command -v rustup >/dev/null 2>&1; then
+    exec "${script_dir}/build-framework.sh"
+fi
+
+# Keep the Rust installation out of the host environment. The mounted image
+# is reusable by later Xcode and Make builds.
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+mount_point=${GHOST_HTTP3_RUST_MOUNT:-${build_dir}/mount/GhostHTTP3Rust188}
+"${script_dir}/create-rust-toolchain-dmg.sh"
+export CARGO_HOME=${mount_point}/cargo
+export RUSTUP_HOME=${mount_point}/rustup
+export PATH=${CARGO_HOME}/bin:${PATH}
+exec "${script_dir}/build-framework.sh"
diff --git a/macOS/GhostHTTP3/scripts/soak-chaos.sh b/macOS/GhostHTTP3/scripts/soak-chaos.sh
new file mode 100755
index 0000000..e5cfaf5
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/soak-chaos.sh
@@ -0,0 +1,119 @@
+#!/bin/zsh
+
+# Deterministic seed-progression soak for the GhostHTTP3 chaos phase.
+#
+# Re-runs the conservative chaos scenarios across an advancing seed range
+# with a wall-clock budget, no root, and no second host. Because losing
+# a handshake-critical datagram inside quiche's 5s idle timeout causes some
+# seeds to stall the stock http3 example independent of framework health,
+# the soak treats those stalls as documented findings (it logs them but does
+# NOT factor them into the pass/fail verdict). Real failures are: process
+# leaks, proxy-queue overflows, lost-client-address, server-failed-h3, or a
+# non-loss scenario that could not complete.
+#
+# Tunables (environment):
+#   GHOST_HTTP3_SOAK_SEED_START       first seed (default 7)
+#   GHOST_HTTP3_SOAK_SEED_COUNT       how many successive seeds (default 5)
+#   GHOST_HTTP3_SOAK_MAX_SECONDS      wall-clock budget (default 240s; checked
+#                                     between seeds)
+#   GHOST_HTTP3_SOAK_MAX_ITERATIONS   hard cap on seeds run (default: off/0)
+#   GHOST_HTTP3_SOAK_ITERATIONS       per-seed chaos iterations (default 2)
+#   GHOST_HTTP3_SOAK_SANITIZERS=1    build the proxy with ASan/UBSan
+#   GHOST_HTTP3_SOAK_HARSH=1         also run the harsh-loss reproducer/seed
+#   GHOST_HTTP3_SOAK_QUIET=1         suppress per-seed chaos output
+#
+# Tip: combine with GHOST_HTTP3_SOAK_MAX_ITERATIONS=20 to bound the maximum
+# CPU/IO commitment while still exercising budgeted seeds.
+
+set -uo pipefail
+
+script_dir=${0:A:h}
+
+soak_seed_start=${GHOST_HTTP3_SOAK_SEED_START:-7}
+soak_seed_count=${GHOST_HTTP3_SOAK_SEED_COUNT:-5}
+soak_max_seconds=${GHOST_HTTP3_SOAK_MAX_SECONDS:-240}
+soak_max_iterations=${GHOST_HTTP3_SOAK_MAX_ITERATIONS:-0}
+soak_iterations=${GHOST_HTTP3_SOAK_ITERATIONS:-3}
+soak_sanitizers=${GHOST_HTTP3_SOAK_SANITIZERS:-0}
+soak_harsh=${GHOST_HTTP3_SOAK_HARSH:-0}
+soak_quiet=${GHOST_HTTP3_SOAK_QUIET:-0}
+
+starts_at=$(date +%s)
+deadline=$((starts_at + soak_max_seconds))
+
+passes=0
+stalls=0
+low_drop=0
+fails=0
+completed=0
+
+last_seed=$((soak_seed_start + soak_seed_count - 1))
+for ((seed = soak_seed_start; seed <= last_seed; seed++)); do
+    if (( $(date +%s) >= deadline )); then
+        print -r -u2 -- "soak: wall-clock cap ${soak_max_seconds}s reached, stopping at seed ${seed}"
+        break
+    fi
+    if (( soak_max_iterations > 0 && completed >= soak_max_iterations )); then
+        print -r -u2 -- "soak: iteration cap ${soak_max_iterations} reached, stopping at seed ${seed}"
+        break
+    fi
+
+    out_file=$(mktemp -t ghost_http3_soak.XXXXXX)
+    env_vars=(
+        GHOST_HTTP3_CHAOS_SEED=${seed}
+        GHOST_HTTP3_CHAOS_ITERATIONS=${soak_iterations}
+        GHOST_HTTP3_CHAOS_CLIENT_TIMEOUT=25
+        GHOST_HTTP3_CHAOS_PROXY_MAX_DURATION=180
+        # Forces strict chaos mode so the soak classifier can distinguish
+        # STALL / LOW-DROP / FAIL outcomes; the chaos test's tolerant
+        # default would mask all but structural failures.
+        GHOST_HTTP3_CHAOS_TOLERATE_STALL=0
+    )
+    if (( soak_sanitizers )); then
+        env_vars+=(GHOST_HTTP3_TEST_SANITIZERS=1)
+    fi
+    if [[ ${soak_harsh} == 1 ]]; then
+        env_vars+=(GHOST_HTTP3_CHAOS_HARSH=1)
+    fi
+
+    if env "${env_vars[@]}" "${script_dir}/test-chaos.sh" >"${out_file}" 2>&1; then
+        passes=$((passes + 1))
+        [[ ${soak_quiet} == 0 ]] && print -r -- "soak seed=${seed}: PASS"
+    else
+        # The chaos script exits non-zero for three classes of run. We
+        # classify each so the soak only fails on framework regressions:
+        #   * STALLED: a quiche example idle-timeout fire (5s) on the loss
+        #     scenario when this seed happened to drop a handshake-critical
+        #     flight. Documented; not a framework bug.
+        #   * LOW_DROP: a non-loss assertion threshold (dup, reorder, mtu)
+        #     wasn't met for this low-packet seed. The impairment was
+        #     configured but fired too rarely to elicit the threshold on a
+        #     short loopback flow. Informational; not a framework bug.
+        #   * FAIL: structural — proxy queue overflow, drop_nopeer,
+        #     server-failed-h3, ASan error, or unclassified chaos failure.
+        if rg -q 'idle timeout fired|stalled handshake|client watchdog timed out|ALPN h3 not negotiated|ALPN h3 or HTTP/3 success markers missing' "${out_file}"; then
+            stalls=$((stalls + 1))
+            [[ ${soak_quiet} == 0 ]] && print -r -- "soak seed=${seed}: STALLED (documented quiche example idle-timeout limit)"
+        elif rg -q "dropped no datagrams at all|fired no dups at all|did not reorder any packets|delayed nothing|dropped no oversized datagram|did not actually drop" "${out_file}"; then
+            low_drop=$((low_drop + 1))
+            [[ ${soak_quiet} == 0 ]] && print -r -- "soak seed=${seed}: LOW-DROP (impairment configured but fired below threshold on this short flow)"
+        else
+            fails=$((fails + 1))
+            print -r -u2 -- "soak seed=${seed}: FAIL"
+            tail -12 "${out_file}" >&2
+        fi
+    fi
+    rm -f "${out_file}" 2>/dev/null || true
+    completed=$((completed + 1))
+done
+
+elapsed=$(( $(date +%s) - starts_at ))
+print -r -- "soak summary: seeds_tried=${completed} passes=${passes} stalls=${stalls} low_drop=${low_drop} fails=${fails} elapsed=${elapsed}s"
+print -r -- "soak budget: seed_start=${soak_seed_start} seed_count=${soak_seed_count} max_seconds=${soak_max_seconds} max_iterations=${soak_max_iterations} iterations=${soak_iterations} (time checked between seeds)"
+
+# Stalls and low-drop counts are documented/informational and do not gate the
+# exit code. Only structural failures do.
+if (( fails > 0 )); then
+    exit 1
+fi
+exit 0
diff --git a/macOS/GhostHTTP3/scripts/test-chaos.sh b/macOS/GhostHTTP3/scripts/test-chaos.sh
new file mode 100755
index 0000000..1f1e21e
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/test-chaos.sh
@@ -0,0 +1,489 @@
+#!/bin/zsh
+
+# Drives the deterministic UDP chaos proxy phase: compiles the proxy and the
+# upstream quiche C HTTP/3 client/server against the packaged
+# GhostHTTP3.framework, then replays conservative impairment scenarios that
+# must all end in a successful RFC 9114 exchange (GET / -> 200 "byez").
+#
+# Every scenario asserts both ends: the client/server logs prove HTTP/3
+# success over QUIC, and the proxy's own counters prove the impairments
+# actually fired (loss, duplication, delay/jitter, reordering, MTU drops).
+#
+# Conservatism invariants (read before changing any rate/seed):
+#   * The stock quiche example sets max_idle_timeout=5000ms. Any loss that
+#     drops a handshake-critical datagram can stall the client until that
+#     idle timeout, so per-direction loss rates are deliberately small and
+#     the seed is fixed. The harsh-loss reproducer below documents the
+#     failure mode that motivated this conservatism (opt-in).
+#   * Proxy stats (drop_loss, dup, delayed, reordered, drop_mtu) are the
+#     source of truth for "impairment fired". quiche's own `lost=` counter
+#     is NOT asserted because it does not increment on small flows whose
+#     retransmissions complete before QUIC declares a packet lost.
+#
+# Tunables (environment):
+#   GHOST_HTTP3_CHAOS_SEED          impairment PRNG seed (default 7)
+#   GHOST_HTTP3_CHAOS_ITERATIONS    client runs per scenario (default 3)
+#   GHOST_HTTP3_CHAOS_PORT_BASE     first candidate UDP port (default derived
+#                                   from this script's PID)
+#   GHOST_HTTP3_CHAOS_SERVER_PORT / GHOST_HTTP3_CHAOS_PROXY_PORT
+#                                   pin both ports explicitly (skips the scan)
+#   GHOST_HTTP3_CHAOS_CLIENT_TIMEOUT  per-client watchdog (default 25s; must
+#                                     exceed quiche's 5s idle timeout with
+#                                     margin for retransmission drains)
+#   GHOST_HTTP3_CHAOS_PROXY_MAX_DURATION  proxy self-termination bound (300s)
+#   GHOST_HTTP3_CHAOS_HARSH=1       also run the harsh-loss reproducer
+#                                  (expected to stall; documents the limit)
+#   GHOST_HTTP3_CHAOS_TOLERATE_STALL=1
+#                                   diagnostic mode only: count client stalls
+#                                   rather than failing the conservative phase
+#   GHOST_HTTP3_TEST_SANITIZERS=1   build the proxy with ASan/UBSan
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+framework_dir=${build_dir}/artifacts/GhostHTTP3.framework
+examples_dir=${build_dir}/upstream/quiche/quiche/examples
+test_dir=${build_dir}/tests
+proxy_binary=${test_dir}/udp-chaos-proxy
+datagram_binary=${test_dir}/udp-datagram
+
+seed=${GHOST_HTTP3_CHAOS_SEED:-7}
+iterations=${GHOST_HTTP3_CHAOS_ITERATIONS:-3}
+port_base=${GHOST_HTTP3_CHAOS_PORT_BASE:-$((20000 + ($$ % 30000)))}
+client_timeout=${GHOST_HTTP3_CHAOS_CLIENT_TIMEOUT:-25}
+proxy_max_duration=${GHOST_HTTP3_CHAOS_PROXY_MAX_DURATION:-300}
+harsh=${GHOST_HTTP3_CHAOS_HARSH:-0}
+# Diagnostic escape hatch only. The default gate is strict: every conservative
+# exchange must complete successfully. Tolerant mode is useful for exploring
+# seeds around the stock examples' hard-coded 5s idle-timeout boundary, but a
+# tolerant run is never reported as a passing recovery gate.
+tolerate_stalls=${GHOST_HTTP3_CHAOS_TOLERATE_STALL:-0}
+
+if [[ ! -d ${framework_dir} ]]; then
+    print -u2 "error: GhostHTTP3.framework is missing; run build-framework.sh first"
+    exit 1
+fi
+
+if [[ ! -f /opt/homebrew/include/ev.h || ! -f /opt/homebrew/include/uthash.h ]]; then
+    print -u2 "error: chaos test requires: brew install libev uthash"
+    exit 1
+fi
+
+if [[ ! -f ${examples_dir}/cert.crt || ! -f ${examples_dir}/cert.key ]]; then
+    print -u2 "error: quiche example TLS identity is missing; run build-framework.sh first"
+    exit 1
+fi
+
+mkdir -p "${test_dir}"
+
+sanitize_flags=()
+if [[ ${GHOST_HTTP3_TEST_SANITIZERS:-0} == 1 ]]; then
+    sanitize_flags=(
+        -O1
+        -fno-omit-frame-pointer
+        -fsanitize=address,undefined
+    )
+fi
+
+xcrun clang \
+    -std=c17 \
+    -O2 \
+    -Wall \
+    -Wextra \
+    -Werror \
+    -Wno-unused-parameter \
+    "${sanitize_flags[@]}" \
+    "${project_dir}/Tests/udp-chaos-proxy.c" \
+    -o "${proxy_binary}"
+
+xcrun clang \
+    -std=c17 \
+    -O2 \
+    -Wall \
+    -Wextra \
+    -Werror \
+    "${project_dir}/Tests/udp-datagram.c" \
+    -o "${datagram_binary}"
+
+common_flags=(
+    -O2
+    -I"${framework_dir}/Headers"
+    -I/opt/homebrew/include
+    -L/opt/homebrew/lib
+    -F"${build_dir}/artifacts"
+    -framework GhostHTTP3
+    -Wl,-rpath,@executable_path/../artifacts
+    -lev
+)
+
+xcrun clang "${common_flags[@]}" \
+    "${examples_dir}/http3-server.c" \
+    -o "${test_dir}/http3-server"
+
+xcrun clang "${common_flags[@]}" \
+    "${examples_dir}/http3-client.c" \
+    -o "${test_dir}/http3-client"
+
+# --- collision-resistant port selection -------------------------------------
+# The proxy's probe mode binds a candidate UDP port: exit 0 means free.
+port_free() {
+    "${proxy_binary}" --probe-port "$1" >/dev/null 2>&1
+}
+
+server_port=${GHOST_HTTP3_CHAOS_SERVER_PORT:-}
+proxy_port=${GHOST_HTTP3_CHAOS_PROXY_PORT:-}
+
+if [[ -z ${server_port} && -z ${proxy_port} ]]; then
+    candidate=${port_base}
+    for (( attempt = 0; attempt < 200; attempt++ )); do
+        if (( candidate + 1 > 65535 )); then
+            break
+        fi
+        if port_free ${candidate} && port_free $(( candidate + 1 )); then
+            server_port=${candidate}
+            proxy_port=$(( candidate + 1 ))
+            break
+        fi
+        (( candidate += 2 ))
+    done
+fi
+
+if [[ -z ${server_port} || -z ${proxy_port} ]]; then
+    print -u2 "error: could not find a free UDP port pair (set GHOST_HTTP3_CHAOS_SERVER_PORT and GHOST_HTTP3_CHAOS_PROXY_PORT)"
+    exit 1
+fi
+
+print "chaos phase: seed=${seed} iterations=${iterations} server_port=${server_port} proxy_port=${proxy_port}"
+
+# --- process lifecycle -------------------------------------------------------
+server_pid=""
+proxy_pid=""
+server_log=""
+proxy_log=""
+client_log=""
+
+cleanup() {
+    [[ -n ${proxy_pid} ]] && kill ${proxy_pid} >/dev/null 2>&1 || true
+    [[ -n ${server_pid} ]] && kill ${server_pid} >/dev/null 2>&1 || true
+    wait >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+trap 'cleanup; exit 130' INT
+trap 'cleanup; exit 143' TERM HUP
+
+fail() {
+    # Use `print -r -- ` so leading dashes in the message (e.g. "--- tail")
+    # are not parsed as options. zsh otherwise aborts the function before
+    # the diagnostic tail is emitted, turning real failures into the
+    # misleading "print: bad option: -" line.
+    print -r -u2 -- "error: $1"
+    for log in "${client_log}" "${server_log}" "${proxy_log}"; do
+        if [[ -n ${log} && -f ${log} ]]; then
+            print -r -u2 -- "=== tail ${log} ==="
+            tail -30 "${log}" >&2
+        fi
+    done
+    exit 1
+}
+
+wait_server_ready() {
+    for (( i = 0; i < 100; i++ )); do
+        kill -0 ${server_pid} 2>/dev/null || return 1
+        port_free ${server_port} || return 0
+        sleep 0.05
+    done
+    return 1
+}
+
+wait_proxy_ready() {
+    for (( i = 0; i < 100; i++ )); do
+        kill -0 ${proxy_pid} 2>/dev/null || return 1
+        rg -q '^listening on ' "${proxy_log}" 2>/dev/null && return 0
+        sleep 0.05
+    done
+    return 1
+}
+
+run_client() {
+    local log=$1
+    (
+        cd "${examples_dir}"
+        exec "${test_dir}/http3-client" 127.0.0.1 ${proxy_port}
+    ) >"${log}" 2>&1 &
+    local client_pid=$!
+    local waited=0
+    while kill -0 ${client_pid} 2>/dev/null; do
+        if (( waited >= client_timeout * 10 )); then
+            kill -9 ${client_pid} >/dev/null 2>&1 || true
+            wait ${client_pid} >/dev/null 2>&1 || true
+            print -r -u2 -- "client watchdog killed PID ${client_pid} after ${client_timeout}s"
+            return 124
+        fi
+        sleep 0.1
+        (( waited += 1 ))
+    done
+    local rc=0
+    wait ${client_pid} >/dev/null 2>&1 || rc=$?
+    if (( rc != 0 )); then
+        # The stock quiche example returns non-zero when the 5s idle
+        # timeout fires (handshake stall). Surface that explicitly so the
+        # caller can fail with the right message instead of letting the
+        # rg assertions later guess what happened.
+        print -r -u2 -- "http3-client exited with status ${rc}"
+    fi
+    return ${rc}
+}
+
+# Extracts FIELD from the last "stats dir=DIR ..." line of a proxy log.
+stat_value() {
+    local log=$1 dir=$2 field=$3
+    rg "^stats dir=${dir} " "${log}" | tail -1 | sed -E "s/.* ${field}=([0-9]+).*/\1/"
+}
+
+# Runs one scenario: fresh server + proxy, ${iterations} client exchanges,
+# then a graceful proxy shutdown so its cumulative stats land in the log.
+# After it returns, callers assert on ${proxy_log}/${server_log}/${client_log}.
+#
+# When scenario_tolerate_stall=1 (set by the harsh-loss reproducer), a
+# per-iteration client stall — non-zero exit, idle-timeout fire, or missing
+# HTTP/3 success marker — is recorded into ${stalled} and ${completed} globals
+# rather than aborting the script. The mandatory invariants (bounded queue,
+# known peer, clean process teardown) are still asserted below.
+scenario_tolerate_stall=${tolerate_stalls}
+stalled=0
+completed=0
+# Cumulative counters across scenarios; printed in the final summary.
+total_stalls=0
+total_completed=0
+total_iterations=0
+# A scenario may inject one harmless oversized UDP datagram after all HTTP/3
+# clients have completed. This proves the proxy's MTU filter/counter without
+# turning the stock quiche example's 5s idle timeout into a flaky black-hole
+# recovery assertion.
+mtu_probe_bytes=0
+
+run_scenario() {
+    local name=$1; shift
+
+    server_log=${test_dir}/chaos-${name}-server.log
+    proxy_log=${test_dir}/chaos-${name}-proxy.log
+    client_log=${test_dir}/chaos-${name}-client.log
+    : > "${client_log}"
+
+    # Start each scenario with fresh counters so toleration accounting is
+    # visible to the caller before we re-enter the next scenario.
+    stalled=0
+    completed=0
+    total_iterations=$((total_iterations + iterations))
+
+    print "== scenario ${name}: $*"
+
+    (
+        cd "${examples_dir}"
+        exec "${test_dir}/http3-server" 127.0.0.1 ${server_port}
+    ) >"${server_log}" 2>&1 &
+    server_pid=$!
+    wait_server_ready || fail "http3-server did not start on 127.0.0.1:${server_port}"
+
+    "${proxy_binary}" \
+        --listen-port ${proxy_port} \
+        --target-port ${server_port} \
+        --seed ${seed} \
+        --max-duration ${proxy_max_duration} \
+        "$@" >"${proxy_log}" 2>&1 &
+    proxy_pid=$!
+    wait_proxy_ready || fail "udp-chaos-proxy did not start on 127.0.0.1:${proxy_port}"
+
+    for (( iteration = 1; iteration <= iterations; iteration++ )); do
+        local iteration_log=${client_log}.${iteration}
+        local rc=0
+        run_client "${iteration_log}" || rc=$?
+        local marker_ok=0
+        if rg -q "connection established: h3" "${iteration_log}" && \
+           rg -q "got HTTP header: :status=200" "${iteration_log}" && \
+           rg -q "got HTTP header: content-length=5" "${iteration_log}" && \
+           rg -q "^byez" "${iteration_log}"; then
+            marker_ok=1
+        fi
+
+        if (( marker_ok )); then
+            completed=$((completed + 1))
+        elif (( scenario_tolerate_stall == 1 )); then
+            stalled=$((stalled + 1))
+        elif (( rc == 124 )); then
+            fail "client watchdog timed out after ${client_timeout}s (scenario ${name}, iteration ${iteration})"
+        elif (( rc != 0 )); then
+            fail "http3-client exited ${rc}, likely the 5s idle timeout fired on a stalled handshake (scenario ${name}, iteration ${iteration})"
+        else
+            fail "ALPN h3 or HTTP/3 success markers missing (scenario ${name}, iteration ${iteration})"
+        fi
+
+        cat "${iteration_log}" >> "${client_log}"
+    done
+
+    if (( mtu_probe_bytes > 0 )); then
+        "${datagram_binary}" 127.0.0.1 ${proxy_port} ${mtu_probe_bytes} || \
+            fail "could not inject ${mtu_probe_bytes}-byte MTU probe (scenario ${name})"
+        # Give the loopback relay a bounded moment to account for the packet
+        # before asking it to print its final counters and terminate.
+        sleep 0.2
+    fi
+
+    kill -TERM ${proxy_pid} >/dev/null 2>&1 || true
+    wait ${proxy_pid} >/dev/null 2>&1 || true
+    proxy_pid=""
+
+    kill ${server_pid} >/dev/null 2>&1 || true
+    wait ${server_pid} >/dev/null 2>&1 || true
+    server_pid=""
+
+    # The mandatory invariants hold even when stalls are tolerated.
+    local dir
+    for dir in c2s s2c; do
+        [[ $(stat_value "${proxy_log}" ${dir} drop_full) == 0 ]] || \
+            fail "proxy queue overflowed (scenario ${name}, ${dir})"
+        [[ $(stat_value "${proxy_log}" ${dir} drop_nopeer) == 0 ]] || \
+            fail "proxy lost track of the client address (scenario ${name}, ${dir})"
+        [[ $(stat_value "${proxy_log}" ${dir} send_error) == 0 ]] || \
+            fail "proxy failed to forward a datagram (scenario ${name}, ${dir})"
+        [[ $(stat_value "${proxy_log}" ${dir} queued) == 0 ]] || \
+            fail "proxy stopped with queued datagrams (scenario ${name}, ${dir})"
+    done
+
+    # Any completed client proves the server should have negotiated h3. Strict
+    # mode necessarily has completions; an all-stalled diagnostic run does not.
+    if (( completed > 0 || scenario_tolerate_stall == 0 )); then
+        rg -q 'proto=Ok\("h3"\)' "${server_log}" || \
+            fail "server did not negotiate h3 (scenario ${name})"
+    fi
+
+    if (( scenario_tolerate_stall == 1 )); then
+        print "   tolerated: ${stalled}/${iterations} iterations stalled, ${completed}/${iterations} completed"
+    fi
+
+    total_stalls=$((total_stalls + stalled))
+    total_completed=$((total_completed + completed))
+
+    rg '^stats' "${proxy_log}" | sed 's/^/   /'
+}
+
+total() {
+    local field=$1
+    echo $(( $(stat_value "${proxy_log}" c2s ${field}) + \
+             $(stat_value "${proxy_log}" s2c ${field}) ))
+}
+
+# --- scenarios ---------------------------------------------------------------
+
+# Transparency baseline: the unimpaired proxy must be invisible.
+run_scenario baseline
+[[ $(total tx) == $(total rx) ]] || fail "baseline proxy dropped or invented datagrams"
+[[ $(stat_value "${proxy_log}" c2s reordered) == 0 && \
+   $(stat_value "${proxy_log}" s2c reordered) == 0 ]] || fail "baseline reordered packets"
+
+# Loss: QUIC retransmission must recover from both-direction datagram loss.
+# The rate is deliberately small (4% c2s / 5% s2c): above the quiche example's
+# 5s idle-timeout handshake stall threshold lies the harsh-loss repro below.
+# We assert proxy drop counters, not quiche's `lost=` counter, because the
+# lost counter does not increment for short flows whose retransmissions
+# deliver before loss detection declares a packet lost. We require >= 1 drop
+# so the assertion is robust to low-packet-count seeds across the soak while
+# still proving impairment fired.
+run_scenario loss --c2s-loss 4 --s2c-loss 5
+(( $(total drop_loss) >= 1 )) || fail "loss scenario dropped no datagrams at all (proxy stats show impairment did not fire)"
+# Informational only: print quiche's own lost counters without asserting them,
+# because they are 0 for short recovered flows per the comment above.
+client_lost=$(rg -o 'lost=[0-9]+' "${client_log}" -N | tail -1 2>/dev/null | sed -E 's/lost=//')
+server_lost=$(rg -o 'lost=[0-9]+' "${server_log}" -N | tail -1 2>/dev/null | sed -E 's/lost=//')
+print "   quiche lost: client=${client_lost:-missing} server=${server_lost:-missing}"
+
+# Duplication: QUIC tolerates duplicate datagrams by design. >= 1 fire across
+# both directions is enough to prove the impairment fired; seed/iteration pairs
+# with very low UDP-packet counts will sometimes suppress the dup decision.
+run_scenario duplication --c2s-dup 10 --s2c-dup 10
+(( $(total dup) >= 1 )) || fail "duplication scenario fired no dups at all (proxy stats show impairment did not fire)"
+
+# Delay, jitter, and reordering: every datagram is held. >= 1 reorder event
+# across either direction proves the reorder impairment fired; both-directions
+# is demonstrable at the stable seed/iteration profile but is not robust to
+# the short flow of a low-traffic seed.
+run_scenario reorder \
+    --c2s-delay 15 --c2s-jitter 25 --c2s-reorder 20 --c2s-reorder-ms 40 \
+    --s2c-delay 15 --s2c-jitter 25 --s2c-reorder 20 --s2c-reorder-ms 40
+(( $(total delayed) > 0 )) || fail "reorder scenario delayed nothing"
+(( $(total reordered) >= 1 )) || \
+    fail "reorder scenario did not reorder any packets in either direction"
+
+# MTU filter: normal quiche datagrams fit the configured 1350-byte ceiling, so
+# the real HTTP/3 exchanges must pass. Afterward, a 1400-byte UDP sentinel is
+# injected and must be rejected. This deterministically verifies MTU policy
+# and accounting; a 1200-byte live-traffic black hole is kept out of the gate
+# because the stock example's fixed 5s idle timeout makes recovery flaky.
+mtu_probe_bytes=1400
+run_scenario mtu-filter --mtu 1350
+mtu_probe_bytes=0
+(( $(total drop_mtu) >= 1 )) || fail "mtu scenario dropped no oversized datagram"
+
+# Combined compound impairments were removed from the gated set because any
+# impairment that drops or delays the 1-RTT flight inside the quiche example's
+# 5s idle window can stall the handshake non-deterministically across OS
+# scheduling jitter; the individual scenarios above already prove each
+# impairment class in isolation. A combined "harsh-loss" reproducer below
+# documents the boundary failure mode (opt-in).
+
+if (( tolerate_stalls == 0 )); then
+    print "HTTP/3 chaos phase passed: all conservative scenarios recovered over QUIC (seed=${seed}, iterations=${iterations})"
+else
+    print "HTTP/3 chaos diagnostic completed (not a recovery gate): iterations=${total_iterations} completed=${total_completed} stalled=${total_stalls}; structural proxy invariants remained gated"
+fi
+
+# --- opt-in harsh-loss reproducer --------------------------------------------
+# Emergency-brake profile that motivated the conservative loss rates above.
+# The stock quiche http3 examples hard-code max_idle_timeout=5000ms; with
+# c2s=8% / s2c=10% two-sided loss on a ~10-datagram loopback handshake,
+# seed=7 reliably stalls an iteration when the proxy drops a handshake-
+# critical flight that the QUIC loss-detection timer cannot recover inside
+# the 5s idle window. This is a quiche-example limitation, NOT a GhostHTTP3
+# framework regression: the proxy is correct (drops are counted, queues are
+# bounded, no peer loss, no leak), and the framework survives.
+#
+# Because the stalling iteration is timing-sensitive (OS scheduling jitter
+# affects when the lossy flight arrives), this reproducer does NOT assert a
+# hard pass/fail. It documents the failure mode and asks only for these
+# invariant policies to hold:
+#   * no proxy queue overflow (drop_full == 0)
+#   * no client address loss (drop_nopeer == 0)
+#   * the proxy and server processes terminate within their max-duration /
+#     client_timeout bounds (no zombie, no leak)
+#   * at least one iteration reaches the 5s idle timeout path (i.e. the
+#     impairment fired at loss rates near the stall threshold)
+if [[ ${harsh} == 1 ]]; then
+    print "== scenario harsh-loss (opt-in reproducer; expected to stall >= 1 iteration)"
+    saved_iterations=${iterations}
+    saved_tolerate=${scenario_tolerate_stall}
+    iterations=3
+    scenario_tolerate_stall=1
+    run_scenario harsh-loss --c2s-loss 8 --s2c-loss 10
+    scenario_tolerate_stall=${saved_tolerate}
+    iterations=${saved_iterations}
+
+    # The mandatory invariants hold even when iterations stall.
+    local dir
+    for dir in c2s s2c; do
+        [[ $(stat_value "${proxy_log}" ${dir} drop_full) == 0 ]] || \
+            fail "harsh-loss proxy queue overflowed (${dir})"
+        [[ $(stat_value "${proxy_log}" ${dir} drop_nopeer) == 0 ]] || \
+            fail "harsh-loss proxy lost client address (${dir})"
+        [[ $(stat_value "${proxy_log}" ${dir} send_error) == 0 ]] || \
+            fail "harsh-loss proxy failed to forward a datagram (${dir})"
+        [[ $(stat_value "${proxy_log}" ${dir} queued) == 0 ]] || \
+            fail "harsh-loss proxy stopped with queued datagrams (${dir})"
+    done
+    (( $(total drop_loss) >= 1 )) || \
+        fail "harsh-loss reproducer did not actually drop any datagram (impairment did not fire)"
+
+    print "harsh-loss reproducer: ${completed}/3 iterations recovered, ${stalled}/3 stalled"
+    print "harsh-loss reproducer: documented expected behavior (see comment above)"
+fi
diff --git a/macOS/GhostHTTP3/scripts/test-framework.sh b/macOS/GhostHTTP3/scripts/test-framework.sh
new file mode 100755
index 0000000..1e0e285
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/test-framework.sh
@@ -0,0 +1,43 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+framework_dir=${build_dir}/artifacts/GhostHTTP3.framework
+test_binary=${build_dir}/tests/ghost-http3-smoke
+swift_test_binary=${build_dir}/tests/ghost-http3-swift-smoke
+
+if [[ ! -d ${framework_dir} ]]; then
+    print -u2 "error: GhostHTTP3.framework is missing; run build-framework.sh first"
+    exit 1
+fi
+
+mkdir -p "${test_binary:h}"
+
+xcrun clang \
+    -F"${build_dir}/artifacts" \
+    -framework GhostHTTP3 \
+    -Wl,-rpath,@executable_path/../artifacts \
+    "${project_dir}/Tests/smoke.c" \
+    -o "${test_binary}"
+
+"${test_binary}"
+
+xcrun swiftc \
+    -F"${build_dir}/artifacts" \
+    -framework GhostHTTP3 \
+    -Xlinker -rpath \
+    -Xlinker @executable_path/../artifacts \
+    "${project_dir}/Tests/smoke.swift" \
+    -o "${swift_test_binary}"
+
+"${swift_test_binary}"
+
+file "${framework_dir}/GhostHTTP3"
+[[ $(lipo -archs "${framework_dir}/GhostHTTP3") == arm64 ]]
+otool -D "${framework_dir}/GhostHTTP3"
+otool -L "${test_binary}" | \
+    rg -q '@rpath/GhostHTTP3\.framework/Versions/A/GhostHTTP3'
+codesign --verify --strict "${framework_dir}"
diff --git a/macOS/GhostHTTP3/scripts/test-http3.sh b/macOS/GhostHTTP3/scripts/test-http3.sh
new file mode 100755
index 0000000..a57922e
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/test-http3.sh
@@ -0,0 +1,75 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+framework_dir=${build_dir}/artifacts/GhostHTTP3.framework
+examples_dir=${build_dir}/upstream/quiche/quiche/examples
+test_dir=${build_dir}/tests
+port=${GHOST_HTTP3_TEST_PORT:-$((30000 + ($$ % 20000)))}
+
+if [[ ! -f /opt/homebrew/include/ev.h || ! -f /opt/homebrew/include/uthash.h ]]; then
+    print -u2 "error: HTTP/3 integration test requires: brew install libev uthash"
+    exit 1
+fi
+
+mkdir -p "${test_dir}"
+
+common_flags=(
+    -O2
+    -I"${framework_dir}/Headers"
+    -I/opt/homebrew/include
+    -L/opt/homebrew/lib
+    -F"${build_dir}/artifacts"
+    -framework GhostHTTP3
+    -Wl,-rpath,@executable_path/../artifacts
+    -lev
+)
+
+xcrun clang "${common_flags[@]}" \
+    "${examples_dir}/http3-server.c" \
+    -o "${test_dir}/http3-server"
+
+xcrun clang "${common_flags[@]}" \
+    "${examples_dir}/http3-client.c" \
+    -o "${test_dir}/http3-client"
+
+server_log=${test_dir}/http3-server.log
+client_log=${test_dir}/http3-client.log
+
+(
+    cd "${examples_dir}"
+    exec "${test_dir}/http3-server" 127.0.0.1 "${port}"
+) >"${server_log}" 2>&1 &
+server_pid=$!
+
+cleanup() {
+    kill "${server_pid}" >/dev/null 2>&1 || true
+    wait "${server_pid}" >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+trap 'cleanup; exit 130' INT
+trap 'cleanup; exit 143' TERM HUP
+
+sleep 0.2
+kill -0 "${server_pid}" 2>/dev/null || {
+    print -u2 "error: HTTP/3 server failed to start on 127.0.0.1:${port}"
+    tail -30 "${server_log}" >&2
+    exit 1
+}
+
+(
+    cd "${examples_dir}"
+    exec "${test_dir}/http3-client" 127.0.0.1 "${port}"
+) >"${client_log}" 2>&1
+
+rg -q "connection established: h3" "${client_log}"
+rg -q "got HTTP header: :status=200" "${client_log}"
+rg -q "got HTTP header: content-length=5" "${client_log}"
+rg -q "^byez" "${client_log}"
+rg -q 'proto=Ok\("h3"\)' "${server_log}"
+
+print "HTTP/3 interoperability passed: GET / -> 200, 5-byte body, ALPN h3"
+rg "connection established: h3|got HTTP header: :status|got HTTP header: content-length|^byez" "${client_log}"
diff --git a/macOS/GhostHTTP3/scripts/test-stress.sh b/macOS/GhostHTTP3/scripts/test-stress.sh
new file mode 100755
index 0000000..dd72514
--- /dev/null
+++ b/macOS/GhostHTTP3/scripts/test-stress.sh
@@ -0,0 +1,48 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+script_dir=${0:A:h}
+project_dir=${script_dir:h}
+build_dir=${GHOST_HTTP3_BUILD_DIR:-${project_dir}/.build}
+framework_dir=${build_dir}/artifacts/GhostHTTP3.framework
+examples_dir=${build_dir}/upstream/quiche/quiche/examples
+test_dir=${build_dir}/tests
+test_binary=${test_dir}/ghost-http3-stress
+
+if [[ ! -d ${framework_dir} ]]; then
+    print -u2 "error: GhostHTTP3.framework is missing; run build-framework.sh first"
+    exit 1
+fi
+
+if [[ ! -f ${examples_dir}/cert.crt || ! -f ${examples_dir}/cert.key ]]; then
+    print -u2 "error: quiche example TLS identity is missing; run build-framework.sh first"
+    exit 1
+fi
+
+mkdir -p "${test_dir}"
+
+sanitize_flags=()
+if [[ ${GHOST_HTTP3_TEST_SANITIZERS:-0} == 1 ]]; then
+    sanitize_flags=(
+        -O1
+        -fno-omit-frame-pointer
+        -fsanitize=address,undefined
+    )
+fi
+
+xcrun clang \
+    -std=c17 \
+    -O2 \
+    -Wall \
+    -Wextra \
+    -Werror \
+    -Wno-unused-parameter \
+    "${sanitize_flags[@]}" \
+    -F"${build_dir}/artifacts" \
+    -framework GhostHTTP3 \
+    -Wl,-rpath,@executable_path/../artifacts \
+    "${project_dir}/Tests/stress.c" \
+    -o "${test_binary}"
+
+"${test_binary}" "${examples_dir}/cert.crt" "${examples_dir}/cert.key"
diff --git a/macOS/GhostTools/Package.swift b/macOS/GhostTools/Package.swift
index e563951..ae5013a 100644
--- a/macOS/GhostTools/Package.swift
+++ b/macOS/GhostTools/Package.swift
@@ -7,7 +7,8 @@ let package = Package(
         .macOS(.v15)
     ],
     products: [
-        .executable(name: "GhostTools", targets: ["GhostTools"])
+        .executable(name: "GhostTools", targets: ["GhostTools"]),
+        .executable(name: "ghostbox", targets: ["ghostbox"])
     ],
     dependencies: [
         .package(path: "../../Packages/GhostHTTP")
@@ -24,16 +25,24 @@ let package = Package(
                 "CPty",
                 .product(name: "GhostHTTP", package: "GhostHTTP"),
             ],
-            exclude: ["Resources/Info.plist", "Resources/Info.template.plist", "Resources/entitlements.plist"],
+            exclude: ["Resources/Info.template.plist", "Resources/entitlements.plist"],
             linkerSettings: [
                 .unsafeFlags(["-Xlinker", "-sectcreate", "-Xlinker", "__TEXT", "-Xlinker", "__info_plist", "-Xlinker", "../../build/generated-plists/GhostTools-Info.plist"], .when(configuration: .release))
             ]
         ),
+        .executableTarget(
+            name: "ghostbox",
+            dependencies: []
+        ),
         .testTarget(
             name: "GhostToolsTests",
             dependencies: [
                 "GhostTools",
             ]
-        )
+        ),
+        .testTarget(
+            name: "GhostboxTests",
+            dependencies: ["ghostbox"]
+        ),
     ]
 )
diff --git a/macOS/GhostTools/README.txt b/macOS/GhostTools/README.txt
index 3064fc0..b07a74a 100644
--- a/macOS/GhostTools/README.txt
+++ b/macOS/GhostTools/README.txt
@@ -12,21 +12,98 @@ enabling enhanced host-guest integration:
 - Pointer and keyboard input injection
 - Screenshot capture with element overlays
 - Log streaming to host
+- Direct Apple Containerization diagnostics
 
 Installation
 ------------
 
-GhostTools is automatically installed to /Applications in the guest VM
-when the GhostTools DMG is attached. It auto-updates when a newer version
-is available from the host.
+GhostTools is automatically installed to /Applications in the guest VM when
+the GhostTools DMG is attached. It auto-updates when a newer version is
+available from the host.
 
 To install manually:
 
    sudo cp /Volumes/GhostTools/GhostTools.app /Applications/
 
-GhostTools requires Accessibility permission in the guest to enable
-pointer, keyboard, and UI automation features. Grant this in
-System Settings > Privacy & Security > Accessibility.
+The direct Containerization CLI can be run from the mounted DMG:
+
+   /Volumes/GhostTools/bin/ghostbox --help
+
+The Docker-like helper is packaged beside it:
+
+   /Volumes/GhostTools/bin/ghostbox-docker --help
+
+The Compose-compatible helper manages multi-container projects through that
+Docker-like helper:
+
+   /Volumes/GhostTools/bin/ghostbox-docker-compose config
+   /Volumes/GhostTools/bin/ghostbox-docker-compose up -d
+   /Volumes/GhostTools/bin/ghostbox-docker-compose ps
+   /Volumes/GhostTools/bin/ghostbox-docker-compose logs -f
+   /Volumes/GhostTools/bin/ghostbox-docker-compose down
+
+It discovers compose.yaml, compose.yml, docker-compose.yaml, or
+docker-compose.yml and supports image-based services, commands, entrypoints,
+environment files and values, bind mounts, loopback TCP ports, dependencies,
+and common process settings. Builds, named volumes, custom networks,
+service-name DNS, health checks, and scaling are not implemented. The helper
+uses the system /usr/bin/ruby YAML parser.
+
+Ghostbox Direct API
+-------------------
+
+`ghostbox` exposes direct, source-shaped Apple Containerization operations. It
+does not provide compatibility fallback commands. `ghostbox-docker` separately
+composes these operations into Docker-like `build`, `pull`, and foreground
+`run --rm` workflows. Currently implemented direct operations are listed by:
+
+   ghostbox --help
+
+Examples:
+
+   ghostbox cn:kernel:default
+   ghostbox cn:dns:default-nameservers
+   ghostbox cn:dns:create dev --nameserver 1.1.1.1
+   ghostbox cn:dns:resolv-conf @dns/dev
+   ghostbox cn:process-config:default-path
+   ghostbox cn:container:default-masked-paths
+
+Guest-backed process I/O uses explicit resources and remains independent from
+container lifecycle operations:
+
+   ghostbox cn:reader-stream:create job-input
+   ghostbox cn:writer:create job-output
+   ghostbox cn:process-config:create job /bin/sh \
+       --stdin @reader-stream/job-input --stdout @writer/job-output
+   producer | ghostbox cn:reader-stream:attach @reader-stream/job-input &
+   ghostbox cn:writer:attach @writer/job-output | consumer &
+
+Start attachments before the process to avoid filling their bounded transport
+buffers. Close a writer after the corresponding process wait completes so its
+attachment emits EOF. For an interactive PTY, create a terminal, pass it to
+`cn:process-config:set-terminal-io`, and keep the following attachment in the
+foreground while the lifecycle controller waits and then closes the terminal:
+
+   ghostbox cn:terminal:attach @terminal/NAME --resize-target @container/NAME
+
+Terminal attach requires a real TTY and forwards raw input, output, and
+window-size changes. A lifecycle controller in another process can block on
+`ghostbox cn:terminal:wait-attached @terminal/NAME` before starting the process.
+
+The outer Mac must be Apple silicon. In GhostVM, open Edit Settings for this VM,
+select NAT (Shared), and enable Host-backed Containers before starting the VM.
+
+Enabling the bridge grants any process in the guest permission to request
+host-side Containerization operations. Unsupported direct operations fail
+explicitly; they are never translated to a legacy one-shot request.
+
+`cn:kernel:default` is a GhostVM host extension backed by Apple container's
+configured default Linux ARM kernel. See `examples/ghostbox` for scripts that
+compose it with the direct manager, container, process, and I/O APIs.
+
+GhostTools requires Accessibility permission in the guest to enable pointer,
+keyboard, and UI automation features. Grant this in System Settings > Privacy &
+Security > Accessibility.
 
 Requirements
 ------------
diff --git a/macOS/GhostTools/Sources/GhostTools/Server/Router.swift b/macOS/GhostTools/Sources/GhostTools/Server/Router.swift
index 78ebe15..e431d04 100644
--- a/macOS/GhostTools/Sources/GhostTools/Server/Router.swift
+++ b/macOS/GhostTools/Sources/GhostTools/Server/Router.swift
@@ -60,7 +60,7 @@ final class Router: @unchecked Sendable {
             return handleFrontmostApp(request)
         } else if path == "/api/v1/apps" || path.hasPrefix("/api/v1/apps/") {
             return handleApps(request: request, body: body)
-        } else if path == "/api/v1/fs" || path == "/api/v1/fs/mkdir" || path == "/api/v1/fs/delete" || path == "/api/v1/fs/move" {
+        } else if path == "/api/v1/fs" || path.hasPrefix("/api/v1/fs/") {
             return handleFS(request: request, body: body)
         } else if path == "/api/v1/exec" {
             return handleExec(request: request, body: body)
@@ -553,7 +553,67 @@ final class Router: @unchecked Sendable {
             let queryPath = parseQuery(request.path, key: "path") ?? NSHomeDirectory()
             return listDirectory(at: queryPath)
         }
-        guard request.method == .POST else {
+
+        if path == "/api/v1/fs/metadata" && request.method == .GET {
+            guard let queryPath = parseQuery(request.path, key: "path") else {
+                return HTTPResponse.error(.badRequest, message: "Path required")
+            }
+            return metadata(at: queryPath)
+        }
+
+        if path == "/api/v1/fs/list" && request.method == .GET {
+            guard let queryPath = parseQuery(request.path, key: "path") else {
+                return HTTPResponse.error(.badRequest, message: "Path required")
+            }
+            return listDirectoryMetadata(at: queryPath)
+        }
+
+        if path == "/api/v1/fs/read" && request.method == .GET {
+            guard
+                let queryPath = parseQuery(request.path, key: "path"),
+                let offsetValue = parseQuery(request.path, key: "offset"),
+                let offset = UInt64(offsetValue),
+                let lengthValue = parseQuery(request.path, key: "length"),
+                let length = Int(lengthValue),
+                length >= 0,
+                length <= 1024 * 1024
+            else {
+                return HTTPResponse.error(.badRequest, message: "Valid path, offset, and length are required")
+            }
+            return readFile(at: queryPath, offset: offset, length: length)
+        }
+
+        if path == "/api/v1/fs/readlink" && request.method == .GET {
+            guard let queryPath = parseQuery(request.path, key: "path") else {
+                return HTTPResponse.error(.badRequest, message: "Path required")
+            }
+            return readSymbolicLink(at: queryPath)
+        }
+
+        if path == "/api/v1/fs/write" && request.method == .PATCH {
+            guard
+                let queryPath = parseQuery(request.path, key: "path"),
+                let offsetValue = parseQuery(request.path, key: "offset"),
+                let offset = UInt64(offsetValue),
+                offset <= UInt64(Int64.max)
+            else {
+                return HTTPResponse.error(.badRequest, message: "Valid path and offset are required")
+            }
+            do {
+                return writeFile(at: queryPath, offset: offset, data: try body.readAll(maxSize: 1024 * 1024))
+            } catch {
+                return HTTPResponse.error(.badRequest, message: "Invalid write body: \(error.localizedDescription)")
+            }
+        }
+
+        if path == "/api/v1/fs/remove" && request.method == .DELETE {
+            guard let queryPath = parseQuery(request.path, key: "path") else {
+                return HTTPResponse.error(.badRequest, message: "Path required")
+            }
+            return removeFileSystemItem(at: queryPath)
+        }
+
+        guard request.method == .POST || request.method == .PATCH else {
             return HTTPResponse.error(.methodNotAllowed, message: "Method not allowed")
         }
 
@@ -562,6 +622,31 @@ final class Router: @unchecked Sendable {
             return HTTPResponse.error(.badRequest, message: "Failed to read body: \(error)")
         }
 
+        if path == "/api/v1/fs/create" && request.method == .POST {
+            guard let payload = try? JSONDecoder().decode(FSCreateRequest.self, from: raw) else {
+                return HTTPResponse.error(.badRequest, message: "Invalid create request")
+            }
+            return createFileSystemItem(payload)
+        }
+        if path == "/api/v1/fs/symlink" && request.method == .POST {
+            guard let payload = try? JSONDecoder().decode(FSSymbolicLinkRequest.self, from: raw) else {
+                return HTTPResponse.error(.badRequest, message: "Invalid symbolic-link request")
+            }
+            return createSymbolicLink(payload)
+        }
+        if path == "/api/v1/fs/attributes" && request.method == .PATCH {
+            guard let payload = try? JSONDecoder().decode(FSSetAttributesRequest.self, from: raw) else {
+                return HTTPResponse.error(.badRequest, message: "Invalid attribute request")
+            }
+            return setFileAttributes(payload)
+        }
+        if path == "/api/v1/fs/rename" && request.method == .POST {
+            guard let payload = try? JSONDecoder().decode(FSRenameRequest.self, from: raw) else {
+                return HTTPResponse.error(.badRequest, message: "Invalid rename request")
+            }
+            return renameFileSystemItem(payload)
+        }
+
         if path == "/api/v1/fs/mkdir" {
             guard let payload = try? JSONDecoder().decode(FSPathRequest.self, from: raw) else {
                 return HTTPResponse.error(.badRequest, message: "Invalid JSON - need path")
@@ -625,6 +710,262 @@ final class Router: @unchecked Sendable {
         }
     }
 
+    private func metadata(at path: String) -> HTTPResponse {
+        do {
+            return HTTPResponse.json(try JSONEncoder().encode(try fileMetadata(at: path)))
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func listDirectoryMetadata(at path: String) -> HTTPResponse {
+        do {
+            let names = try FileManager.default.contentsOfDirectory(atPath: path)
+            let entries = try names.sorted().map { name in
+                try fileMetadata(at: (path as NSString).appendingPathComponent(name))
+            }
+            return HTTPResponse.json(try JSONEncoder().encode(GuestDirectoryMetadata(path: path, entries: entries)))
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func readFile(at path: String, offset: UInt64, length: Int) -> HTTPResponse {
+        do {
+            let metadata = try fileMetadata(at: path)
+            guard metadata.type == .file else {
+                return HTTPResponse.error(.badRequest, message: "Path is not a regular file")
+            }
+            let handle = try FileHandle(forReadingFrom: URL(fileURLWithPath: path))
+            defer { try? handle.close() }
+            try handle.seek(toOffset: offset)
+            let data = try handle.read(upToCount: length) ?? Data()
+            return HTTPResponse(
+                status: .ok,
+                headers: ["Content-Type": "application/octet-stream"],
+                body: .bytes(data)
+            )
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func readSymbolicLink(at path: String) -> HTTPResponse {
+        do {
+            let target = try FileManager.default.destinationOfSymbolicLink(atPath: path)
+            return HTTPResponse(
+                status: .ok,
+                headers: ["Content-Type": "text/plain; charset=utf-8"],
+                body: .bytes(Data(target.utf8))
+            )
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func createFileSystemItem(_ request: FSCreateRequest) -> HTTPResponse {
+        do {
+            let permissions = mode_t(request.mode & 0o7777)
+            switch request.type {
+            case .file:
+                let descriptor = Darwin.open(request.path, O_WRONLY | O_CREAT | O_EXCL, permissions)
+                guard descriptor >= 0 else { throw currentPOSIXError() }
+                guard Darwin.close(descriptor) == 0 else { throw currentPOSIXError() }
+            case .directory:
+                guard Darwin.mkdir(request.path, permissions) == 0 else { throw currentPOSIXError() }
+            }
+            return filesystemMetadataResponse(at: request.path)
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func createSymbolicLink(_ request: FSSymbolicLinkRequest) -> HTTPResponse {
+        guard !request.destination.contains("\0") else {
+            return HTTPResponse.error(.badRequest, message: "Invalid symbolic-link destination")
+        }
+        do {
+            guard Darwin.symlink(request.destination, request.path) == 0 else { throw currentPOSIXError() }
+            return filesystemMetadataResponse(at: request.path)
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func writeFile(at path: String, offset: UInt64, data: Data) -> HTTPResponse {
+        do {
+            var info = stat()
+            guard Darwin.lstat(path, &info) == 0 else { throw currentPOSIXError() }
+            guard info.st_mode & S_IFMT == S_IFREG else { throw POSIXError(.EINVAL) }
+            let descriptor = Darwin.open(path, O_WRONLY)
+            guard descriptor >= 0 else { throw currentPOSIXError() }
+            defer { Darwin.close(descriptor) }
+            var written = 0
+            try data.withUnsafeBytes { bytes in
+                while written < bytes.count {
+                    let result = Darwin.pwrite(
+                        descriptor,
+                        bytes.baseAddress?.advanced(by: written),
+                        bytes.count - written,
+                        off_t(offset) + off_t(written)
+                    )
+                    if result < 0, errno == EINTR { continue }
+                    guard result > 0 else { throw currentPOSIXError() }
+                    written += result
+                }
+            }
+            return filesystemMetadataResponse(at: path)
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func setFileAttributes(_ request: FSSetAttributesRequest) -> HTTPResponse {
+        do {
+            if let size = request.attributes.size {
+                guard size <= UInt64(Int64.max) else { throw POSIXError(.EOVERFLOW) }
+                guard Darwin.truncate(request.path, off_t(size)) == 0 else { throw currentPOSIXError() }
+            }
+            if let mode = request.attributes.mode {
+                guard Darwin.chmod(request.path, mode_t(mode & 0o7777)) == 0 else { throw currentPOSIXError() }
+            }
+            if request.attributes.modifiedSeconds != nil || request.attributes.accessedSeconds != nil {
+                func requestedTime(seconds: Int64?, nanoseconds: Int32?) -> timespec {
+                    guard let seconds else { return timespec(tv_sec: 0, tv_nsec: Int(UTIME_OMIT)) }
+                    return timespec(tv_sec: Int(seconds), tv_nsec: Int(nanoseconds ?? 0))
+                }
+                let times = [
+                    requestedTime(
+                        seconds: request.attributes.accessedSeconds,
+                        nanoseconds: request.attributes.accessedNanoseconds
+                    ),
+                    requestedTime(
+                        seconds: request.attributes.modifiedSeconds,
+                        nanoseconds: request.attributes.modifiedNanoseconds
+                    ),
+                ]
+                let result = times.withUnsafeBufferPointer {
+                    Darwin.utimensat(AT_FDCWD, request.path, $0.baseAddress, 0)
+                }
+                guard result == 0 else { throw currentPOSIXError() }
+            }
+            return filesystemMetadataResponse(at: request.path)
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func removeFileSystemItem(at path: String) -> HTTPResponse {
+        do {
+            var info = stat()
+            guard Darwin.lstat(path, &info) == 0 else { throw currentPOSIXError() }
+            let result = info.st_mode & S_IFMT == S_IFDIR ? Darwin.rmdir(path) : Darwin.unlink(path)
+            guard result == 0 else { throw currentPOSIXError() }
+            return HTTPResponse(status: .noContent)
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func renameFileSystemItem(_ request: FSRenameRequest) -> HTTPResponse {
+        do {
+            guard Darwin.rename(request.path, request.destinationPath) == 0 else { throw currentPOSIXError() }
+            return filesystemMetadataResponse(at: request.destinationPath)
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func filesystemMetadataResponse(at path: String) -> HTTPResponse {
+        do {
+            return HTTPResponse.json(try JSONEncoder().encode(try fileMetadata(at: path)))
+        } catch {
+            return filesystemError(error)
+        }
+    }
+
+    private func filesystemError(_ error: Error) -> HTTPResponse {
+        let posix = normalizedPOSIXError(error)
+        let status: HTTPStatus
+        switch posix?.code {
+        case .ENOENT: status = .notFound
+        case .EACCES, .EPERM: status = .forbidden
+        case .EEXIST, .ENOTEMPTY: status = .conflict
+        case .EINVAL, .EISDIR, .ENOTDIR: status = .badRequest
+        default: status = .internalServerError
+        }
+        let payload = GuestFilesystemErrorResponse(
+            error: error.localizedDescription,
+            errno: posix?.code.rawValue
+        )
+        return HTTPResponse(
+            status: status,
+            headers: ["Content-Type": "application/json"],
+            body: .bytes((try? JSONEncoder().encode(payload)) ?? Data())
+        )
+    }
+
+    private func currentPOSIXError() -> POSIXError {
+        POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+    }
+
+    private func normalizedPOSIXError(_ error: Error) -> POSIXError? {
+        if let error = error as? POSIXError { return error }
+        let nsError = error as NSError
+        if nsError.domain == NSPOSIXErrorDomain,
+           let code = POSIXErrorCode(rawValue: Int32(nsError.code)) {
+            return POSIXError(code)
+        }
+        if let underlying = nsError.userInfo[NSUnderlyingErrorKey] as? Error,
+           let error = normalizedPOSIXError(underlying) {
+            return error
+        }
+        let code: POSIXErrorCode?
+        switch CocoaError.Code(rawValue: nsError.code) {
+        case .fileNoSuchFile: code = .ENOENT
+        case .fileReadNoPermission, .fileWriteNoPermission: code = .EACCES
+        case .fileWriteFileExists: code = .EEXIST
+        case .fileWriteOutOfSpace: code = .ENOSPC
+        default: code = nil
+        }
+        return code.map { POSIXError($0) }
+    }
+
+    private func fileMetadata(at path: String) throws -> GuestFileMetadata {
+        var info = stat()
+        guard Darwin.lstat(path, &info) == 0 else {
+            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+        }
+
+        let type: GuestFileType
+        switch info.st_mode & S_IFMT {
+        case S_IFREG: type = .file
+        case S_IFDIR: type = .directory
+        case S_IFLNK: type = .symbolicLink
+        default: type = .other
+        }
+
+        return GuestFileMetadata(
+            name: URL(fileURLWithPath: path).lastPathComponent,
+            type: type,
+            size: UInt64(max(0, info.st_size)),
+            mode: UInt32(info.st_mode),
+            uid: info.st_uid,
+            gid: info.st_gid,
+            inode: info.st_ino,
+            device: UInt64(info.st_dev),
+            linkCount: UInt32(info.st_nlink),
+            modifiedSeconds: info.st_mtimespec.tv_sec,
+            modifiedNanoseconds: Int32(info.st_mtimespec.tv_nsec),
+            accessedSeconds: info.st_atimespec.tv_sec,
+            accessedNanoseconds: Int32(info.st_atimespec.tv_nsec),
+            changedSeconds: info.st_ctimespec.tv_sec,
+            changedNanoseconds: Int32(info.st_ctimespec.tv_nsec),
+            birthSeconds: info.st_birthtimespec.tv_sec,
+            birthNanoseconds: Int32(info.st_birthtimespec.tv_nsec)
+        )
+    }
+
     // MARK: - Exec
 
     private struct ExecRequest: Codable {
@@ -795,6 +1136,46 @@ struct FSMoveRequest: Codable {
     let to: String
 }
 
+enum FSCreateType: String, Codable {
+    case file
+    case directory
+}
+
+struct FSCreateRequest: Codable {
+    let path: String
+    let type: FSCreateType
+    let mode: UInt32
+}
+
+struct FSSymbolicLinkRequest: Codable {
+    let path: String
+    let destination: String
+}
+
+struct FSFileAttributes: Codable {
+    let mode: UInt32?
+    let size: UInt64?
+    let modifiedSeconds: Int64?
+    let modifiedNanoseconds: Int32?
+    let accessedSeconds: Int64?
+    let accessedNanoseconds: Int32?
+}
+
+struct FSSetAttributesRequest: Codable {
+    let path: String
+    let attributes: FSFileAttributes
+}
+
+struct FSRenameRequest: Codable {
+    let path: String
+    let destinationPath: String
+}
+
+struct GuestFilesystemErrorResponse: Codable {
+    let error: String
+    let errno: Int32?
+}
+
 // MARK: - Internal helpers
 
 /// Tracks paths per batch ID so Finder reveal happens once when the last
@@ -825,3 +1206,35 @@ final class RouterBatchTracker: @unchecked Sendable {
 final class LaunchResult: @unchecked Sendable {
     var success: Bool = false
 }
+
+enum GuestFileType: String, Codable {
+    case file
+    case directory
+    case symbolicLink
+    case other
+}
+
+struct GuestFileMetadata: Codable {
+    let name: String
+    let type: GuestFileType
+    let size: UInt64
+    let mode: UInt32
+    let uid: UInt32
+    let gid: UInt32
+    let inode: UInt64
+    let device: UInt64
+    let linkCount: UInt32
+    let modifiedSeconds: Int
+    let modifiedNanoseconds: Int32
+    let accessedSeconds: Int?
+    let accessedNanoseconds: Int32?
+    let changedSeconds: Int?
+    let changedNanoseconds: Int32?
+    let birthSeconds: Int?
+    let birthNanoseconds: Int32?
+}
+
+struct GuestDirectoryMetadata: Codable {
+    let path: String
+    let entries: [GuestFileMetadata]
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/Args.swift b/macOS/GhostTools/Sources/ghostbox/Args.swift
new file mode 100644
index 0000000..87c5114
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/Args.swift
@@ -0,0 +1,545 @@
+import Foundation
+
+enum ParsedAction {
+    case direct(GhostboxDirectInvocation)
+    case attach(GhostboxDirectInvocation, GhostboxIOStream)
+    case forward(container: String, ports: [PublishedPort])
+    case help([String])
+    case version
+}
+
+enum ParseError: LocalizedError, Equatable {
+    case invalidDirect(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidDirect(let reason):
+            return reason
+        }
+    }
+}
+
+struct CLIOptions {
+    let action: ParsedAction
+}
+
+struct GhostboxQualifiedCommand: Equatable, Sendable {
+    let namespace: String
+    let resource: String
+    let operation: String
+
+    var canonical: String { "\(namespace):\(resource):\(operation)" }
+
+    init?(_ token: String) {
+        let components = token.split(separator: ":", omittingEmptySubsequences: false)
+        guard components.count == 3 else { return nil }
+        switch components[0] {
+        case "cn", "containerization": namespace = "cn"
+        case "cr", "container": namespace = "cr"
+        default: return nil
+        }
+        let resource = String(components[1])
+        let operation = String(components[2])
+        guard isValidCommandSegment(resource), isValidCommandSegment(operation) else { return nil }
+        self.resource = resource
+        self.operation = operation
+    }
+}
+
+private func isValidCommandSegment(_ value: String) -> Bool {
+    guard let first = value.utf8.first, (97...122).contains(first) else { return false }
+    return value.utf8.allSatisfy { (97...122).contains($0) || (48...57).contains($0) || $0 == 45 }
+}
+
+func parseArguments(_ arguments: [String]) -> Result {
+    guard let command = arguments.first else {
+        return .success(CLIOptions(action: .help([])))
+    }
+    switch command {
+    case "--help", "-h":
+        guard arguments.count == 1 else {
+            return .failure(.invalidDirect("\(command) accepts no arguments"))
+        }
+        return .success(CLIOptions(action: .help([])))
+    case "help":
+        return .success(CLIOptions(action: .help(Array(arguments.dropFirst()))))
+    case "--version", "-v":
+        return .success(CLIOptions(action: .version))
+    default:
+        if ["cn:help", "containerization:help"].contains(command) {
+            guard arguments.count == 1 else {
+                return .failure(.invalidDirect("\(command) accepts no arguments"))
+            }
+            return .success(CLIOptions(action: .help(["cn"])))
+        }
+        if ["cr:help", "container:help"].contains(command) {
+            guard arguments.count == 1 else {
+                return .failure(.invalidDirect("\(command) accepts no arguments"))
+            }
+            return .success(CLIOptions(action: .help(["cr"])))
+        }
+        guard let qualified = GhostboxQualifiedCommand(command) else {
+            return .failure(.invalidDirect(
+                "unknown qualified command '\(command)'; expected NAMESPACE:RESOURCE:OPERATION"
+            ))
+        }
+        if qualified.operation == "help" {
+            guard arguments.count == 1 else {
+                return .failure(.invalidDirect("\(command) accepts no arguments"))
+            }
+            return .success(CLIOptions(action: .help([qualified.namespace, qualified.resource])))
+        }
+        if let helpIndex = arguments.firstIndex(where: { $0 == "--help" || $0 == "-h" }),
+           !arguments[.. [String]? {
+    guard command.namespace == "cn" else { return nil }
+    if ["reader-stream", "writer", "terminal"].contains(command.resource) {
+        if arguments.first?.hasPrefix("@") == true {
+            return [command.resource, arguments[0], command.operation] + arguments.dropFirst()
+        }
+        return [command.resource, command.operation] + arguments
+    }
+    if command.operation == "delete" || command.operation == "close" || command.operation == "forward" {
+        guard let receiver = arguments.first else { return [command.resource, command.operation] }
+        return [command.resource, receiver, command.operation] + arguments.dropFirst()
+    }
+    return [command.resource, command.operation] + arguments
+}
+
+private func parseVolumeArguments(_ arguments: [String]) -> Result {
+    guard arguments.count >= 2 else {
+        return .failure(.invalidDirect("volume requires an operation"))
+    }
+    if arguments[1] == "list" {
+        guard arguments.count == 2 else {
+            return .failure(.invalidDirect("volume list accepts no arguments"))
+        }
+        return directVolumeAction(.volumeList, parameters: [:])
+    }
+    if arguments[1] == "create" {
+        guard arguments.count >= 3, isValidReferenceComponent(arguments[2]) else {
+            return .failure(.invalidDirect("volume create requires a valid name"))
+        }
+        var parameters: [String: GhostboxJSONValue] = ["volume": .string(arguments[2])]
+        var index = 3
+        while index < arguments.count {
+            let (name, attached) = splitLongOption(arguments[index])
+            guard name == "--size" else {
+                return .failure(.invalidDirect("unknown option '\(name)' for volume create"))
+            }
+            guard parameters["size"] == nil else {
+                return .failure(.invalidDirect("option --size may be specified once"))
+            }
+            let value: String
+            if let attached {
+                value = attached
+            } else {
+                guard index + 1 < arguments.count else {
+                    return .failure(.invalidDirect("option --size requires a value"))
+                }
+                index += 1
+                value = arguments[index]
+            }
+            guard let size = UInt64(value) else {
+                return .failure(.invalidDirect("--size requires an unsigned integer byte count"))
+            }
+            parameters["size"] = .unsignedInteger(size)
+            index += 1
+        }
+        return directVolumeAction(.volumeCreate, parameters: parameters)
+    }
+
+    guard isValidReference(arguments[1], expectedKind: "volume"), arguments.count >= 3 else {
+        return .failure(.invalidDirect("expected volume create, volume list, or an @volume/NAME reference"))
+    }
+    let reference = arguments[1]
+    switch arguments[2] {
+    case "inspect":
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("volume inspect accepts no options"))
+        }
+        return directVolumeAction(.volumeInspect, parameters: ["volume": .string(reference)])
+    case "delete":
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("volume delete accepts no options"))
+        }
+        return directVolumeAction(.volumeDelete, parameters: ["volume": .string(reference)])
+    case "mount":
+        guard arguments.count >= 4, isValidReferenceComponent(arguments[3]) else {
+            return .failure(.invalidDirect("volume mount requires a valid mount name"))
+        }
+        var parameters: [String: GhostboxJSONValue] = [
+            "volume": .string(reference),
+            "mount": .string(arguments[3]),
+            "readOnly": .boolean(false),
+        ]
+        var suppliedOptions = Set()
+        var index = 4
+        while index < arguments.count {
+            let (name, attached) = splitLongOption(arguments[index])
+            guard name == "--destination" || name == "--read-only" else {
+                return .failure(.invalidDirect("unknown option '\(name)' for volume mount"))
+            }
+            guard suppliedOptions.insert(name).inserted else {
+                return .failure(.invalidDirect("option \(name) may be specified once"))
+            }
+            let parameter = name == "--destination" ? "destination" : "readOnly"
+            let value: String
+            if let attached {
+                value = attached
+            } else if name == "--read-only", index + 1 == arguments.count || arguments[index + 1].hasPrefix("--") {
+                value = "true"
+            } else {
+                guard index + 1 < arguments.count else {
+                    return .failure(.invalidDirect("option \(name) requires a value"))
+                }
+                index += 1
+                value = arguments[index]
+            }
+            if name == "--read-only" {
+                guard value == "true" || value == "false" else {
+                    return .failure(.invalidDirect("--read-only must be true or false"))
+                }
+                parameters[parameter] = .boolean(value == "true")
+            } else {
+                parameters[parameter] = .string(value)
+            }
+            index += 1
+        }
+        guard case .string(let destination) = parameters["destination"], isValidContainerMountPath(destination) else {
+            return .failure(.invalidDirect("--destination must be an absolute non-root container path without dot components"))
+        }
+        return directVolumeAction(.volumeMount, parameters: parameters)
+    default:
+        return .failure(.invalidDirect("unknown volume operation '\(arguments[2])'"))
+    }
+}
+
+private func directVolumeAction(
+    _ method: GhostboxDirectMethod,
+    parameters: [String: GhostboxJSONValue]
+) -> Result {
+    .success(CLIOptions(action: .direct(.init(method: method, parameters: parameters))))
+}
+
+private func splitLongOption(_ option: String) -> (String, String?) {
+    guard let separator = option.firstIndex(of: "=") else { return (option, nil) }
+    return (String(option[.. Result? {
+    guard arguments.count >= 3, arguments[1].hasPrefix("@") else { return nil }
+    let resource = arguments[0]
+    let operation = arguments[2]
+    let method: GhostboxDirectMethod
+    let referenceKind: String
+    let parameter: String
+    switch (resource, operation) {
+    case ("mount", "delete"):
+        method = .mountDelete
+        referenceKind = "mount"
+        parameter = "mount"
+    case ("dns", "delete"):
+        method = .dnsDelete
+        referenceKind = "dns"
+        parameter = "dns"
+    case ("process-config", "delete"):
+        method = .processConfigDelete
+        referenceKind = "process-config"
+        parameter = "processConfig"
+    case ("network", "delete"):
+        method = .networkDelete
+        referenceKind = "network"
+        parameter = "network"
+    case ("manager", "close"):
+        method = .managerClose
+        referenceKind = "manager"
+        parameter = "manager"
+    default:
+        return nil
+    }
+    guard arguments.count == 3 else {
+        return .failure(.invalidDirect("too many arguments for \(resource) \(operation)"))
+    }
+    guard isValidReference(arguments[1], expectedKind: referenceKind) else {
+        return .failure(.invalidDirect("expected @\(referenceKind)/NAME reference"))
+    }
+    return .success(CLIOptions(action: .direct(.init(
+        method: method,
+        parameters: [parameter: .string(arguments[1])]
+    ))))
+}
+
+private func parseGuestMountArguments(_ arguments: [String]) -> Result? {
+    guard arguments.count >= 2, arguments[1] == "guest-share" else { return nil }
+    guard arguments.count >= 3, isValidReferenceComponent(arguments[2]) else {
+        return .failure(.invalidDirect("mount guest-share requires a valid mount name"))
+    }
+    var parameters: [String: GhostboxJSONValue] = [
+        "mount": .string(arguments[2]),
+        "readOnly": .boolean(false),
+        "option": .array([]),
+        "runtimeOption": .array([]),
+    ]
+    var singularOptions = Set()
+    var index = 3
+    while index < arguments.count {
+        let option = arguments[index]
+        let name: String
+        let attached: String?
+        if let separator = option.firstIndex(of: "=") {
+            name = String(option[.. Result {
+    guard isValidReference(arguments[1], expectedKind: "container") else {
+        return .failure(.invalidDirect("container forward requires an @container/NAME reference"))
+    }
+    var ports: [PublishedPort] = []
+    var index = 3
+    while index < arguments.count {
+        let option = arguments[index]
+        let specification: String
+        if option == "-p" || option == "-P" || option == "--publish" {
+            guard index + 1 < arguments.count else {
+                return .failure(.invalidDirect("option \(option) requires a value"))
+            }
+            index += 1
+            specification = arguments[index]
+        } else if option.hasPrefix("--publish=") {
+            specification = String(option.dropFirst("--publish=".count))
+        } else {
+            return .failure(.invalidDirect("container forward accepts repeated -p, -P, or --publish options"))
+        }
+        do {
+            let port = try parsePublishedPort(specification).get()
+            guard !ports.contains(where: { $0.hostAddress == port.hostAddress && $0.hostPort == port.hostPort }) else {
+                return .failure(.invalidDirect("duplicate published port \(port.hostAddress):\(port.hostPort)"))
+            }
+            ports.append(port)
+        } catch let error {
+            return .failure(error)
+        }
+        index += 1
+    }
+    guard !ports.isEmpty else {
+        return .failure(.invalidDirect("container forward requires at least one -p mapping"))
+    }
+    return .success(CLIOptions(action: .forward(container: arguments[1], ports: ports)))
+}
+
+func isValidContainerMountPath(_ path: String) -> Bool {
+    let components = path.split(separator: "/", omittingEmptySubsequences: true)
+    return path.hasPrefix("/") && path != "/" && !path.contains("\0")
+        && !components.contains(where: { $0 == "." || $0 == ".." })
+}
+
+private func parseIOProxyArguments(_ arguments: [String]) -> Result {
+    guard arguments.count >= 2 else {
+        return .failure(.invalidDirect("resource '\(arguments[0])' requires an operation"))
+    }
+    let resource = arguments[0]
+    let referenceKind = resource
+    let isReference = arguments[1].hasPrefix("@")
+    let operationIndex = isReference ? 2 : 1
+    guard arguments.indices.contains(operationIndex) else {
+        return .failure(.invalidDirect("reference command for '\(resource)' requires an operation"))
+    }
+    let operation = arguments[operationIndex]
+
+    func invocation(_ method: GhostboxDirectMethod, _ parameters: [String: GhostboxJSONValue]) -> CLIOptions {
+        CLIOptions(action: .direct(.init(method: method, parameters: parameters)))
+    }
+
+    if !isReference, operation == "create" {
+        guard arguments.count >= 3 else {
+            return .failure(.invalidDirect("missing required positional name"))
+        }
+        let name = arguments[2]
+        guard isValidReferenceComponent(name) else {
+            return .failure(.invalidDirect("name must contain only letters, digits, '.', '_', or '-' and be at most 128 bytes"))
+        }
+        if resource == "terminal" {
+            var width: UInt16 = 80
+            var height: UInt16 = 24
+            for argument in arguments.dropFirst(3) {
+                if argument.hasPrefix("--width="), let value = UInt16(argument.dropFirst("--width=".count)), value > 0 {
+                    width = value
+                } else if argument.hasPrefix("--height="), let value = UInt16(argument.dropFirst("--height=".count)), value > 0 {
+                    height = value
+                } else {
+                    return .failure(.invalidDirect("terminal create accepts --width=N and --height=N"))
+                }
+            }
+            return .success(invocation(.terminalCreateProxy, [
+                "terminal": .string(name), "width": .unsignedInteger(UInt64(width)),
+                "height": .unsignedInteger(UInt64(height)),
+            ]))
+        }
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for \(resource) create"))
+        }
+        let method: GhostboxDirectMethod = resource == "reader-stream" ? .readerStreamCreateProxy : .writerCreateProxy
+        let parameter = resource == "reader-stream" ? "readerStream" : "writer"
+        return .success(invocation(method, [parameter: .string(name)]))
+    }
+
+    guard isReference, isValidReference(arguments[1], expectedKind: referenceKind) else {
+        return .failure(.invalidDirect("expected @\(referenceKind)/NAME reference and one operation"))
+    }
+    let reference = GhostboxJSONValue.string(arguments[1])
+    let parameter = resource == "reader-stream" ? "readerStream" : resource
+    switch (resource, operation) {
+    case ("reader-stream", "attach"):
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for reader-stream attach"))
+        }
+        return .success(CLIOptions(action: .attach(.init(
+            method: .readerStreamAttachProxy, parameters: [parameter: reference]
+        ), .input)))
+    case ("reader-stream", "close"):
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for reader-stream close"))
+        }
+        return .success(invocation(.readerStreamCloseProxy, [parameter: reference]))
+    case ("writer", "attach"):
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for writer attach"))
+        }
+        return .success(CLIOptions(action: .attach(.init(
+            method: .writerAttachProxy, parameters: [parameter: reference]
+        ), .output)))
+    case ("writer", "close"):
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for writer close"))
+        }
+        return .success(invocation(.writerCloseProxy, [parameter: reference]))
+    case ("terminal", "attach"):
+        var parameters = [parameter: reference]
+        if arguments.count > 3 {
+            let target: String
+            if arguments.count == 4, arguments[3].hasPrefix("--resize-target=") {
+                target = String(arguments[3].dropFirst("--resize-target=".count))
+            } else if arguments.count == 5, arguments[3] == "--resize-target" {
+                target = arguments[4]
+            } else {
+                return .failure(.invalidDirect("terminal attach accepts --resize-target @container/NAME or @process/NAME"))
+            }
+            guard isValidReference(target, expectedKind: "container")
+                    || isValidReference(target, expectedKind: "process") else {
+                return .failure(.invalidDirect("--resize-target must be an @container/NAME or @process/NAME reference"))
+            }
+            parameters["resizeTarget"] = .string(target)
+        }
+        return .success(CLIOptions(action: .attach(.init(
+            method: .terminalAttachProxy, parameters: parameters
+        ), .terminal)))
+    case ("terminal", "wait-attached"):
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for terminal wait-attached"))
+        }
+        return .success(invocation(.terminalWaitAttachedProxy, [parameter: reference]))
+    case ("terminal", "close"):
+        guard arguments.count == 3 else {
+            return .failure(.invalidDirect("too many arguments for terminal close"))
+        }
+        return .success(invocation(.terminalCloseProxy, [parameter: reference]))
+    default:
+        return .failure(.invalidDirect("unsupported reference operation '\(operation)' for resource '\(resource)'"))
+    }
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/Attachment.swift b/macOS/GhostTools/Sources/ghostbox/Attachment.swift
new file mode 100644
index 0000000..4f4d5de
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/Attachment.swift
@@ -0,0 +1,392 @@
+import Foundation
+
+func runAttachment(
+    invocation: GhostboxDirectInvocation,
+    expectedStream: GhostboxIOStream,
+    port: UInt32
+) -> Int32 {
+    if expectedStream == .terminal {
+        guard isatty(STDIN_FILENO) != 0, isatty(STDOUT_FILENO) != 0 else {
+            writeStderr("ghostbox: terminal attach requires terminal stdin and stdout\n")
+            return 125
+        }
+    }
+
+    let request = GhostboxDirectRequest(invocation: invocation)
+    let requestLine: Data
+    do {
+        requestLine = try encodeDirectRequestLine(request)
+    } catch {
+        writeStderr("ghostbox: failed to encode attachment request: \(error)\n")
+        return 125
+    }
+
+    let fd: Int32
+    do {
+        fd = try vsockDialHost(port: port)
+    } catch {
+        writeStderr("ghostbox: cannot connect to host: \(error)\n")
+        return 125
+    }
+    defer { Darwin.close(fd) }
+
+    guard writeAll(fd: fd, requestLine) else {
+        writeStderr("ghostbox: failed to send attachment request (errno \(errno))\n")
+        return 125
+    }
+
+    let reader = LineReader(fd: fd, maxLineBytes: kMaxIOFrameLineBytes)
+    let responseData: Data
+    do {
+        guard let response = try reader.readLine(), !response.isEmpty else {
+            writeStderr("ghostbox: connection closed before attachment response\n")
+            return 125
+        }
+        responseData = response
+    } catch {
+        writeStderr("ghostbox: failed to read attachment response: \(error)\n")
+        return 125
+    }
+
+    switch decodeDirectResponse(responseData, requestID: request.id) {
+    case .result(let value):
+        guard case .json(.string(let mode)) = value.storage, mode == expectedStream.rawValue else {
+            writeStderr("ghostbox: host returned an invalid attachment mode\n")
+            return 125
+        }
+    case .error(let code, let message):
+        writeStderr("ghostbox: host error [\(code)]: \(message)\n")
+        return 125
+    case .protocolError(let message):
+        writeStderr("ghostbox: protocol error: \(message)\n")
+        return 125
+    }
+
+    switch expectedStream {
+    case .input:
+        return forwardInputAttachment(fd: fd, reader: reader)
+    case .output:
+        _ = Darwin.shutdown(fd, SHUT_WR)
+        return receiveAttachmentOutput(fd: fd, reader: reader, expectedStream: .output)
+    case .terminal:
+        return runTerminalAttachment(fd: fd, reader: reader)
+    }
+}
+
+private func forwardInputAttachment(fd: Int32, reader: LineReader) -> Int32 {
+    let writer = AttachmentFrameWriter(fd: fd)
+    var buffer = [UInt8](repeating: 0, count: 32 * 1024)
+    while true {
+        if reader.hasBufferedLine {
+            return receiveAttachmentOutput(fd: fd, reader: reader, expectedStream: .input)
+        }
+        var descriptors = [
+            pollfd(fd: STDIN_FILENO, events: Int16(POLLIN | POLLHUP), revents: 0),
+            pollfd(fd: fd, events: Int16(POLLIN | POLLHUP | POLLERR), revents: 0),
+        ]
+        let status = Darwin.poll(&descriptors, nfds_t(descriptors.count), -1)
+        if status < 0, errno == EINTR { continue }
+        if status < 0 {
+            writeStderr("ghostbox: failed to poll stdin attachment (errno \(errno))\n")
+            return 125
+        }
+        if descriptors[1].revents != 0 {
+            return receiveAttachmentOutput(fd: fd, reader: reader, expectedStream: .input)
+        }
+        guard descriptors[0].revents != 0 else { continue }
+        let count = Darwin.read(STDIN_FILENO, &buffer, buffer.count)
+        if count > 0 {
+            guard writer.send(.data(Data(buffer[0.. Int32 {
+    let terminal: RawAttachmentTerminal
+    do {
+        terminal = try RawAttachmentTerminal(fd: STDIN_FILENO)
+    } catch {
+        writeStderr("ghostbox: failed to enter raw terminal mode: \(error)\n")
+        return 125
+    }
+
+    let writer = AttachmentFrameWriter(fd: fd)
+    defer { writer.shutdownWrite() }
+    let controlQueue = DispatchQueue(label: "org.ghostvm.ghostbox.terminal-signals", qos: .userInitiated)
+    let sendResize: @Sendable () -> Bool = {
+        let size = currentAttachmentTerminalSize()
+        return writer.send(.resize(columns: size.columns, rows: size.rows))
+    }
+    let terminationSources = installAttachmentTerminationSignalHandlers(terminal, queue: controlQueue)
+    let resizeSource = installAttachmentResizeSignalHandler(queue: controlQueue, sendResize: sendResize)
+    let jobControlSources = installAttachmentJobControlSignalHandlers(
+        terminal,
+        writer: writer,
+        queue: controlQueue,
+        sendResize: sendResize
+    )
+    defer {
+        terminationSources.forEach { $0.cancel() }
+        resizeSource.cancel()
+        jobControlSources.forEach { $0.cancel() }
+    }
+
+    do {
+        try terminal.enterRawMode()
+    } catch {
+        writeStderr("ghostbox: failed to enter raw terminal mode: \(error)\n")
+        return 125
+    }
+    defer { terminal.finish() }
+
+    var sentInitialSize = false
+    controlQueue.sync { sentInitialSize = sendResize() }
+    guard sentInitialSize else {
+        writeStderr("ghostbox: failed to send terminal size\r\n")
+        return 125
+    }
+
+    DispatchQueue.global(qos: .userInitiated).async {
+        var buffer = [UInt8](repeating: 0, count: 32 * 1024)
+        while true {
+            let count = Darwin.read(STDIN_FILENO, &buffer, buffer.count)
+            if count > 0 {
+                if !writer.send(.data(Data(buffer[0.. Int32 {
+    while true {
+        let line: Data
+        do {
+            guard let value = try reader.readLine(), !value.isEmpty else {
+                writeAttachmentDiagnostic("ghostbox: attachment closed before EOF\n", terminal: terminalDiagnostics)
+                return 125
+            }
+            line = value
+        } catch {
+            writeAttachmentDiagnostic("ghostbox: failed to read attachment frame: \(error)\n", terminal: terminalDiagnostics)
+            return 125
+        }
+
+        let frame: GhostboxIOFrame
+        do {
+            frame = try GhostboxIOFrame.decode(line: line)
+        } catch {
+            writeAttachmentDiagnostic("ghostbox: invalid attachment frame: \(error)\n", terminal: terminalDiagnostics)
+            return 125
+        }
+
+        switch frame.type {
+        case .data:
+            guard frame.stream == expectedStream, let data = frame.data else {
+                writeAttachmentDiagnostic("ghostbox: unexpected attachment data stream\n", terminal: terminalDiagnostics)
+                return 125
+            }
+            guard writeStdout(data) else {
+                _ = Darwin.shutdown(fd, SHUT_RDWR)
+                return 125
+            }
+        case .eof:
+            guard frame.stream == expectedStream else {
+                writeAttachmentDiagnostic("ghostbox: unexpected attachment EOF stream\n", terminal: terminalDiagnostics)
+                return 125
+            }
+            return 0
+        case .error:
+            writeAttachmentDiagnostic("ghostbox: host I/O error: \(frame.message ?? "unknown error")\n", terminal: terminalDiagnostics)
+            return 125
+        case .resize:
+            writeAttachmentDiagnostic("ghostbox: unexpected resize frame from host\n", terminal: terminalDiagnostics)
+            return 125
+        }
+    }
+}
+
+private final class AttachmentFrameWriter: @unchecked Sendable {
+    private let fd: Int32
+    private let lock = NSLock()
+    private var writeClosed = false
+
+    init(fd: Int32) {
+        self.fd = fd
+    }
+
+    func send(_ frame: GhostboxIOFrame) -> Bool {
+        guard let line = try? frame.encodeLine() else { return false }
+        return lock.withLock {
+            guard !writeClosed else { return false }
+            return writeAll(fd: fd, line)
+        }
+    }
+
+    func shutdownWrite() {
+        lock.withLock {
+            guard !writeClosed else { return }
+            writeClosed = true
+            _ = Darwin.shutdown(fd, SHUT_WR)
+        }
+    }
+}
+
+private func currentAttachmentTerminalSize() -> (columns: UInt16, rows: UInt16) {
+    var size = winsize()
+    let descriptor = isatty(STDOUT_FILENO) != 0 ? STDOUT_FILENO : STDIN_FILENO
+    guard ioctl(descriptor, TIOCGWINSZ, &size) == 0, size.ws_col > 0, size.ws_row > 0 else {
+        return (80, 24)
+    }
+    return (size.ws_col, size.ws_row)
+}
+
+final class RawAttachmentTerminal: @unchecked Sendable {
+    private let fd: Int32
+    private let lock = NSLock()
+    private let original: termios
+    private let raw: termios
+    private var finished = false
+
+    init(fd: Int32) throws {
+        self.fd = fd
+        var original = termios()
+        guard tcgetattr(fd, &original) == 0 else {
+            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+        }
+        var raw = original
+        cfmakeraw(&raw)
+        self.original = original
+        self.raw = raw
+    }
+
+    func enterRawMode() throws {
+        try lock.withLock {
+            guard !finished else { return }
+            var attributes = raw
+            guard tcsetattr(fd, TCSAFLUSH, &attributes) == 0 else {
+                throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+            }
+        }
+    }
+
+    @discardableResult
+    func suspend() -> Bool {
+        lock.withLock {
+            guard !finished else { return false }
+            var attributes = original
+            return tcsetattr(fd, TCSAFLUSH, &attributes) == 0
+        }
+    }
+
+    @discardableResult
+    func resume() -> Bool {
+        lock.withLock {
+            guard !finished else { return false }
+            var attributes = raw
+            return tcsetattr(fd, TCSAFLUSH, &attributes) == 0
+        }
+    }
+
+    func finish() {
+        lock.withLock {
+            guard !finished else { return }
+            finished = true
+            var attributes = original
+            _ = tcsetattr(fd, TCSAFLUSH, &attributes)
+        }
+    }
+}
+
+private func installAttachmentTerminationSignalHandlers(
+    _ terminal: RawAttachmentTerminal,
+    queue: DispatchQueue
+) -> [DispatchSourceSignal] {
+    [SIGINT, SIGTERM, SIGHUP, SIGQUIT].map { signalNumber in
+        signal(signalNumber, SIG_IGN)
+        let source = DispatchSource.makeSignalSource(signal: signalNumber, queue: queue)
+        source.setEventHandler {
+            terminal.finish()
+            signal(signalNumber, SIG_DFL)
+            raise(signalNumber)
+        }
+        source.resume()
+        return source
+    }
+}
+
+private func installAttachmentResizeSignalHandler(
+    queue: DispatchQueue,
+    sendResize: @escaping @Sendable () -> Bool
+) -> DispatchSourceSignal {
+    signal(SIGWINCH, SIG_IGN)
+    let source = DispatchSource.makeSignalSource(signal: SIGWINCH, queue: queue)
+    source.setEventHandler { _ = sendResize() }
+    source.resume()
+    return source
+}
+
+private func installAttachmentJobControlSignalHandlers(
+    _ terminal: RawAttachmentTerminal,
+    writer: AttachmentFrameWriter,
+    queue: DispatchQueue,
+    sendResize: @escaping @Sendable () -> Bool
+) -> [DispatchSourceSignal] {
+    signal(SIGTSTP, SIG_IGN)
+    signal(SIGCONT, SIG_IGN)
+
+    let suspendSource = DispatchSource.makeSignalSource(signal: SIGTSTP, queue: queue)
+    suspendSource.setEventHandler {
+        guard terminal.suspend() else {
+            writer.shutdownWrite()
+            return
+        }
+        signal(SIGTSTP, SIG_DFL)
+        raise(SIGTSTP)
+        signal(SIGTSTP, SIG_IGN)
+        guard terminal.resume(), sendResize() else { writer.shutdownWrite(); return }
+    }
+    suspendSource.resume()
+
+    let continueSource = DispatchSource.makeSignalSource(signal: SIGCONT, queue: queue)
+    continueSource.setEventHandler {
+        guard terminal.resume(), sendResize() else { writer.shutdownWrite(); return }
+    }
+    continueSource.resume()
+    return [suspendSource, continueSource]
+}
+
+private func writeAttachmentDiagnostic(_ message: String, terminal: Bool) {
+    if terminal {
+        writeStderr(message.replacingOccurrences(of: "\n", with: "\r\n"))
+    } else {
+        writeStderr(message)
+    }
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/DirectCommand.swift b/macOS/GhostTools/Sources/ghostbox/DirectCommand.swift
new file mode 100644
index 0000000..fc4714f
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/DirectCommand.swift
@@ -0,0 +1,301 @@
+import Foundation
+
+func parseDirectArguments(_ argv: [String]) -> Result {
+    guard !argv.isEmpty else {
+        return .failure(.invalidDirect("direct invocation requires at least one argument"))
+    }
+    guard argv.count <= kMaxDirectArgumentCount else {
+        return .failure(.invalidDirect("direct invocation exceeds the \(kMaxDirectArgumentCount)-argument limit"))
+    }
+    var totalBytes = 0
+    for argument in argv {
+        guard !argument.contains("\0") else {
+            return .failure(.invalidDirect("direct arguments must not contain NUL"))
+        }
+        let byteCount = argument.utf8.count
+        guard byteCount <= kMaxDirectArgumentBytes else {
+            return .failure(.invalidDirect("a direct argument exceeds the \(kMaxDirectArgumentBytes)-byte limit"))
+        }
+        totalBytes += byteCount
+        guard totalBytes <= kMaxDirectArgumentsBytes else {
+            return .failure(.invalidDirect("direct arguments exceed the \(kMaxDirectArgumentsBytes)-byte limit"))
+        }
+    }
+
+    do {
+        let (signature, argumentStart) = try selectSignature(argv)
+        let parameters = try parseParameters(argv, startingAt: argumentStart, signature: signature)
+        return .success(GhostboxDirectInvocation(
+            method: GhostboxDirectMethod(rawValue: signature.methodID),
+            parameters: parameters
+        ))
+    } catch let error as ParseError {
+        return .failure(error)
+    } catch {
+        return .failure(.invalidDirect(String(describing: error)))
+    }
+}
+
+private func selectSignature(_ argv: [String]) throws -> (GhostboxCommandSignature, Int) {
+    let command = argv[0]
+    guard let signature = ghostboxCommandCatalog.first(where: {
+        $0.commandID == command || $0.aliases.contains(command)
+    }) else {
+        throw ParseError.invalidDirect(
+            "unknown qualified command '\(command)'; expected NAMESPACE:RESOURCE:OPERATION"
+        )
+    }
+    return (signature, 1)
+}
+
+private func parseParameters(
+    _ argv: [String],
+    startingAt argumentStart: Int,
+    signature: GhostboxCommandSignature
+) throws -> [String: GhostboxJSONValue] {
+    var parameters = signature.implicitDefaults
+    for option in signature.options {
+        if let defaultValue = option.defaultValue {
+            parameters[option.parameterName] = defaultValue
+        }
+    }
+
+    var positionals = signature.positionals
+    if signature.shape == .reference {
+        guard let receiver = positionals.first else {
+            throw ParseError.invalidDirect("catalog entry '\(signature.methodID)' has no receiver")
+        }
+        parameters[receiver.parameterName] = try parseCatalogValue(
+            argv[argumentStart],
+            type: receiver.type,
+            label: receiver.name
+        )
+        positionals.removeFirst()
+    }
+
+    var positionalValues: [String] = []
+    var seenOptions: [String: Int] = [:]
+    var acceptsOptions = true
+    var index = argumentStart + (signature.shape == .reference ? 1 : 0)
+    while index < argv.count {
+        let argument = argv[index]
+        if acceptsOptions && argument == "--" {
+            acceptsOptions = false
+            index += 1
+            continue
+        }
+        if acceptsOptions && argument.hasPrefix("--") {
+            let (name, attachedValue) = splitOption(argument)
+            guard let option = signature.options.first(where: { $0.names.contains(name) }) else {
+                throw ParseError.invalidDirect("unknown option '\(name)' for \(signature.resource) \(signature.operation)")
+            }
+            let count = seenOptions[option.parameterName, default: 0]
+            guard option.repeatable || count == 0 else {
+                throw ParseError.invalidDirect("option \(name) may be specified once")
+            }
+
+            let rawValue: String
+            if let attachedValue {
+                rawValue = attachedValue
+            } else if option.type == "bool",
+                      index + 1 == argv.count || argv[index + 1].hasPrefix("--") {
+                rawValue = "true"
+            } else {
+                guard index + 1 < argv.count, !argv[index + 1].hasPrefix("--") else {
+                    throw ParseError.invalidDirect("option \(name) requires a value")
+                }
+                index += 1
+                rawValue = argv[index]
+            }
+            let value = try parseCatalogValue(rawValue, type: option.type, label: name)
+            if option.repeatable {
+                appendRepeated(value, for: option.parameterName, to: ¶meters)
+            } else {
+                parameters[option.parameterName] = value
+            }
+            seenOptions[option.parameterName] = count + 1
+            index += 1
+            continue
+        }
+        positionalValues.append(argument)
+        index += 1
+    }
+
+    for option in signature.options where option.required {
+        guard seenOptions[option.parameterName, default: 0] > 0 else {
+            throw ParseError.invalidDirect("missing required option \(option.names[0])")
+        }
+    }
+
+    var positionalIndex = 0
+    for positional in positionals {
+        if positional.repeatable {
+            let remaining = positionalValues[positionalIndex...]
+            guard !positional.required || !remaining.isEmpty else {
+                throw ParseError.invalidDirect("missing required positional \(positional.name)")
+            }
+            parameters[positional.parameterName] = .array(try remaining.map {
+                try parseCatalogValue($0, type: positional.type, label: positional.name)
+            })
+            positionalIndex = positionalValues.count
+            continue
+        }
+        guard positionalIndex < positionalValues.count else {
+            if positional.required {
+                throw ParseError.invalidDirect("missing required positional \(positional.name)")
+            }
+            continue
+        }
+        parameters[positional.parameterName] = try parseCatalogValue(
+            positionalValues[positionalIndex],
+            type: positional.type,
+            label: positional.name
+        )
+        positionalIndex += 1
+    }
+    guard positionalIndex == positionalValues.count else {
+        throw ParseError.invalidDirect("too many positional arguments for \(signature.resource) \(signature.operation)")
+    }
+    return parameters
+}
+
+private func parseCatalogValue(_ rawValue: String, type: String, label: String) throws -> GhostboxJSONValue {
+    let nullable = type.hasSuffix("?")
+    let baseType = nullable ? String(type.dropLast()) : type
+    if nullable && rawValue == "null" {
+        return .null
+    }
+
+    if let separator = baseType.firstIndex(of: "=") {
+        let leftType = String(baseType[.. = [
+    "mount-runtime-options",
+    "oci-descriptor-json",
+    "oci-image-config",
+    "oci-user",
+    "pod-volume-source",
+]
+
+private func appendRepeated(
+    _ value: GhostboxJSONValue,
+    for key: String,
+    to parameters: inout [String: GhostboxJSONValue]
+) {
+    if let existing = parameters[key], case .array(var values) = existing {
+        values.append(value)
+        parameters[key] = .array(values)
+    } else {
+        parameters[key] = .array([value])
+    }
+}
+
+private func splitOption(_ argument: String) -> (String, String?) {
+    guard let separator = argument.firstIndex(of: "=") else { return (argument, nil) }
+    return (String(argument[.. Bool {
+    guard reference.first == "@", let slash = reference.firstIndex(of: "/") else { return false }
+    let kind = String(reference[reference.index(after: reference.startIndex).. Bool {
+    !value.isEmpty && value.utf8.count <= 128 && value.utf8.allSatisfy {
+        (48...57).contains($0) || (65...90).contains($0) || (97...122).contains($0)
+            || $0 == 45 || $0 == 46 || $0 == 95
+    }
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/DirectProtocol.swift b/macOS/GhostTools/Sources/ghostbox/DirectProtocol.swift
new file mode 100644
index 0000000..344ba7c
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/DirectProtocol.swift
@@ -0,0 +1,493 @@
+import Foundation
+
+let kMaxDirectRequestLineBytes = 64 * 1024
+let kMaxDirectArgumentCount = 256
+let kMaxDirectArgumentBytes = 16 * 1024
+let kMaxDirectArgumentsBytes = 60 * 1024
+let kMaxDirectBytePayloadBytes = 1024 * 1024
+let kMaxDirectResponseLineBytes = 2 * 1024 * 1024
+let kMaxIOFrameDataBytes = 64 * 1024
+let kMaxIOFrameLineBytes = 128 * 1024
+
+enum GhostboxDirectProtocolError: LocalizedError, Equatable {
+    case requestTooLarge
+
+    var errorDescription: String? {
+        "direct request exceeds the \(kMaxDirectRequestLineBytes)-byte limit"
+    }
+}
+
+struct GhostboxDirectMethod: RawRepresentable, Codable, Hashable, Sendable {
+    let rawValue: String
+
+    init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+
+    static let dnsCreate = Self(rawValue: "dns.create")
+    static let dnsDefaultNameservers = Self(rawValue: "dns.defaultNameservers")
+    static let dnsValidate = Self(rawValue: "dns.validate")
+    static let dnsResolvConf = Self(rawValue: "dns.resolvConf")
+    static let dnsNameservers = Self(rawValue: "dns.nameservers")
+    static let dnsDomain = Self(rawValue: "dns.domain")
+    static let dnsSearchDomains = Self(rawValue: "dns.searchDomains")
+    static let dnsOptions = Self(rawValue: "dns.options")
+    static let dnsDelete = Self(rawValue: "dns.delete")
+    static let processConfigDefaultPath = Self(rawValue: "processConfig.defaultPath")
+    static let processConfigDelete = Self(rawValue: "processConfig.delete")
+    static let networkDelete = Self(rawValue: "network.delete")
+    static let managerClose = Self(rawValue: "manager.close")
+    static let mountGuestShare = Self(rawValue: "mount.guestShare")
+    static let mountDelete = Self(rawValue: "mount.delete")
+    static let volumeCreate = Self(rawValue: "volume.create")
+    static let volumeList = Self(rawValue: "volume.list")
+    static let volumeInspect = Self(rawValue: "volume.inspect")
+    static let volumeMount = Self(rawValue: "volume.mount")
+    static let volumeDelete = Self(rawValue: "volume.delete")
+    static let containerDefaultMaskedPaths = Self(rawValue: "container.defaultMaskedPaths")
+    static let containerDefaultReadonlyPaths = Self(rawValue: "container.defaultReadonlyPaths")
+    static let containerDefaultCopyChunkSize = Self(rawValue: "container.defaultCopyChunkSize")
+    static let containerMaxIDLength = Self(rawValue: "container.maxIDLength")
+    static let kernelDefault = Self(rawValue: "kernel.default")
+    static let kernelInstallRecommended = Self(rawValue: "kernel.installRecommended")
+    static let readerStreamCreateProxy = Self(rawValue: "readerStream.createProxy")
+    static let readerStreamAttachProxy = Self(rawValue: "readerStream.attachProxy")
+    static let readerStreamCloseProxy = Self(rawValue: "readerStream.closeProxy")
+    static let writerCreateProxy = Self(rawValue: "writer.createProxy")
+    static let writerAttachProxy = Self(rawValue: "writer.attachProxy")
+    static let writerCloseProxy = Self(rawValue: "writer.closeProxy")
+    static let terminalCreateProxy = Self(rawValue: "terminal.createProxy")
+    static let terminalAttachProxy = Self(rawValue: "terminal.attachProxy")
+    static let terminalWaitAttachedProxy = Self(rawValue: "terminal.waitAttachedProxy")
+    static let terminalCloseProxy = Self(rawValue: "terminal.closeProxy")
+}
+
+enum GhostboxIOStream: String, Codable, Equatable, Sendable {
+    case input
+    case output
+    case terminal
+}
+
+enum GhostboxIOFrameType: String, Codable, Equatable, Sendable {
+    case data
+    case eof
+    case resize
+    case error
+}
+
+struct GhostboxIOFrame: Codable, Equatable, Sendable {
+    var version = kProtocolVersion
+    var type: GhostboxIOFrameType
+    var stream: GhostboxIOStream?
+    var data: Data?
+    var columns: UInt16?
+    var rows: UInt16?
+    var message: String?
+
+    static func data(_ data: Data, stream: GhostboxIOStream) -> Self {
+        Self(type: .data, stream: stream, data: data)
+    }
+
+    static func eof(_ stream: GhostboxIOStream) -> Self {
+        Self(type: .eof, stream: stream)
+    }
+
+    static func resize(columns: UInt16, rows: UInt16) -> Self {
+        Self(type: .resize, stream: .terminal, columns: columns, rows: rows)
+    }
+
+    static func error(_ message: String) -> Self {
+        Self(type: .error, message: message)
+    }
+
+    func validate() throws {
+        guard version == kProtocolVersion else {
+            throw ParseError.invalidDirect("unsupported I/O frame version")
+        }
+        switch type {
+        case .data:
+            guard stream != nil, let data, !data.isEmpty, data.count <= kMaxIOFrameDataBytes,
+                  columns == nil, rows == nil, message == nil else {
+                throw ParseError.invalidDirect("malformed I/O data frame")
+            }
+        case .eof:
+            guard stream != nil, data == nil, columns == nil, rows == nil, message == nil else {
+                throw ParseError.invalidDirect("malformed I/O EOF frame")
+            }
+        case .resize:
+            guard stream == .terminal, data == nil, message == nil,
+                  let columns, columns > 0, let rows, rows > 0 else {
+                throw ParseError.invalidDirect("malformed I/O resize frame")
+            }
+        case .error:
+            guard stream == nil, data == nil, columns == nil, rows == nil,
+                  let message, !message.isEmpty, message.utf8.count <= 4096 else {
+                throw ParseError.invalidDirect("malformed I/O error frame")
+            }
+        }
+    }
+
+    static func decode(line: Data) throws -> Self {
+        guard !line.isEmpty, line.count <= kMaxIOFrameLineBytes else {
+            throw ParseError.invalidDirect("invalid I/O frame length")
+        }
+        let frame = try JSONDecoder().decode(Self.self, from: line)
+        try frame.validate()
+        return frame
+    }
+
+    func encodeLine() throws -> Data {
+        try validate()
+        var encoded = try JSONEncoder().encode(self)
+        guard encoded.count <= kMaxIOFrameLineBytes else {
+            throw ParseError.invalidDirect("I/O frame exceeds the line limit")
+        }
+        encoded.append(0x0A)
+        return encoded
+    }
+}
+
+indirect enum GhostboxJSONValue: Codable, Equatable, Sendable {
+    case null
+    case boolean(Bool)
+    case string(String)
+    case integer(Int64)
+    case unsignedInteger(UInt64)
+    case array([GhostboxJSONValue])
+    case object([String: GhostboxJSONValue])
+
+    private static let unsignedIntegerTag = "$uint64"
+
+    init(from decoder: Decoder) throws {
+        let single = try decoder.singleValueContainer()
+        if single.decodeNil() {
+            self = .null
+            return
+        }
+        if let value = try? single.decode(Bool.self) {
+            self = .boolean(value)
+            return
+        }
+        if let value = try? single.decode(String.self) {
+            self = .string(value)
+            return
+        }
+        if let value = try? single.decode(Int64.self) {
+            self = .integer(value)
+            return
+        }
+        if let value = try? single.decode(UInt64.self) {
+            self = .unsignedInteger(value)
+            return
+        }
+        if var container = try? decoder.unkeyedContainer() {
+            var values: [GhostboxJSONValue] = []
+            while !container.isAtEnd {
+                try values.append(container.decode(GhostboxJSONValue.self))
+            }
+            self = .array(values)
+            return
+        }
+
+        let container = try decoder.container(keyedBy: JSONCodingKey.self)
+        if container.contains(JSONCodingKey(Self.unsignedIntegerTag)) {
+            guard container.allKeys.count == 1 else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: JSONCodingKey(Self.unsignedIntegerTag),
+                    in: container,
+                    debugDescription: "\(Self.unsignedIntegerTag) must be the only key in a tagged unsigned integer"
+                )
+            }
+            let encoded = try container.decode(String.self, forKey: JSONCodingKey(Self.unsignedIntegerTag))
+            guard isCanonicalUnsignedInteger(encoded), let value = UInt64(encoded) else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: JSONCodingKey(Self.unsignedIntegerTag),
+                    in: container,
+                    debugDescription: "\(Self.unsignedIntegerTag) must contain a canonical UInt64 decimal string"
+                )
+            }
+            self = .unsignedInteger(value)
+            return
+        }
+
+        self = .object(try Dictionary(uniqueKeysWithValues: container.allKeys.map { key in
+            (key.stringValue, try container.decode(GhostboxJSONValue.self, forKey: key))
+        }))
+    }
+
+    func encode(to encoder: Encoder) throws {
+        switch self {
+        case .null:
+            var container = encoder.singleValueContainer()
+            try container.encodeNil()
+        case .boolean(let value):
+            var container = encoder.singleValueContainer()
+            try container.encode(value)
+        case .string(let value):
+            var container = encoder.singleValueContainer()
+            try container.encode(value)
+        case .integer(let value):
+            var container = encoder.singleValueContainer()
+            try container.encode(value)
+        case .unsignedInteger(let value):
+            var container = encoder.container(keyedBy: JSONCodingKey.self)
+            try container.encode(String(value), forKey: JSONCodingKey(Self.unsignedIntegerTag))
+        case .array(let values):
+            var container = encoder.unkeyedContainer()
+            for value in values {
+                try container.encode(value)
+            }
+        case .object(let values):
+            var container = encoder.container(keyedBy: JSONCodingKey.self)
+            for (key, value) in values {
+                try container.encode(value, forKey: JSONCodingKey(key))
+            }
+        }
+    }
+}
+
+private struct JSONCodingKey: CodingKey, Hashable {
+    let stringValue: String
+    let intValue: Int? = nil
+
+    init(_ stringValue: String) {
+        self.stringValue = stringValue
+    }
+
+    init?(stringValue: String) {
+        self.init(stringValue)
+    }
+
+    init?(intValue: Int) {
+        return nil
+    }
+}
+
+private func isCanonicalUnsignedInteger(_ value: String) -> Bool {
+    guard !value.isEmpty else { return false }
+    if value == "0" { return true }
+    guard value.first != "0" else { return false }
+    return value.utf8.allSatisfy { (0x30...0x39).contains($0) }
+}
+
+struct GhostboxDirectInvocation: Equatable, Sendable {
+    let method: GhostboxDirectMethod
+    let parameters: [String: GhostboxJSONValue]
+}
+
+struct GhostboxDirectRequest: Codable, Equatable, Sendable {
+    let version: Int
+    let operation: String
+    let id: String
+    let method: GhostboxDirectMethod
+    let parameters: [String: GhostboxJSONValue]
+
+    init(id: String = UUID().uuidString.lowercased(), invocation: GhostboxDirectInvocation) {
+        version = kProtocolVersion
+        operation = "direct"
+        self.id = id
+        method = invocation.method
+        parameters = invocation.parameters
+    }
+}
+
+struct GhostboxDirectValue: Codable, Equatable, Sendable {
+    enum Storage: Equatable, Sendable {
+        case json(GhostboxJSONValue)
+        case reference(String)
+        case references([String])
+        case bytes(Data)
+        case void
+    }
+
+    let storage: Storage
+
+    private init(storage: Storage) {
+        self.storage = storage
+    }
+
+    private enum CodingKeys: String, CodingKey, CaseIterable {
+        case type
+        case value
+    }
+
+    private enum Kind: String, Codable {
+        case null
+        case boolean
+        case string
+        case integer
+        case unsignedInteger = "unsigned_integer"
+        case array
+        case object
+        case reference
+        case references
+        case bytes
+        case void
+    }
+
+    static var null: Self { Self(storage: .json(.null)) }
+    static func boolean(_ value: Bool) -> Self { Self(storage: .json(.boolean(value))) }
+    static func string(_ value: String) -> Self { Self(storage: .json(.string(value))) }
+    static func integer(_ value: Int64) -> Self { Self(storage: .json(.integer(value))) }
+    static func unsignedInteger(_ value: UInt64) -> Self { Self(storage: .json(.unsignedInteger(value))) }
+    static func array(_ value: [GhostboxDirectValue]) -> Self {
+        Self(storage: .json(.array(value.map(\.jsonRepresentation))))
+    }
+    static func object(_ value: [String: GhostboxDirectValue]) -> Self {
+        Self(storage: .json(.object(value.mapValues(\.jsonRepresentation))))
+    }
+    static func strings(_ value: [String]) -> Self {
+        Self(storage: .json(.array(value.map(GhostboxJSONValue.string))))
+    }
+    static func reference(_ value: String) -> Self { Self(storage: .reference(value)) }
+    static func references(_ value: [String]) -> Self { Self(storage: .references(value)) }
+    static func bytes(_ value: Data) -> Self { Self(storage: .bytes(value)) }
+    static var void: Self { Self(storage: .void) }
+
+    var jsonRepresentation: GhostboxJSONValue {
+        switch storage {
+        case .json(let value): return value
+        case .reference(let value): return .string(value)
+        case .references(let values): return .array(values.map(GhostboxJSONValue.string))
+        case .bytes(let value): return .object(["$bytes": .string(value.base64EncodedString())])
+        case .void: return .null
+        }
+    }
+
+    init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let kind = try container.decode(Kind.self, forKey: .type)
+        let requiresValue = kind != .null && kind != .void
+        let rawContainer = try decoder.container(keyedBy: JSONCodingKey.self)
+        let expectedKeys: Set = requiresValue ? ["type", "value"] : ["type"]
+        guard Set(rawContainer.allKeys.map(\.stringValue)) == expectedKeys else {
+            throw DecodingError.dataCorruptedError(
+                forKey: .type,
+                in: container,
+                debugDescription: "malformed tagged direct value"
+            )
+        }
+
+        switch kind {
+        case .null: storage = .json(.null)
+        case .boolean: storage = .json(.boolean(try container.decode(Bool.self, forKey: .value)))
+        case .string: storage = .json(.string(try container.decode(String.self, forKey: .value)))
+        case .integer: storage = .json(.integer(try container.decode(Int64.self, forKey: .value)))
+        case .unsignedInteger:
+            let encoded = try container.decode(String.self, forKey: .value)
+            guard isCanonicalUnsignedInteger(encoded), let value = UInt64(encoded) else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: .value,
+                    in: container,
+                    debugDescription: "unsigned_integer must contain a canonical UInt64 decimal string"
+                )
+            }
+            storage = .json(.unsignedInteger(value))
+        case .array: storage = .json(.array(try container.decode([GhostboxJSONValue].self, forKey: .value)))
+        case .object: storage = .json(.object(try container.decode([String: GhostboxJSONValue].self, forKey: .value)))
+        case .reference: storage = .reference(try container.decode(String.self, forKey: .value))
+        case .references: storage = .references(try container.decode([String].self, forKey: .value))
+        case .bytes:
+            let value = try container.decode(Data.self, forKey: .value)
+            guard value.count <= kMaxDirectBytePayloadBytes else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: .value,
+                    in: container,
+                    debugDescription: "byte payload exceeds the \(kMaxDirectBytePayloadBytes)-byte limit"
+                )
+            }
+            storage = .bytes(value)
+        case .void: storage = .void
+        }
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        switch storage {
+        case .json(.null):
+            try container.encode(Kind.null, forKey: .type)
+        case .json(.boolean(let value)):
+            try container.encode(Kind.boolean, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.string(let value)):
+            try container.encode(Kind.string, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.integer(let value)):
+            try container.encode(Kind.integer, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.unsignedInteger(let value)):
+            try container.encode(Kind.unsignedInteger, forKey: .type)
+            try container.encode(String(value), forKey: .value)
+        case .json(.array(let value)):
+            try container.encode(Kind.array, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.object(let value)):
+            try container.encode(Kind.object, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .reference(let value):
+            try container.encode(Kind.reference, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .references(let value):
+            try container.encode(Kind.references, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .bytes(let value):
+            guard value.count <= kMaxDirectBytePayloadBytes else {
+                throw EncodingError.invalidValue(
+                    value,
+                    EncodingError.Context(codingPath: encoder.codingPath, debugDescription: "byte payload exceeds the \(kMaxDirectBytePayloadBytes)-byte limit")
+                )
+            }
+            try container.encode(Kind.bytes, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .void:
+            try container.encode(Kind.void, forKey: .type)
+        }
+    }
+}
+
+struct GhostboxDirectFailure: Codable, Equatable {
+    let code: String
+    let message: String
+}
+
+struct GhostboxDirectResponse: Codable, Equatable {
+    let version: Int
+    let id: String
+    let result: GhostboxDirectValue?
+    let error: GhostboxDirectFailure?
+}
+
+enum DecodedDirectResponse: Equatable {
+    case result(GhostboxDirectValue)
+    case error(code: String, message: String)
+    case protocolError(String)
+}
+
+func encodeDirectRequestLine(_ request: GhostboxDirectRequest) throws -> Data {
+    var data = try JSONEncoder().encode(request)
+    guard data.count <= kMaxDirectRequestLineBytes else {
+        throw GhostboxDirectProtocolError.requestTooLarge
+    }
+    data.append(0x0A)
+    return data
+}
+
+func decodeDirectResponse(_ data: Data, requestID: String) -> DecodedDirectResponse {
+    guard let response = try? JSONDecoder().decode(GhostboxDirectResponse.self, from: data) else {
+        return .protocolError("malformed direct response")
+    }
+    guard response.version == kProtocolVersion else {
+        return .protocolError("unsupported direct response version")
+    }
+    guard response.id == requestID else {
+        return .protocolError("direct response ID does not match request")
+    }
+    switch (response.result, response.error) {
+    case (.some(let result), .none):
+        return .result(result)
+    case (.none, .some(let error)) where !error.code.isEmpty && !error.message.isEmpty:
+        return .error(code: error.code, message: error.message)
+    default:
+        return .protocolError("direct response must contain exactly one result or error")
+    }
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/Generated/GhostboxCommandCatalog.generated.swift b/macOS/GhostTools/Sources/ghostbox/Generated/GhostboxCommandCatalog.generated.swift
new file mode 100644
index 0000000..a632475
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/Generated/GhostboxCommandCatalog.generated.swift
@@ -0,0 +1,8638 @@
+// Generated by scripts/generate-ghostbox-command-catalog.py. Do not edit.
+
+enum GhostboxCommandShape: String, Sendable {
+    case `static`
+    case create
+    case reference
+}
+
+struct GhostboxCommandArgument: Sendable {
+    let name: String
+    let parameterName: String
+    let type: String
+    let required: Bool
+    let repeatable: Bool
+}
+
+struct GhostboxCommandOption: Sendable {
+    let names: [String]
+    let parameterName: String
+    let type: String
+    let required: Bool
+    let repeatable: Bool
+    let defaultValue: GhostboxJSONValue?
+}
+
+struct GhostboxCommandSignature: Sendable {
+    let commandID: String
+    let methodID: String
+    let namespace: String
+    let sourceKind: String
+    let aliases: [String]
+    let resource: String
+    let operation: String
+    let shape: GhostboxCommandShape
+    let signature: String
+    let resultType: String
+    let appleAPISymbol: String
+    let appleDocumentationURL: String
+    let swiftModule: String?
+    let swiftSymbol: String
+    let swiftSource: String?
+    let exampleArguments: [String]
+    let positionals: [GhostboxCommandArgument]
+    let options: [GhostboxCommandOption]
+    let implicitDefaults: [String: GhostboxJSONValue]
+}
+
+let ghostboxCommandResources = [
+    "authentication",
+    "boot-log",
+    "capabilities",
+    "container",
+    "container-config",
+    "content",
+    "content-store",
+    "dns",
+    "hosts",
+    "hosts-entry",
+    "image",
+    "image-description",
+    "image-store",
+    "init-image",
+    "interface",
+    "kernel",
+    "kernel-command-line",
+    "kernel-image",
+    "manager",
+    "memory-size",
+    "mount",
+    "network",
+    "parser",
+    "pod",
+    "pod-config",
+    "pod-container-config",
+    "pod-volume",
+    "process",
+    "process-config",
+    "progress-handler",
+    "resource-labels",
+    "rlimit",
+    "rlimit-kind",
+    "socket",
+    "standard-vm-config",
+    "vm-config",
+    "vm-instance",
+    "vmm",
+    "volume",
+]
+
+let ghostboxCommandCatalog: [GhostboxCommandSignature] = [
+    .init(
+        commandID: "cn:image-store:create",
+        methodID: "imageStore.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:create",
+        ],
+        resource: "image-store",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:image-store:create \n--path \n[--content-store @]\n-> @",
+        resultType: "reference:image-store",
+        appleAPISymbol: "ImageStore.init(path:contentStore:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/init(path:contentstore:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.init(path:contentStore:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:create",
+            "example",
+            "--path",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--path"], parameterName: "path", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--content-store"], parameterName: "contentStore", type: "reference:content-store", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:default",
+        methodID: "imageStore.default",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:default",
+        ],
+        resource: "image-store",
+        operation: "default",
+        shape: .static,
+        signature: "ghostbox cn:image-store:default -> @",
+        resultType: "reference:image-store",
+        appleAPISymbol: "ImageStore.default",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/default",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.default",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:default",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:path",
+        methodID: "imageStore.path",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:path",
+        ],
+        resource: "image-store",
+        operation: "path",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:path @ -> ",
+        resultType: "host-url",
+        appleAPISymbol: "ImageStore.path",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/path",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.path",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:path",
+            "@image-store/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:get",
+        methodID: "imageStore.get",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:get",
+        ],
+        resource: "image-store",
+        operation: "get",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:get @\n\n[--pull=false]\n-> @",
+        resultType: "reference:image",
+        appleAPISymbol: "ImageStore.get(reference:pull:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/get(reference:pull:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.get(reference:pull:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:get",
+            "@image-store/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--pull"], parameterName: "pull", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:list",
+        methodID: "imageStore.list",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:list",
+        ],
+        resource: "image-store",
+        operation: "list",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:list @ -> @...",
+        resultType: "reference:image[]",
+        appleAPISymbol: "ImageStore.list()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/list()",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.list()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:list",
+            "@image-store/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:create-image",
+        methodID: "imageStore.createImage",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:create-image",
+        ],
+        resource: "image-store",
+        operation: "create-image",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:create-image @\n@\n-> @",
+        resultType: "reference:image",
+        appleAPISymbol: "ImageStore.create(description:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/create(description:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.create(description:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:create-image",
+            "@image-store/example",
+            "@image-description/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "image-description", parameterName: "imageDescription", type: "reference:image-description", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:delete",
+        methodID: "imageStore.delete",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:delete",
+        ],
+        resource: "image-store",
+        operation: "delete",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:delete @\n\n[--perform-cleanup=false]",
+        resultType: "void",
+        appleAPISymbol: "ImageStore.delete(reference:performCleanup:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/delete(reference:performcleanup:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.delete(reference:performCleanup:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:delete",
+            "@image-store/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--perform-cleanup"], parameterName: "performCleanup", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:clean-up-orphaned-blobs",
+        methodID: "imageStore.cleanUpOrphanedBlobs",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:clean-up-orphaned-blobs",
+        ],
+        resource: "image-store",
+        operation: "clean-up-orphaned-blobs",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:clean-up-orphaned-blobs @\n-> ",
+        resultType: "deleted-digests-and-freed-bytes",
+        appleAPISymbol: "ImageStore.cleanUpOrphanedBlobs()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/cleanuporphanedblobs()",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.cleanUpOrphanedBlobs()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:clean-up-orphaned-blobs",
+            "@image-store/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:calculate-orphaned-blobs-size",
+        methodID: "imageStore.calculateOrphanedBlobsSize",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:calculate-orphaned-blobs-size",
+        ],
+        resource: "image-store",
+        operation: "calculate-orphaned-blobs-size",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:calculate-orphaned-blobs-size @\n-> ",
+        resultType: "uint64",
+        appleAPISymbol: "ImageStore.calculateOrphanedBlobsSize()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/calculateorphanedblobssize()",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.calculateOrphanedBlobsSize()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:calculate-orphaned-blobs-size",
+            "@image-store/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:tag",
+        methodID: "imageStore.tag",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:tag",
+        ],
+        resource: "image-store",
+        operation: "tag",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:tag @\n\n\n-> @",
+        resultType: "reference:image",
+        appleAPISymbol: "ImageStore.tag(existing:new:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/tag(existing:new:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.tag(existing:new:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:tag",
+            "@image-store/example",
+            "example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "existing-reference", parameterName: "existingReference", type: "string", required: true, repeatable: false),
+            .init(name: "new-reference", parameterName: "newReference", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:pull",
+        methodID: "imageStore.pull",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:pull",
+        ],
+        resource: "image-store",
+        operation: "pull",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:pull @\n\n[--platform ]\n[--insecure=false]\n[--authentication @]\n[--progress @]\n[--max-concurrent-downloads=3]\n-> @",
+        resultType: "reference:image",
+        appleAPISymbol: "ImageStore.pull(reference:platform:insecure:auth:progress:maxConcurrentDownloads:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/pull(reference:platform:insecure:auth:progress:maxconcurrentdownloads:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.pull(reference:platform:insecure:auth:progress:maxConcurrentDownloads:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:pull",
+            "@image-store/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--platform"], parameterName: "platform", type: "oci-platform", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--insecure"], parameterName: "insecure", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--authentication"], parameterName: "authentication", type: "reference:authentication", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--max-concurrent-downloads"], parameterName: "maxConcurrentDownloads", type: "int", required: false, repeatable: false, defaultValue: .integer(3)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:push",
+        methodID: "imageStore.push",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:push",
+        ],
+        resource: "image-store",
+        operation: "push",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:push @\n\n[--platform ]\n[--insecure=false]\n[--authentication @]\n[--progress @]",
+        resultType: "void",
+        appleAPISymbol: "ImageStore.push(reference:platform:insecure:auth:progress:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/push(reference:platform:insecure:auth:progress:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.push(reference:platform:insecure:auth:progress:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:push",
+            "@image-store/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--platform"], parameterName: "platform", type: "oci-platform", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--insecure"], parameterName: "insecure", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--authentication"], parameterName: "authentication", type: "reference:authentication", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:push-many",
+        methodID: "imageStore.pushMany",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:push-many",
+        ],
+        resource: "image-store",
+        operation: "push-many",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:push-many @\n...\n[--platform ]\n[--insecure=false]\n[--authentication @]\n[--max-concurrent-uploads=3]\n[--progress @]",
+        resultType: "void",
+        appleAPISymbol: "ImageStore.push(references:platform:insecure:auth:maxConcurrentUploads:progress:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/push(references:platform:insecure:auth:maxconcurrentuploads:progress:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.push(references:platform:insecure:auth:maxConcurrentUploads:progress:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:push-many",
+            "@image-store/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: true),
+        ],
+        options: [
+            .init(names: ["--platform"], parameterName: "platform", type: "oci-platform", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--insecure"], parameterName: "insecure", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--authentication"], parameterName: "authentication", type: "reference:authentication", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--max-concurrent-uploads"], parameterName: "maxConcurrentUploads", type: "int", required: false, repeatable: false, defaultValue: .integer(3)),
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:save",
+        methodID: "imageStore.save",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:save",
+        ],
+        resource: "image-store",
+        operation: "save",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:save @\n...\n--out \n[--platform ]",
+        resultType: "void",
+        appleAPISymbol: "ImageStore.save(references:out:platform:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/save(references:out:platform:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.save(references:out:platform:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:save",
+            "@image-store/example",
+            "example",
+            "--out",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: true),
+        ],
+        options: [
+            .init(names: ["--out"], parameterName: "out", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--platform"], parameterName: "platform", type: "oci-platform", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:load",
+        methodID: "imageStore.load",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:load",
+        ],
+        resource: "image-store",
+        operation: "load",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:load @\n\n[--progress @]\n-> @...",
+        resultType: "reference:image[]",
+        appleAPISymbol: "ImageStore.load(from:progress:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/load(from:progress:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.load(from:progress:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:load",
+            "@image-store/example",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "directory", parameterName: "directory", type: "host-url", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-store:get-init-image",
+        methodID: "imageStore.getInitImage",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-store:get-init-image",
+        ],
+        resource: "image-store",
+        operation: "get-init-image",
+        shape: .reference,
+        signature: "ghostbox cn:image-store:get-init-image @\n\n[--authentication @]\n[--progress @]\n-> @",
+        resultType: "reference:init-image",
+        appleAPISymbol: "ImageStore.getInitImage(reference:auth:progress:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/imagestore/getinitimage(reference:auth:progress:)",
+        swiftModule: nil,
+        swiftSymbol: "ImageStore.getInitImage(reference:auth:progress:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-store:get-init-image",
+            "@image-store/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image-store", parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--authentication"], parameterName: "authentication", type: "reference:authentication", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-description:create",
+        methodID: "imageDescription.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-description:create",
+        ],
+        resource: "image-description",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:image-description:create \n\n\n-> @",
+        resultType: "reference:image-description",
+        appleAPISymbol: "Image.Description.init(reference:descriptor:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/init(reference:descriptor:)",
+        swiftModule: nil,
+        swiftSymbol: "Image.Description.init(reference:descriptor:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-description:create",
+            "example",
+            "example",
+            "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:0000000000000000000000000000000000000000000000000000000000000000\",\"size\":0}",
+        ],
+        positionals: [
+            .init(name: "image-description", parameterName: "imageDescription", type: "name", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+            .init(name: "descriptor", parameterName: "descriptor", type: "oci-descriptor-json", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-description:reference",
+        methodID: "imageDescription.reference",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-description:reference",
+        ],
+        resource: "image-description",
+        operation: "reference",
+        shape: .reference,
+        signature: "ghostbox cn:image-description:reference @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Image.Description.reference",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/reference",
+        swiftModule: nil,
+        swiftSymbol: "Image.Description.reference",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-description:reference",
+            "@image-description/example",
+        ],
+        positionals: [
+            .init(name: "image-description", parameterName: "imageDescription", type: "reference:image-description", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-description:descriptor",
+        methodID: "imageDescription.descriptor",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-description:descriptor",
+        ],
+        resource: "image-description",
+        operation: "descriptor",
+        shape: .reference,
+        signature: "ghostbox cn:image-description:descriptor @ -> ",
+        resultType: "oci-descriptor",
+        appleAPISymbol: "Image.Description.descriptor",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/descriptor",
+        swiftModule: nil,
+        swiftSymbol: "Image.Description.descriptor",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-description:descriptor",
+            "@image-description/example",
+        ],
+        positionals: [
+            .init(name: "image-description", parameterName: "imageDescription", type: "reference:image-description", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-description:digest",
+        methodID: "imageDescription.digest",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-description:digest",
+        ],
+        resource: "image-description",
+        operation: "digest",
+        shape: .reference,
+        signature: "ghostbox cn:image-description:digest @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Image.Description.digest",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/digest",
+        swiftModule: nil,
+        swiftSymbol: "Image.Description.digest",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-description:digest",
+            "@image-description/example",
+        ],
+        positionals: [
+            .init(name: "image-description", parameterName: "imageDescription", type: "reference:image-description", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image-description:media-type",
+        methodID: "imageDescription.mediaType",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image-description:media-type",
+        ],
+        resource: "image-description",
+        operation: "media-type",
+        shape: .reference,
+        signature: "ghostbox cn:image-description:media-type @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Image.Description.mediaType",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/description-swift.struct/mediatype",
+        swiftModule: nil,
+        swiftSymbol: "Image.Description.mediaType",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image-description:media-type",
+            "@image-description/example",
+        ],
+        positionals: [
+            .init(name: "image-description", parameterName: "imageDescription", type: "reference:image-description", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:create",
+        methodID: "image.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:create",
+        ],
+        resource: "image",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:image:create \n@\n@\n-> @",
+        resultType: "reference:image",
+        appleAPISymbol: "Image.init(description:contentStore:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/init(description:contentstore:)",
+        swiftModule: nil,
+        swiftSymbol: "Image.init(description:contentStore:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:create",
+            "example",
+            "@image-description/example",
+            "@content-store/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "name", required: true, repeatable: false),
+            .init(name: "image-description", parameterName: "imageDescription", type: "reference:image-description", required: true, repeatable: false),
+            .init(name: "content-store", parameterName: "contentStore", type: "reference:content-store", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:description",
+        methodID: "image.description",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:description",
+        ],
+        resource: "image",
+        operation: "description",
+        shape: .reference,
+        signature: "ghostbox cn:image:description @ -> ",
+        resultType: "image-description",
+        appleAPISymbol: "Image.description",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/description-swift.property",
+        swiftModule: nil,
+        swiftSymbol: "Image.description",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:description",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:descriptor",
+        methodID: "image.descriptor",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:descriptor",
+        ],
+        resource: "image",
+        operation: "descriptor",
+        shape: .reference,
+        signature: "ghostbox cn:image:descriptor @ -> ",
+        resultType: "oci-descriptor",
+        appleAPISymbol: "Image.descriptor",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/descriptor",
+        swiftModule: nil,
+        swiftSymbol: "Image.descriptor",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:descriptor",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:digest",
+        methodID: "image.digest",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:digest",
+        ],
+        resource: "image",
+        operation: "digest",
+        shape: .reference,
+        signature: "ghostbox cn:image:digest @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Image.digest",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/digest",
+        swiftModule: nil,
+        swiftSymbol: "Image.digest",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:digest",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:media-type",
+        methodID: "image.mediaType",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:media-type",
+        ],
+        resource: "image",
+        operation: "media-type",
+        shape: .reference,
+        signature: "ghostbox cn:image:media-type @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Image.mediaType",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/mediatype",
+        swiftModule: nil,
+        swiftSymbol: "Image.mediaType",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:media-type",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:reference",
+        methodID: "image.reference",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:reference",
+        ],
+        resource: "image",
+        operation: "reference",
+        shape: .reference,
+        signature: "ghostbox cn:image:reference @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Image.reference",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/reference",
+        swiftModule: nil,
+        swiftSymbol: "Image.reference",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:reference",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:index",
+        methodID: "image.index",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:index",
+        ],
+        resource: "image",
+        operation: "index",
+        shape: .reference,
+        signature: "ghostbox cn:image:index @ -> ",
+        resultType: "oci-index",
+        appleAPISymbol: "Image.index()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/index()",
+        swiftModule: nil,
+        swiftSymbol: "Image.index()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:index",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:manifest",
+        methodID: "image.manifest",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:manifest",
+        ],
+        resource: "image",
+        operation: "manifest",
+        shape: .reference,
+        signature: "ghostbox cn:image:manifest @\n\n-> ",
+        resultType: "oci-manifest",
+        appleAPISymbol: "Image.manifest(for:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/manifest(for:)",
+        swiftModule: nil,
+        swiftSymbol: "Image.manifest(for:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:manifest",
+            "@image/example",
+            "linux/arm64",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+            .init(name: "platform", parameterName: "platform", type: "oci-platform", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:descriptor-for",
+        methodID: "image.descriptorFor",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:descriptor-for",
+        ],
+        resource: "image",
+        operation: "descriptor-for",
+        shape: .reference,
+        signature: "ghostbox cn:image:descriptor-for @\n\n-> ",
+        resultType: "oci-descriptor",
+        appleAPISymbol: "Image.descriptor(for:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/descriptor(for:)",
+        swiftModule: nil,
+        swiftSymbol: "Image.descriptor(for:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:descriptor-for",
+            "@image/example",
+            "linux/arm64",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+            .init(name: "platform", parameterName: "platform", type: "oci-platform", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:config",
+        methodID: "image.config",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:config",
+        ],
+        resource: "image",
+        operation: "config",
+        shape: .reference,
+        signature: "ghostbox cn:image:config @\n\n-> ",
+        resultType: "oci-image",
+        appleAPISymbol: "Image.config(for:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/config(for:)",
+        swiftModule: nil,
+        swiftSymbol: "Image.config(for:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:config",
+            "@image/example",
+            "linux/arm64",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+            .init(name: "platform", parameterName: "platform", type: "oci-platform", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:referenced-digests",
+        methodID: "image.referencedDigests",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:referenced-digests",
+        ],
+        resource: "image",
+        operation: "referenced-digests",
+        shape: .reference,
+        signature: "ghostbox cn:image:referenced-digests @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Image.referencedDigests()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/referenceddigests()",
+        swiftModule: nil,
+        swiftSymbol: "Image.referencedDigests()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:referenced-digests",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:image:get-content",
+        methodID: "image.getContent",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:image:get-content",
+        ],
+        resource: "image",
+        operation: "get-content",
+        shape: .reference,
+        signature: "ghostbox cn:image:get-content @\n\n-> @",
+        resultType: "reference:content",
+        appleAPISymbol: "Image.getContent(digest:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/image/getcontent(digest:)",
+        swiftModule: nil,
+        swiftSymbol: "Image.getContent(digest:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:image:get-content",
+            "@image/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+            .init(name: "digest", parameterName: "digest", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:content:path",
+        methodID: "content.path",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:content:path",
+        ],
+        resource: "content",
+        operation: "path",
+        shape: .reference,
+        signature: "ghostbox cn:content:path @ -> ",
+        resultType: "host-url",
+        appleAPISymbol: "Content.path",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/content/path",
+        swiftModule: nil,
+        swiftSymbol: "Content.path",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:content:path",
+            "@content/example",
+        ],
+        positionals: [
+            .init(name: "content", parameterName: "content", type: "reference:content", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:content:digest",
+        methodID: "content.digest",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:content:digest",
+        ],
+        resource: "content",
+        operation: "digest",
+        shape: .reference,
+        signature: "ghostbox cn:content:digest @ -> ",
+        resultType: "sha256-digest",
+        appleAPISymbol: "Content.digest()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/content/digest()",
+        swiftModule: nil,
+        swiftSymbol: "Content.digest()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:content:digest",
+            "@content/example",
+        ],
+        positionals: [
+            .init(name: "content", parameterName: "content", type: "reference:content", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:content:size",
+        methodID: "content.size",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:content:size",
+        ],
+        resource: "content",
+        operation: "size",
+        shape: .reference,
+        signature: "ghostbox cn:content:size @ -> ",
+        resultType: "uint64",
+        appleAPISymbol: "Content.size()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/content/size()",
+        swiftModule: nil,
+        swiftSymbol: "Content.size()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:content:size",
+            "@content/example",
+        ],
+        positionals: [
+            .init(name: "content", parameterName: "content", type: "reference:content", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:content:data",
+        methodID: "content.data",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:content:data",
+        ],
+        resource: "content",
+        operation: "data",
+        shape: .reference,
+        signature: "ghostbox cn:content:data @ -> ",
+        resultType: "byte-stream",
+        appleAPISymbol: "Content.data()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/content/data()",
+        swiftModule: nil,
+        swiftSymbol: "Content.data()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:content:data",
+            "@content/example",
+        ],
+        positionals: [
+            .init(name: "content", parameterName: "content", type: "reference:content", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:content:data-range",
+        methodID: "content.dataRange",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:content:data-range",
+        ],
+        resource: "content",
+        operation: "data-range",
+        shape: .reference,
+        signature: "ghostbox cn:content:data-range @\n\n\n-> |null",
+        resultType: "byte-stream?",
+        appleAPISymbol: "Content.data(offset:length:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/content/data(offset:length:)",
+        swiftModule: nil,
+        swiftSymbol: "Content.data(offset:length:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:content:data-range",
+            "@content/example",
+            "1",
+            "1",
+        ],
+        positionals: [
+            .init(name: "content", parameterName: "content", type: "reference:content", required: true, repeatable: false),
+            .init(name: "offset", parameterName: "offset", type: "uint64", required: true, repeatable: false),
+            .init(name: "length", parameterName: "length", type: "int", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:create",
+        methodID: "kernelCommandLine.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:create",
+        ],
+        resource: "kernel-command-line",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:kernel-command-line:create \n[--kernel-argument ]...\n[--init-argument ]...\n-> @",
+        resultType: "reference:kernel-command-line",
+        appleAPISymbol: "Kernel.CommandLine.init(kernelArgs:initArgs:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/init(kernelargs:initargs:)",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.init(kernelArgs:initArgs:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "command-line", parameterName: "commandLine", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel-argument"], parameterName: "kernelArgument", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--init-argument"], parameterName: "initArgument", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:create-debug",
+        methodID: "kernelCommandLine.createDebug",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:create-debug",
+        ],
+        resource: "kernel-command-line",
+        operation: "create-debug",
+        shape: .create,
+        signature: "ghostbox cn:kernel-command-line:create-debug \n\n\n[--init-argument ]...\n-> @",
+        resultType: "reference:kernel-command-line",
+        appleAPISymbol: "Kernel.CommandLine.init(debug:panic:initArgs:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/init(debug:panic:initargs:)",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.init(debug:panic:initArgs:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:create-debug",
+            "example",
+            "true",
+            "1",
+        ],
+        positionals: [
+            .init(name: "command-line", parameterName: "commandLine", type: "name", required: true, repeatable: false),
+            .init(name: "debug", parameterName: "debug", type: "bool", required: true, repeatable: false),
+            .init(name: "panic", parameterName: "panic", type: "int", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--init-argument"], parameterName: "initArgument", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:add-debug",
+        methodID: "kernelCommandLine.addDebug",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:add-debug",
+        ],
+        resource: "kernel-command-line",
+        operation: "add-debug",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-command-line:add-debug @",
+        resultType: "void",
+        appleAPISymbol: "Kernel.CommandLine.addDebug()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/adddebug()",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.addDebug()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:add-debug",
+            "@kernel-command-line/example",
+        ],
+        positionals: [
+            .init(name: "kernel-command-line", parameterName: "kernelCommandLine", type: "reference:kernel-command-line", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:add-panic",
+        methodID: "kernelCommandLine.addPanic",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:add-panic",
+        ],
+        resource: "kernel-command-line",
+        operation: "add-panic",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-command-line:add-panic @ ",
+        resultType: "void",
+        appleAPISymbol: "Kernel.CommandLine.addPanic(level:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/addpanic(level:)",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.addPanic(level:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:add-panic",
+            "@kernel-command-line/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "kernel-command-line", parameterName: "kernelCommandLine", type: "reference:kernel-command-line", required: true, repeatable: false),
+            .init(name: "level", parameterName: "level", type: "int", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:set-agent-log-level",
+        methodID: "kernelCommandLine.setAgentLogLevel",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:set-agent-log-level",
+        ],
+        resource: "kernel-command-line",
+        operation: "set-agent-log-level",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-command-line:set-agent-log-level @ ",
+        resultType: "void",
+        appleAPISymbol: "Kernel.CommandLine.setAgentLogLevel(level:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/setagentloglevel(level:)",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.setAgentLogLevel(level:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:set-agent-log-level",
+            "@kernel-command-line/example",
+            "info",
+        ],
+        positionals: [
+            .init(name: "kernel-command-line", parameterName: "kernelCommandLine", type: "reference:kernel-command-line", required: true, repeatable: false),
+            .init(name: "level", parameterName: "level", type: "logger-level", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:kernel-arguments",
+        methodID: "kernelCommandLine.kernelArguments",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:kernel-arguments",
+        ],
+        resource: "kernel-command-line",
+        operation: "kernel-arguments",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-command-line:kernel-arguments @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Kernel.CommandLine.kernelArgs",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/kernelargs",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.kernelArgs",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:kernel-arguments",
+            "@kernel-command-line/example",
+        ],
+        positionals: [
+            .init(name: "kernel-command-line", parameterName: "kernelCommandLine", type: "reference:kernel-command-line", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-command-line:init-arguments",
+        methodID: "kernelCommandLine.initArguments",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-command-line:init-arguments",
+        ],
+        resource: "kernel-command-line",
+        operation: "init-arguments",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-command-line:init-arguments @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Kernel.CommandLine.initArgs",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/commandline-swift.struct/initargs",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.CommandLine.initArgs",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-command-line:init-arguments",
+            "@kernel-command-line/example",
+        ],
+        positionals: [
+            .init(name: "kernel-command-line", parameterName: "kernelCommandLine", type: "reference:kernel-command-line", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel:create",
+        methodID: "kernel.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel:create",
+        ],
+        resource: "kernel",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:kernel:create \n--path \n--platform \n[--command-line @]\n-> @",
+        resultType: "reference:kernel",
+        appleAPISymbol: "Kernel.init(path:platform:commandline:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/init(path:platform:commandline:)",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.init(path:platform:commandline:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel:create",
+            "example",
+            "--path",
+            "/tmp/example",
+            "--platform",
+            "linux/arm64",
+        ],
+        positionals: [
+            .init(name: "kernel", parameterName: "kernel", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--path"], parameterName: "path", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--platform"], parameterName: "platform", type: "system-platform", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--command-line"], parameterName: "commandLine", type: "reference:kernel-command-line", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel:path",
+        methodID: "kernel.path",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel:path",
+        ],
+        resource: "kernel",
+        operation: "path",
+        shape: .reference,
+        signature: "ghostbox cn:kernel:path @ -> ",
+        resultType: "host-url",
+        appleAPISymbol: "Kernel.path",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/path",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.path",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel:path",
+            "@kernel/example",
+        ],
+        positionals: [
+            .init(name: "kernel", parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel:platform",
+        methodID: "kernel.platform",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel:platform",
+        ],
+        resource: "kernel",
+        operation: "platform",
+        shape: .reference,
+        signature: "ghostbox cn:kernel:platform @ -> ",
+        resultType: "system-platform",
+        appleAPISymbol: "Kernel.platform",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/platform",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.platform",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel:platform",
+            "@kernel/example",
+        ],
+        positionals: [
+            .init(name: "kernel", parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel:kernel-arguments",
+        methodID: "kernel.kernelArguments",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel:kernel-arguments",
+        ],
+        resource: "kernel",
+        operation: "kernel-arguments",
+        shape: .reference,
+        signature: "ghostbox cn:kernel:kernel-arguments @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Kernel.kernelArgs",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/kernelargs",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.kernelArgs",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel:kernel-arguments",
+            "@kernel/example",
+        ],
+        positionals: [
+            .init(name: "kernel", parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel:init-arguments",
+        methodID: "kernel.initArguments",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel:init-arguments",
+        ],
+        resource: "kernel",
+        operation: "init-arguments",
+        shape: .reference,
+        signature: "ghostbox cn:kernel:init-arguments @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Kernel.initArgs",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernel/initargs",
+        swiftModule: nil,
+        swiftSymbol: "Kernel.initArgs",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel:init-arguments",
+            "@kernel/example",
+        ],
+        positionals: [
+            .init(name: "kernel", parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-image:from-image",
+        methodID: "kernelImage.fromImage",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-image:from-image",
+        ],
+        resource: "kernel-image",
+        operation: "from-image",
+        shape: .create,
+        signature: "ghostbox cn:kernel-image:from-image \n@\n-> @",
+        resultType: "reference:kernel-image",
+        appleAPISymbol: "KernelImage.init(image:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernelimage/init(image:)",
+        swiftModule: nil,
+        swiftSymbol: "KernelImage.init(image:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-image:from-image",
+            "example",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "kernel-image", parameterName: "kernelImage", type: "name", required: true, repeatable: false),
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-image:create",
+        methodID: "kernelImage.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-image:create",
+        ],
+        resource: "kernel-image",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:kernel-image:create \n\n--kernel @...\n[--label ]...\n--image-store @\n--content-store @\n-> @",
+        resultType: "reference:kernel-image",
+        appleAPISymbol: "KernelImage.create(reference:binaries:labels:imageStore:contentStore:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernelimage/create(reference:binaries:labels:imagestore:contentstore:)",
+        swiftModule: nil,
+        swiftSymbol: "KernelImage.create(reference:binaries:labels:imageStore:contentStore:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-image:create",
+            "example",
+            "example",
+            "--kernel",
+            "@kernel/example",
+            "--image-store",
+            "@image-store/example",
+            "--content-store",
+            "@content-store/example",
+        ],
+        positionals: [
+            .init(name: "kernel-image", parameterName: "kernelImage", type: "name", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel"], parameterName: "kernel", type: "reference:kernel", required: true, repeatable: true, defaultValue: nil),
+            .init(names: ["--label"], parameterName: "label", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--image-store"], parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--content-store"], parameterName: "contentStore", type: "reference:content-store", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-image:kernel",
+        methodID: "kernelImage.kernel",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-image:kernel",
+        ],
+        resource: "kernel-image",
+        operation: "kernel",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-image:kernel @\n\n-> @",
+        resultType: "reference:kernel",
+        appleAPISymbol: "KernelImage.kernel(for:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernelimage/kernel(for:)",
+        swiftModule: nil,
+        swiftSymbol: "KernelImage.kernel(for:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-image:kernel",
+            "@kernel-image/example",
+            "linux/arm64",
+        ],
+        positionals: [
+            .init(name: "kernel-image", parameterName: "kernelImage", type: "reference:kernel-image", required: true, repeatable: false),
+            .init(name: "platform", parameterName: "platform", type: "system-platform", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-image:name",
+        methodID: "kernelImage.name",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-image:name",
+        ],
+        resource: "kernel-image",
+        operation: "name",
+        shape: .reference,
+        signature: "ghostbox cn:kernel-image:name @ -> ",
+        resultType: "string",
+        appleAPISymbol: "KernelImage.name",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernelimage/name",
+        swiftModule: nil,
+        swiftSymbol: "KernelImage.name",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-image:name",
+            "@kernel-image/example",
+        ],
+        positionals: [
+            .init(name: "kernel-image", parameterName: "kernelImage", type: "reference:kernel-image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:kernel-image:media-type",
+        methodID: "kernelImage.mediaType",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:kernel-image:media-type",
+        ],
+        resource: "kernel-image",
+        operation: "media-type",
+        shape: .static,
+        signature: "ghostbox cn:kernel-image:media-type -> ",
+        resultType: "string",
+        appleAPISymbol: "KernelImage.mediaType",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/kernelimage/mediatype",
+        swiftModule: nil,
+        swiftSymbol: "KernelImage.mediaType",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:kernel-image:media-type",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:init-image:from-image",
+        methodID: "initImage.fromImage",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:init-image:from-image",
+        ],
+        resource: "init-image",
+        operation: "from-image",
+        shape: .create,
+        signature: "ghostbox cn:init-image:from-image \n@\n-> @",
+        resultType: "reference:init-image",
+        appleAPISymbol: "InitImage.init(image:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/initimage/init(image:)",
+        swiftModule: nil,
+        swiftSymbol: "InitImage.init(image:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:init-image:from-image",
+            "example",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "init-image", parameterName: "initImage", type: "name", required: true, repeatable: false),
+            .init(name: "image", parameterName: "image", type: "reference:image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:init-image:create",
+        methodID: "initImage.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:init-image:create",
+        ],
+        resource: "init-image",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:init-image:create \n\n--rootfs \n--platform \n[--label ]...\n--image-store @\n--content-store @\n-> @",
+        resultType: "reference:init-image",
+        appleAPISymbol: "InitImage.create(reference:rootfs:platform:labels:imageStore:contentStore:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/initimage/create(reference:rootfs:platform:labels:imagestore:contentstore:)",
+        swiftModule: nil,
+        swiftSymbol: "InitImage.create(reference:rootfs:platform:labels:imageStore:contentStore:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:init-image:create",
+            "example",
+            "example",
+            "--rootfs",
+            "/tmp/example",
+            "--platform",
+            "linux/arm64",
+            "--image-store",
+            "@image-store/example",
+            "--content-store",
+            "@content-store/example",
+        ],
+        positionals: [
+            .init(name: "init-image", parameterName: "initImage", type: "name", required: true, repeatable: false),
+            .init(name: "reference", parameterName: "reference", type: "string", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--rootfs"], parameterName: "rootfs", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--platform"], parameterName: "platform", type: "oci-platform", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--label"], parameterName: "label", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--image-store"], parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--content-store"], parameterName: "contentStore", type: "reference:content-store", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:init-image:init-block",
+        methodID: "initImage.initBlock",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:init-image:init-block",
+        ],
+        resource: "init-image",
+        operation: "init-block",
+        shape: .reference,
+        signature: "ghostbox cn:init-image:init-block @\n--at \n--platform \n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "InitImage.initBlock(at:for:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/initimage/initblock(at:for:)",
+        swiftModule: nil,
+        swiftSymbol: "InitImage.initBlock(at:for:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:init-image:init-block",
+            "@init-image/example",
+            "--at",
+            "/tmp/example",
+            "--platform",
+            "linux/arm64",
+        ],
+        positionals: [
+            .init(name: "init-image", parameterName: "initImage", type: "reference:init-image", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--at"], parameterName: "at", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--platform"], parameterName: "platform", type: "system-platform", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:init-image:name",
+        methodID: "initImage.name",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:init-image:name",
+        ],
+        resource: "init-image",
+        operation: "name",
+        shape: .reference,
+        signature: "ghostbox cn:init-image:name @ -> ",
+        resultType: "string",
+        appleAPISymbol: "InitImage.name",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/initimage/name",
+        swiftModule: nil,
+        swiftSymbol: "InitImage.name",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:init-image:name",
+            "@init-image/example",
+        ],
+        positionals: [
+            .init(name: "init-image", parameterName: "initImage", type: "reference:init-image", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:create",
+        methodID: "mount.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:create",
+        ],
+        resource: "mount",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:mount:create \n--type \n--source \n--destination \n--option ...\n--runtime-options \n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "Mount.init(type:source:destination:options:runtimeOptions:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/init(type:source:destination:options:runtimeoptions:)",
+        swiftModule: nil,
+        swiftSymbol: "Mount.init(type:source:destination:options:runtimeOptions:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:create",
+            "example",
+            "--type",
+            "example",
+            "--source",
+            "example",
+            "--destination",
+            "/example",
+            "--option",
+            "example",
+            "--runtime-options",
+            "{}",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--type"], parameterName: "type", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--source"], parameterName: "source", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--destination"], parameterName: "destination", type: "container-path", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--option"], parameterName: "option", type: "string", required: true, repeatable: true, defaultValue: nil),
+            .init(names: ["--runtime-options"], parameterName: "runtimeOptions", type: "mount-runtime-options", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:block",
+        methodID: "mount.block",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:block",
+        ],
+        resource: "mount",
+        operation: "block",
+        shape: .create,
+        signature: "ghostbox cn:mount:block \n--format \n--source \n--destination \n[--option ]...\n[--runtime-option ]...\n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "Mount.block(format:source:destination:options:runtimeOptions:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/block(format:source:destination:options:runtimeoptions:)",
+        swiftModule: nil,
+        swiftSymbol: "Mount.block(format:source:destination:options:runtimeOptions:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:block",
+            "example",
+            "--format",
+            "example",
+            "--source",
+            "example",
+            "--destination",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--format"], parameterName: "format", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--source"], parameterName: "source", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--destination"], parameterName: "destination", type: "container-path", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--option"], parameterName: "option", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--runtime-option"], parameterName: "runtimeOption", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:share",
+        methodID: "mount.share",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:share",
+        ],
+        resource: "mount",
+        operation: "share",
+        shape: .create,
+        signature: "ghostbox cn:mount:share \n--source \n--destination \n[--option ]...\n[--runtime-option ]...\n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "Mount.share(source:destination:options:runtimeOptions:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/share(source:destination:options:runtimeoptions:)",
+        swiftModule: nil,
+        swiftSymbol: "Mount.share(source:destination:options:runtimeOptions:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:share",
+            "example",
+            "--source",
+            "example",
+            "--destination",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--source"], parameterName: "source", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--destination"], parameterName: "destination", type: "container-path", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--option"], parameterName: "option", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--runtime-option"], parameterName: "runtimeOption", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:any",
+        methodID: "mount.any",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:any",
+        ],
+        resource: "mount",
+        operation: "any",
+        shape: .create,
+        signature: "ghostbox cn:mount:any \n--type \n--source \n--destination \n[--option ]...\n[--runtime-option ]...\n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "Mount.any(type:source:destination:options:runtimeOptions:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/any(type:source:destination:options:runtimeoptions:)",
+        swiftModule: nil,
+        swiftSymbol: "Mount.any(type:source:destination:options:runtimeOptions:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:any",
+            "example",
+            "--type",
+            "example",
+            "--source",
+            "example",
+            "--destination",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--type"], parameterName: "type", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--source"], parameterName: "source", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--destination"], parameterName: "destination", type: "container-path", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--option"], parameterName: "option", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--runtime-option"], parameterName: "runtimeOption", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:shared-mount",
+        methodID: "mount.sharedMount",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:shared-mount",
+        ],
+        resource: "mount",
+        operation: "shared-mount",
+        shape: .create,
+        signature: "ghostbox cn:mount:shared-mount \n--name \n--destination \n[--option ]...\n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "Mount.sharedMount(name:destination:options:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/sharedmount(name:destination:options:)",
+        swiftModule: nil,
+        swiftSymbol: "Mount.sharedMount(name:destination:options:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:shared-mount",
+            "example",
+            "--name",
+            "example",
+            "--destination",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--name"], parameterName: "name", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--destination"], parameterName: "destination", type: "container-path", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--option"], parameterName: "option", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:clone",
+        methodID: "mount.clone",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:clone",
+        ],
+        resource: "mount",
+        operation: "clone",
+        shape: .reference,
+        signature: "ghostbox cn:mount:clone @\n--to \n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "Mount.clone(to:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/clone(to:)",
+        swiftModule: nil,
+        swiftSymbol: "Mount.clone(to:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:clone",
+            "@mount/example",
+            "--to",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--to"], parameterName: "to", type: "host-path", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:is-block",
+        methodID: "mount.isBlock",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:is-block",
+        ],
+        resource: "mount",
+        operation: "is-block",
+        shape: .reference,
+        signature: "ghostbox cn:mount:is-block @ -> ",
+        resultType: "bool",
+        appleAPISymbol: "Mount.isBlock",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/isblock",
+        swiftModule: nil,
+        swiftSymbol: "Mount.isBlock",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:is-block",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:type",
+        methodID: "mount.type",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:type",
+        ],
+        resource: "mount",
+        operation: "type",
+        shape: .reference,
+        signature: "ghostbox cn:mount:type @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Mount.type",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/type",
+        swiftModule: nil,
+        swiftSymbol: "Mount.type",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:type",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:source",
+        methodID: "mount.source",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:source",
+        ],
+        resource: "mount",
+        operation: "source",
+        shape: .reference,
+        signature: "ghostbox cn:mount:source @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Mount.source",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/source",
+        swiftModule: nil,
+        swiftSymbol: "Mount.source",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:source",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:destination",
+        methodID: "mount.destination",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:destination",
+        ],
+        resource: "mount",
+        operation: "destination",
+        shape: .reference,
+        signature: "ghostbox cn:mount:destination @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Mount.destination",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/destination",
+        swiftModule: nil,
+        swiftSymbol: "Mount.destination",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:destination",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:options",
+        methodID: "mount.options",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:options",
+        ],
+        resource: "mount",
+        operation: "options",
+        shape: .reference,
+        signature: "ghostbox cn:mount:options @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Mount.options",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/options",
+        swiftModule: nil,
+        swiftSymbol: "Mount.options",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:options",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:mount:runtime-options",
+        methodID: "mount.runtimeOptions",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:mount:runtime-options",
+        ],
+        resource: "mount",
+        operation: "runtime-options",
+        shape: .reference,
+        signature: "ghostbox cn:mount:runtime-options @ -> ",
+        resultType: "mount-runtime-options",
+        appleAPISymbol: "Mount.runtimeOptions",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/mount/runtimeoptions-swift.property",
+        swiftModule: nil,
+        swiftSymbol: "Mount.runtimeOptions",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:mount:runtime-options",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:create",
+        methodID: "dns.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:create",
+        ],
+        resource: "dns",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:dns:create \n[--nameserver ]...\n[--domain ]\n[--search-domain ]...\n[--option ]...\n-> @",
+        resultType: "reference:dns",
+        appleAPISymbol: "DNS.init(nameservers:domain:searchDomains:options:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/init(nameservers:domain:searchdomains:options:)",
+        swiftModule: nil,
+        swiftSymbol: "DNS.init(nameservers:domain:searchDomains:options:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "name", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--nameserver"], parameterName: "nameservers", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--domain"], parameterName: "domain", type: "string", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--search-domain"], parameterName: "searchDomains", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--option"], parameterName: "options", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: ["searchDomains": .array([]), "options": .array([])]
+    ),
+    .init(
+        commandID: "cn:dns:default-nameservers",
+        methodID: "dns.defaultNameservers",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:default-nameservers",
+        ],
+        resource: "dns",
+        operation: "default-nameservers",
+        shape: .static,
+        signature: "ghostbox cn:dns:default-nameservers -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "DNS.defaultNameservers",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/defaultnameservers",
+        swiftModule: nil,
+        swiftSymbol: "DNS.defaultNameservers",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:default-nameservers",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:validate",
+        methodID: "dns.validate",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:validate",
+        ],
+        resource: "dns",
+        operation: "validate",
+        shape: .reference,
+        signature: "ghostbox cn:dns:validate @",
+        resultType: "void",
+        appleAPISymbol: "DNS.validate()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/validate()",
+        swiftModule: nil,
+        swiftSymbol: "DNS.validate()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:validate",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "reference", type: "reference:dns", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:resolv-conf",
+        methodID: "dns.resolvConf",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:resolv-conf",
+        ],
+        resource: "dns",
+        operation: "resolv-conf",
+        shape: .reference,
+        signature: "ghostbox cn:dns:resolv-conf @ -> ",
+        resultType: "string",
+        appleAPISymbol: "DNS.resolvConf",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/resolvconf",
+        swiftModule: nil,
+        swiftSymbol: "DNS.resolvConf",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:resolv-conf",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "reference", type: "reference:dns", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:nameservers",
+        methodID: "dns.nameservers",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:nameservers",
+        ],
+        resource: "dns",
+        operation: "nameservers",
+        shape: .reference,
+        signature: "ghostbox cn:dns:nameservers @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "DNS.nameservers",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/nameservers",
+        swiftModule: nil,
+        swiftSymbol: "DNS.nameservers",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:nameservers",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "reference", type: "reference:dns", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:domain",
+        methodID: "dns.domain",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:domain",
+        ],
+        resource: "dns",
+        operation: "domain",
+        shape: .reference,
+        signature: "ghostbox cn:dns:domain @ -> |null",
+        resultType: "string?",
+        appleAPISymbol: "DNS.domain",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/domain",
+        swiftModule: nil,
+        swiftSymbol: "DNS.domain",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:domain",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "reference", type: "reference:dns", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:search-domains",
+        methodID: "dns.searchDomains",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:search-domains",
+        ],
+        resource: "dns",
+        operation: "search-domains",
+        shape: .reference,
+        signature: "ghostbox cn:dns:search-domains @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "DNS.searchDomains",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/searchdomains",
+        swiftModule: nil,
+        swiftSymbol: "DNS.searchDomains",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:search-domains",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "reference", type: "reference:dns", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:dns:options",
+        methodID: "dns.options",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:dns:options",
+        ],
+        resource: "dns",
+        operation: "options",
+        shape: .reference,
+        signature: "ghostbox cn:dns:options @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "DNS.options",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/dns/options",
+        swiftModule: nil,
+        swiftSymbol: "DNS.options",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:dns:options",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "dns", parameterName: "reference", type: "reference:dns", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:create",
+        methodID: "hostsEntry.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:create",
+        ],
+        resource: "hosts-entry",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:create \n\n...\n[--comment ]\n-> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.init(ipAddress:hostnames:comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/init(ipaddress:hostnames:comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.init(ipAddress:hostnames:comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:create",
+            "example",
+            "example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+            .init(name: "ip-address", parameterName: "ipAddress", type: "string", required: true, repeatable: false),
+            .init(name: "hostname", parameterName: "hostname", type: "string", required: true, repeatable: true),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:localhost-ipv4",
+        methodID: "hostsEntry.localhostIpv4",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:localhost-ipv4",
+        ],
+        resource: "hosts-entry",
+        operation: "localhost-ipv4",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:localhost-ipv4  [--comment ] -> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.localHostIPV4(comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/localhostipv4(comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.localHostIPV4(comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:localhost-ipv4",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:localhost-ipv6",
+        methodID: "hostsEntry.localhostIpv6",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:localhost-ipv6",
+        ],
+        resource: "hosts-entry",
+        operation: "localhost-ipv6",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:localhost-ipv6  [--comment ] -> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.localHostIPV6(comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/localhostipv6(comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.localHostIPV6(comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:localhost-ipv6",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:ipv6-localnet",
+        methodID: "hostsEntry.ipv6Localnet",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:ipv6-localnet",
+        ],
+        resource: "hosts-entry",
+        operation: "ipv6-localnet",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:ipv6-localnet  [--comment ] -> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.ipv6LocalNet(comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6localnet(comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.ipv6LocalNet(comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:ipv6-localnet",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:ipv6-mcastprefix",
+        methodID: "hostsEntry.ipv6Mcastprefix",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:ipv6-mcastprefix",
+        ],
+        resource: "hosts-entry",
+        operation: "ipv6-mcastprefix",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:ipv6-mcastprefix  [--comment ] -> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.ipv6MulticastPrefix(comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6multicastprefix(comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.ipv6MulticastPrefix(comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:ipv6-mcastprefix",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:ipv6-allnodes",
+        methodID: "hostsEntry.ipv6Allnodes",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:ipv6-allnodes",
+        ],
+        resource: "hosts-entry",
+        operation: "ipv6-allnodes",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:ipv6-allnodes  [--comment ] -> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.ipv6AllNodes(comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6allnodes(comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.ipv6AllNodes(comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:ipv6-allnodes",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:ipv6-allrouters",
+        methodID: "hostsEntry.ipv6Allrouters",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:ipv6-allrouters",
+        ],
+        resource: "hosts-entry",
+        operation: "ipv6-allrouters",
+        shape: .create,
+        signature: "ghostbox cn:hosts-entry:ipv6-allrouters  [--comment ] -> @",
+        resultType: "reference:hosts-entry",
+        appleAPISymbol: "Hosts.Entry.ipv6AllRouters(comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipv6allrouters(comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.ipv6AllRouters(comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:ipv6-allrouters",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:rendered",
+        methodID: "hostsEntry.rendered",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:rendered",
+        ],
+        resource: "hosts-entry",
+        operation: "rendered",
+        shape: .reference,
+        signature: "ghostbox cn:hosts-entry:rendered @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Hosts.Entry.rendered",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/rendered",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.rendered",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:rendered",
+            "@hosts-entry/example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "reference:hosts-entry", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:ip-address",
+        methodID: "hostsEntry.ipAddress",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:ip-address",
+        ],
+        resource: "hosts-entry",
+        operation: "ip-address",
+        shape: .reference,
+        signature: "ghostbox cn:hosts-entry:ip-address @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Hosts.Entry.ipAddress",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/ipaddress",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.ipAddress",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:ip-address",
+            "@hosts-entry/example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "reference:hosts-entry", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:hostnames",
+        methodID: "hostsEntry.hostnames",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:hostnames",
+        ],
+        resource: "hosts-entry",
+        operation: "hostnames",
+        shape: .reference,
+        signature: "ghostbox cn:hosts-entry:hostnames @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "Hosts.Entry.hostnames",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/hostnames",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.hostnames",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:hostnames",
+            "@hosts-entry/example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "reference:hosts-entry", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts-entry:comment",
+        methodID: "hostsEntry.comment",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts-entry:comment",
+        ],
+        resource: "hosts-entry",
+        operation: "comment",
+        shape: .reference,
+        signature: "ghostbox cn:hosts-entry:comment @ -> |null",
+        resultType: "string?",
+        appleAPISymbol: "Hosts.Entry.comment",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entry/comment",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.Entry.comment",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts-entry:comment",
+            "@hosts-entry/example",
+        ],
+        positionals: [
+            .init(name: "hosts-entry", parameterName: "hostsEntry", type: "reference:hosts-entry", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts:create",
+        methodID: "hosts.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts:create",
+        ],
+        resource: "hosts",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:hosts:create \n[--entry @]...\n[--comment ]\n-> @",
+        resultType: "reference:hosts",
+        appleAPISymbol: "Hosts.init(entries:comment:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/init(entries:comment:)",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.init(entries:comment:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "hosts", parameterName: "hosts", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--entry"], parameterName: "entry", type: "reference:hosts-entry", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--comment"], parameterName: "comment", type: "string", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts:default",
+        methodID: "hosts.default",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts:default",
+        ],
+        resource: "hosts",
+        operation: "default",
+        shape: .static,
+        signature: "ghostbox cn:hosts:default -> @",
+        resultType: "reference:hosts",
+        appleAPISymbol: "Hosts.default",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/default",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.default",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts:default",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts:hosts-file",
+        methodID: "hosts.hostsFile",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts:hosts-file",
+        ],
+        resource: "hosts",
+        operation: "hosts-file",
+        shape: .reference,
+        signature: "ghostbox cn:hosts:hosts-file @ -> ",
+        resultType: "string",
+        appleAPISymbol: "Hosts.hostsFile",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/hostsfile",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.hostsFile",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts:hosts-file",
+            "@hosts/example",
+        ],
+        positionals: [
+            .init(name: "hosts", parameterName: "hosts", type: "reference:hosts", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts:entries",
+        methodID: "hosts.entries",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts:entries",
+        ],
+        resource: "hosts",
+        operation: "entries",
+        shape: .reference,
+        signature: "ghostbox cn:hosts:entries @ -> @...",
+        resultType: "reference:hosts-entry[]",
+        appleAPISymbol: "Hosts.entries",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/entries",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.entries",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts:entries",
+            "@hosts/example",
+        ],
+        positionals: [
+            .init(name: "hosts", parameterName: "hosts", type: "reference:hosts", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:hosts:comment",
+        methodID: "hosts.comment",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:hosts:comment",
+        ],
+        resource: "hosts",
+        operation: "comment",
+        shape: .reference,
+        signature: "ghostbox cn:hosts:comment @ -> |null",
+        resultType: "string?",
+        appleAPISymbol: "Hosts.comment",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/hosts/comment",
+        swiftModule: nil,
+        swiftSymbol: "Hosts.comment",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:hosts:comment",
+            "@hosts/example",
+        ],
+        positionals: [
+            .init(name: "hosts", parameterName: "hosts", type: "reference:hosts", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:socket:create",
+        methodID: "socket.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:socket:create",
+        ],
+        resource: "socket",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:socket:create \n--source \n--destination \n[--permissions ]\n[--direction ]\n-> @",
+        resultType: "reference:socket",
+        appleAPISymbol: "UnixSocketConfiguration.init(source:destination:permissions:direction:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/init(source:destination:permissions:direction:)",
+        swiftModule: nil,
+        swiftSymbol: "UnixSocketConfiguration.init(source:destination:permissions:direction:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:socket:create",
+            "example",
+            "--source",
+            "/tmp/example",
+            "--destination",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "socket", parameterName: "socket", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--source"], parameterName: "source", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--destination"], parameterName: "destination", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--permissions"], parameterName: "permissions", type: "file-permissions", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--direction"], parameterName: "direction", type: "into|out-of", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:socket:id",
+        methodID: "socket.id",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:socket:id",
+        ],
+        resource: "socket",
+        operation: "id",
+        shape: .reference,
+        signature: "ghostbox cn:socket:id @ -> ",
+        resultType: "string",
+        appleAPISymbol: "UnixSocketConfiguration.id",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/id",
+        swiftModule: nil,
+        swiftSymbol: "UnixSocketConfiguration.id",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:socket:id",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:socket:source",
+        methodID: "socket.source",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:socket:source",
+        ],
+        resource: "socket",
+        operation: "source",
+        shape: .reference,
+        signature: "ghostbox cn:socket:source @ -> ",
+        resultType: "host-url",
+        appleAPISymbol: "UnixSocketConfiguration.source",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/source",
+        swiftModule: nil,
+        swiftSymbol: "UnixSocketConfiguration.source",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:socket:source",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:socket:destination",
+        methodID: "socket.destination",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:socket:destination",
+        ],
+        resource: "socket",
+        operation: "destination",
+        shape: .reference,
+        signature: "ghostbox cn:socket:destination @ -> ",
+        resultType: "host-url",
+        appleAPISymbol: "UnixSocketConfiguration.destination",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/destination",
+        swiftModule: nil,
+        swiftSymbol: "UnixSocketConfiguration.destination",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:socket:destination",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:socket:permissions",
+        methodID: "socket.permissions",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:socket:permissions",
+        ],
+        resource: "socket",
+        operation: "permissions",
+        shape: .reference,
+        signature: "ghostbox cn:socket:permissions @ -> |null",
+        resultType: "file-permissions?",
+        appleAPISymbol: "UnixSocketConfiguration.permissions",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/permissions",
+        swiftModule: nil,
+        swiftSymbol: "UnixSocketConfiguration.permissions",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:socket:permissions",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:socket:direction",
+        methodID: "socket.direction",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:socket:direction",
+        ],
+        resource: "socket",
+        operation: "direction",
+        shape: .reference,
+        signature: "ghostbox cn:socket:direction @ -> ",
+        resultType: "into|out-of",
+        appleAPISymbol: "UnixSocketConfiguration.direction",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/unixsocketconfiguration/direction-swift.property",
+        swiftModule: nil,
+        swiftSymbol: "UnixSocketConfiguration.direction",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:socket:direction",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:boot-log:file",
+        methodID: "bootLog.file",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:boot-log:file",
+        ],
+        resource: "boot-log",
+        operation: "file",
+        shape: .create,
+        signature: "ghostbox cn:boot-log:file \n--path \n[--append=true]\n-> @",
+        resultType: "reference:boot-log",
+        appleAPISymbol: "BootLog.file(path:append:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/bootlog/file(path:append:)",
+        swiftModule: nil,
+        swiftSymbol: "BootLog.file(path:append:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:boot-log:file",
+            "example",
+            "--path",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "boot-log", parameterName: "bootLog", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--path"], parameterName: "path", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--append"], parameterName: "append", type: "bool", required: false, repeatable: false, defaultValue: .boolean(true)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:vmnet-create",
+        methodID: "network.vmnetCreate",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:vmnet-create",
+        ],
+        resource: "network",
+        operation: "vmnet-create",
+        shape: .create,
+        signature: "ghostbox cn:network:vmnet-create \n[--mode=shared]\n[--subnet ]\n[--prefix-v6 ]\n-> @",
+        resultType: "reference:network",
+        appleAPISymbol: "VmnetNetwork.init(mode:subnet:prefixV6:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/init(mode:subnet:prefixv6:)",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.init(mode:subnet:prefixV6:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:vmnet-create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--mode"], parameterName: "mode", type: "network-mode", required: false, repeatable: false, defaultValue: .string("shared")),
+            .init(names: ["--subnet"], parameterName: "subnet", type: "cidrv4", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--prefix-v6"], parameterName: "prefixV6", type: "cidrv6", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:subnet",
+        methodID: "network.subnet",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:subnet",
+        ],
+        resource: "network",
+        operation: "subnet",
+        shape: .reference,
+        signature: "ghostbox cn:network:subnet @ -> ",
+        resultType: "cidrv4",
+        appleAPISymbol: "VmnetNetwork.subnet",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/subnet",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.subnet",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:subnet",
+            "@network/example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:prefix-v6",
+        methodID: "network.prefixV6",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:prefix-v6",
+        ],
+        resource: "network",
+        operation: "prefix-v6",
+        shape: .reference,
+        signature: "ghostbox cn:network:prefix-v6 @ -> |null",
+        resultType: "cidrv6?",
+        appleAPISymbol: "VmnetNetwork.prefixV6",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/prefixv6",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.prefixV6",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:prefix-v6",
+            "@network/example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:ipv4-gateway",
+        methodID: "network.ipv4Gateway",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:ipv4-gateway",
+        ],
+        resource: "network",
+        operation: "ipv4-gateway",
+        shape: .reference,
+        signature: "ghostbox cn:network:ipv4-gateway @ -> ",
+        resultType: "ipv4-address",
+        appleAPISymbol: "VmnetNetwork.ipv4Gateway",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/ipv4gateway",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.ipv4Gateway",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:ipv4-gateway",
+            "@network/example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:ipv6-gateway",
+        methodID: "network.ipv6Gateway",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:ipv6-gateway",
+        ],
+        resource: "network",
+        operation: "ipv6-gateway",
+        shape: .reference,
+        signature: "ghostbox cn:network:ipv6-gateway @ -> |null",
+        resultType: "ipv6-address?",
+        appleAPISymbol: "VmnetNetwork.ipv6Gateway",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/ipv6gateway",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.ipv6Gateway",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:ipv6-gateway",
+            "@network/example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:create-interface",
+        methodID: "network.createInterface",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:create-interface",
+        ],
+        resource: "network",
+        operation: "create-interface",
+        shape: .reference,
+        signature: "ghostbox cn:network:create-interface @\n\n-> @|null",
+        resultType: "reference:interface?",
+        appleAPISymbol: "VmnetNetwork.createInterface(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/createinterface(_:)",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.createInterface(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:create-interface",
+            "@network/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+            .init(name: "interface", parameterName: "interface", type: "name", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:create-interface-mtu",
+        methodID: "network.createInterfaceMtu",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:create-interface-mtu",
+        ],
+        resource: "network",
+        operation: "create-interface-mtu",
+        shape: .reference,
+        signature: "ghostbox cn:network:create-interface-mtu @\n\n\n-> @|null",
+        resultType: "reference:interface?",
+        appleAPISymbol: "VmnetNetwork.createInterface(_:mtu:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/createinterface(_:mtu:)",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.createInterface(_:mtu:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:create-interface-mtu",
+            "@network/example",
+            "example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+            .init(name: "interface", parameterName: "interface", type: "name", required: true, repeatable: false),
+            .init(name: "mtu", parameterName: "mtu", type: "uint32", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:create-interface-without-gateway",
+        methodID: "network.createInterfaceWithoutGateway",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:create-interface-without-gateway",
+        ],
+        resource: "network",
+        operation: "create-interface-without-gateway",
+        shape: .reference,
+        signature: "ghostbox cn:network:create-interface-without-gateway @\n\n-> @|null",
+        resultType: "reference:interface?",
+        appleAPISymbol: "VmnetNetwork.createInterfaceWithoutGateway(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/createinterfacewithoutgateway(_:)",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.createInterfaceWithoutGateway(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:create-interface-without-gateway",
+            "@network/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+            .init(name: "interface", parameterName: "interface", type: "name", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:network:release-interface",
+        methodID: "network.releaseInterface",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:network:release-interface",
+        ],
+        resource: "network",
+        operation: "release-interface",
+        shape: .reference,
+        signature: "ghostbox cn:network:release-interface @ @",
+        resultType: "void",
+        appleAPISymbol: "VmnetNetwork.releaseInterface(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmnetnetwork/releaseinterface(_:)",
+        swiftModule: nil,
+        swiftSymbol: "VmnetNetwork.releaseInterface(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:network:release-interface",
+            "@network/example",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "network", parameterName: "network", type: "reference:network", required: true, repeatable: false),
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:nat-create",
+        methodID: "interface.natCreate",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:nat-create",
+        ],
+        resource: "interface",
+        operation: "nat-create",
+        shape: .create,
+        signature: "ghostbox cn:interface:nat-create \n--ipv4-address \n[--ipv4-gateway ]\n[--ipv6-address ]\n[--ipv6-gateway ]\n[--mac-address ]\n[--mtu=1500]\n-> @",
+        resultType: "reference:interface",
+        appleAPISymbol: "NATInterface.init(ipv4Address:ipv4Gateway:ipv6Address:ipv6Gateway:macAddress:mtu:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/natinterface/init(ipv4address:ipv4gateway:ipv6address:ipv6gateway:macaddress:mtu:)",
+        swiftModule: nil,
+        swiftSymbol: "NATInterface.init(ipv4Address:ipv4Gateway:ipv6Address:ipv6Gateway:macAddress:mtu:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:nat-create",
+            "example",
+            "--ipv4-address",
+            "192.0.2.2/24",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--ipv4-address"], parameterName: "ipv4Address", type: "cidrv4", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--ipv4-gateway"], parameterName: "ipv4Gateway", type: "ipv4-address", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--ipv6-address"], parameterName: "ipv6Address", type: "cidrv6", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--ipv6-gateway"], parameterName: "ipv6Gateway", type: "ipv6-address", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--mac-address"], parameterName: "macAddress", type: "mac-address", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--mtu"], parameterName: "mtu", type: "uint32", required: false, repeatable: false, defaultValue: .unsignedInteger(1500)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:ipv4-address",
+        methodID: "interface.ipv4Address",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:ipv4-address",
+        ],
+        resource: "interface",
+        operation: "ipv4-address",
+        shape: .reference,
+        signature: "ghostbox cn:interface:ipv4-address @ -> ",
+        resultType: "cidrv4",
+        appleAPISymbol: "Interface.ipv4Address",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/interface/ipv4address",
+        swiftModule: nil,
+        swiftSymbol: "Interface.ipv4Address",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:ipv4-address",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:ipv4-gateway",
+        methodID: "interface.ipv4Gateway",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:ipv4-gateway",
+        ],
+        resource: "interface",
+        operation: "ipv4-gateway",
+        shape: .reference,
+        signature: "ghostbox cn:interface:ipv4-gateway @ -> |null",
+        resultType: "ipv4-address?",
+        appleAPISymbol: "Interface.ipv4Gateway",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/interface/ipv4gateway",
+        swiftModule: nil,
+        swiftSymbol: "Interface.ipv4Gateway",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:ipv4-gateway",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:ipv6-address",
+        methodID: "interface.ipv6Address",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:ipv6-address",
+        ],
+        resource: "interface",
+        operation: "ipv6-address",
+        shape: .reference,
+        signature: "ghostbox cn:interface:ipv6-address @ -> |null",
+        resultType: "cidrv6?",
+        appleAPISymbol: "Interface.ipv6Address",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/interface/ipv6address",
+        swiftModule: nil,
+        swiftSymbol: "Interface.ipv6Address",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:ipv6-address",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:ipv6-gateway",
+        methodID: "interface.ipv6Gateway",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:ipv6-gateway",
+        ],
+        resource: "interface",
+        operation: "ipv6-gateway",
+        shape: .reference,
+        signature: "ghostbox cn:interface:ipv6-gateway @ -> |null",
+        resultType: "ipv6-address?",
+        appleAPISymbol: "Interface.ipv6Gateway",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/interface/ipv6gateway",
+        swiftModule: nil,
+        swiftSymbol: "Interface.ipv6Gateway",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:ipv6-gateway",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:mac-address",
+        methodID: "interface.macAddress",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:mac-address",
+        ],
+        resource: "interface",
+        operation: "mac-address",
+        shape: .reference,
+        signature: "ghostbox cn:interface:mac-address @ -> |null",
+        resultType: "mac-address?",
+        appleAPISymbol: "Interface.macAddress",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/interface/macaddress",
+        swiftModule: nil,
+        swiftSymbol: "Interface.macAddress",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:mac-address",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:interface:mtu",
+        methodID: "interface.mtu",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:interface:mtu",
+        ],
+        resource: "interface",
+        operation: "mtu",
+        shape: .reference,
+        signature: "ghostbox cn:interface:mtu @ -> ",
+        resultType: "uint32",
+        appleAPISymbol: "Interface.mtu",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/interface/mtu",
+        swiftModule: nil,
+        swiftSymbol: "Interface.mtu",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:interface:mtu",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-config:create",
+        methodID: "vmConfig.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-config:create",
+        ],
+        resource: "vm-config",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:vm-config:create \n[--cpus=4]\n[--memory=1073741824]\n[--interface @]...\n[--mount =@]...\n[--boot-log @]\n[--nested-virtualization=false]\n-> @",
+        resultType: "reference:vm-config",
+        appleAPISymbol: "VMConfiguration.init(cpus:memoryInBytes:interfaces:mountsByID:bootLog:nestedVirtualization:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vmconfiguration/init(cpus:memoryinbytes:interfaces:mountsbyid:bootlog:nestedvirtualization:)",
+        swiftModule: nil,
+        swiftSymbol: "VMConfiguration.init(cpus:memoryInBytes:interfaces:mountsByID:bootLog:nestedVirtualization:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-config:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "vm-config", parameterName: "vmConfig", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--cpus"], parameterName: "cpus", type: "int", required: false, repeatable: false, defaultValue: .integer(4)),
+            .init(names: ["--memory"], parameterName: "memory", type: "uint64", required: false, repeatable: false, defaultValue: .unsignedInteger(1073741824)),
+            .init(names: ["--interface"], parameterName: "interface", type: "reference:interface", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--mount"], parameterName: "mount", type: "string=reference:mount", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--boot-log"], parameterName: "bootLog", type: "reference:boot-log", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--nested-virtualization"], parameterName: "nestedVirtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:standard-vm-config:create",
+        methodID: "standardVmConfig.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:standard-vm-config:create",
+        ],
+        resource: "standard-vm-config",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:standard-vm-config:create \n@\n-> @",
+        resultType: "reference:standard-vm-config",
+        appleAPISymbol: "StandardVMConfig.init(configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/standardvmconfig/init(configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "StandardVMConfig.init(configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:standard-vm-config:create",
+            "example",
+            "@vm-config/example",
+        ],
+        positionals: [
+            .init(name: "standard-vm-config", parameterName: "standardVmConfig", type: "name", required: true, repeatable: false),
+            .init(name: "vm-config", parameterName: "vmConfig", type: "reference:vm-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vmm:create",
+        methodID: "vmm.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vmm:create",
+        ],
+        resource: "vmm",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:vmm:create \n--kernel @\n--initial-filesystem @\n[--rosetta=false]\n[--nested-virtualization=false]\n-> @",
+        resultType: "reference:vmm",
+        appleAPISymbol: "VZVirtualMachineManager.init(kernel:initialFilesystem:rosetta:nestedVirtualization:group:logger:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vzvirtualmachinemanager/init(kernel:initialfilesystem:rosetta:nestedvirtualization:group:logger:)",
+        swiftModule: nil,
+        swiftSymbol: "VZVirtualMachineManager.init(kernel:initialFilesystem:rosetta:nestedVirtualization:group:logger:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vmm:create",
+            "example",
+            "--kernel",
+            "@kernel/example",
+            "--initial-filesystem",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "vmm", parameterName: "vmm", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel"], parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--initial-filesystem"], parameterName: "initialFilesystem", type: "reference:mount", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--rosetta"], parameterName: "rosetta", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--nested-virtualization"], parameterName: "nestedVirtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vmm:create-instance",
+        methodID: "vmm.createInstance",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vmm:create-instance",
+        ],
+        resource: "vmm",
+        operation: "create-instance",
+        shape: .reference,
+        signature: "ghostbox cn:vmm:create-instance @\n@\n-> @",
+        resultType: "reference:vm-instance",
+        appleAPISymbol: "VZVirtualMachineManager.create(config:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/vzvirtualmachinemanager/create(config:)",
+        swiftModule: nil,
+        swiftSymbol: "VZVirtualMachineManager.create(config:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vmm:create-instance",
+            "@vmm/example",
+            "@standard-vm-config/example",
+        ],
+        positionals: [
+            .init(name: "vmm", parameterName: "vmm", type: "reference:vmm", required: true, repeatable: false),
+            .init(name: "standard-vm-config", parameterName: "standardVmConfig", type: "reference:standard-vm-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:state",
+        methodID: "vmInstance.state",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:state",
+        ],
+        resource: "vm-instance",
+        operation: "state",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:state @ -> ",
+        resultType: "vm-state",
+        appleAPISymbol: "VirtualMachineInstance.state",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/state",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.state",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:state",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:mounts",
+        methodID: "vmInstance.mounts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:mounts",
+        ],
+        resource: "vm-instance",
+        operation: "mounts",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:mounts @ -> ",
+        resultType: "attached-filesystem-map",
+        appleAPISymbol: "VirtualMachineInstance.mounts",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/mounts",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.mounts",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:mounts",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:virtiofs-layout",
+        methodID: "vmInstance.virtiofsLayout",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:virtiofs-layout",
+        ],
+        resource: "vm-instance",
+        operation: "virtiofs-layout",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:virtiofs-layout @ -> ",
+        resultType: "virtiofs-layout",
+        appleAPISymbol: "VirtualMachineInstance.virtiofsLayout",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/virtiofslayout",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.virtiofsLayout",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:virtiofs-layout",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:start",
+        methodID: "vmInstance.start",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:start",
+        ],
+        resource: "vm-instance",
+        operation: "start",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:start @",
+        resultType: "void",
+        appleAPISymbol: "VirtualMachineInstance.start()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/start()",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.start()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:start",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:stop",
+        methodID: "vmInstance.stop",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:stop",
+        ],
+        resource: "vm-instance",
+        operation: "stop",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:stop @",
+        resultType: "void",
+        appleAPISymbol: "VirtualMachineInstance.stop()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/stop()",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.stop()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:stop",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:pause",
+        methodID: "vmInstance.pause",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:pause",
+        ],
+        resource: "vm-instance",
+        operation: "pause",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:pause @",
+        resultType: "void",
+        appleAPISymbol: "VirtualMachineInstance.pause()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/pause()",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.pause()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:pause",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:resume",
+        methodID: "vmInstance.resume",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:resume",
+        ],
+        resource: "vm-instance",
+        operation: "resume",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:resume @",
+        resultType: "void",
+        appleAPISymbol: "VirtualMachineInstance.resume()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/resume()",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.resume()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:resume",
+            "@vm-instance/example",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:vm-instance:dial",
+        methodID: "vmInstance.dial",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:vm-instance:dial",
+        ],
+        resource: "vm-instance",
+        operation: "dial",
+        shape: .reference,
+        signature: "ghostbox cn:vm-instance:dial @\n\n-> @",
+        resultType: "reference:file-handle",
+        appleAPISymbol: "VirtualMachineInstance.dial(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/virtualmachineinstance/dial(_:)",
+        swiftModule: nil,
+        swiftSymbol: "VirtualMachineInstance.dial(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:vm-instance:dial",
+            "@vm-instance/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "vm-instance", parameterName: "vmInstance", type: "reference:vm-instance", required: true, repeatable: false),
+            .init(name: "port", parameterName: "port", type: "uint32", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit-kind:create",
+        methodID: "rlimitKind.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit-kind:create",
+        ],
+        resource: "rlimit-kind",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:rlimit-kind:create \n\n-> @",
+        resultType: "reference:rlimit-kind",
+        appleAPISymbol: "LinuxRLimit.Kind.init(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/kind-swift.struct/init(_:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.Kind.init(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit-kind:create",
+            "example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "rlimit-kind", parameterName: "rlimitKind", type: "name", required: true, repeatable: false),
+            .init(name: "oci-name", parameterName: "ociName", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit:create",
+        methodID: "rlimit.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit:create",
+        ],
+        resource: "rlimit",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:rlimit:create \n--kind @\n--hard \n--soft \n-> @",
+        resultType: "reference:rlimit",
+        appleAPISymbol: "LinuxRLimit.init(kind:hard:soft:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/init(kind:hard:soft:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.init(kind:hard:soft:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit:create",
+            "example",
+            "--kind",
+            "@rlimit-kind/example",
+            "--hard",
+            "1",
+            "--soft",
+            "1",
+        ],
+        positionals: [
+            .init(name: "rlimit", parameterName: "rlimit", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kind"], parameterName: "kind", type: "reference:rlimit-kind", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--hard"], parameterName: "hard", type: "uint64", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--soft"], parameterName: "soft", type: "uint64", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit:create-equal",
+        methodID: "rlimit.createEqual",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit:create-equal",
+        ],
+        resource: "rlimit",
+        operation: "create-equal",
+        shape: .create,
+        signature: "ghostbox cn:rlimit:create-equal \n--kind @\n--limit \n-> @",
+        resultType: "reference:rlimit",
+        appleAPISymbol: "LinuxRLimit.init(kind:limit:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/init(kind:limit:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.init(kind:limit:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit:create-equal",
+            "example",
+            "--kind",
+            "@rlimit-kind/example",
+            "--limit",
+            "1",
+        ],
+        positionals: [
+            .init(name: "rlimit", parameterName: "rlimit", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kind"], parameterName: "kind", type: "reference:rlimit-kind", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--limit"], parameterName: "limit", type: "uint64", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit:kind",
+        methodID: "rlimit.kind",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit:kind",
+        ],
+        resource: "rlimit",
+        operation: "kind",
+        shape: .reference,
+        signature: "ghostbox cn:rlimit:kind @ -> @",
+        resultType: "reference:rlimit-kind",
+        appleAPISymbol: "LinuxRLimit.kind",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/kind-swift.property",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.kind",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit:kind",
+            "@rlimit/example",
+        ],
+        positionals: [
+            .init(name: "rlimit", parameterName: "rlimit", type: "reference:rlimit", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit:hard",
+        methodID: "rlimit.hard",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit:hard",
+        ],
+        resource: "rlimit",
+        operation: "hard",
+        shape: .reference,
+        signature: "ghostbox cn:rlimit:hard @ -> ",
+        resultType: "uint64",
+        appleAPISymbol: "LinuxRLimit.hard",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/hard",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.hard",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit:hard",
+            "@rlimit/example",
+        ],
+        positionals: [
+            .init(name: "rlimit", parameterName: "rlimit", type: "reference:rlimit", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit:soft",
+        methodID: "rlimit.soft",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit:soft",
+        ],
+        resource: "rlimit",
+        operation: "soft",
+        shape: .reference,
+        signature: "ghostbox cn:rlimit:soft @ -> ",
+        resultType: "uint64",
+        appleAPISymbol: "LinuxRLimit.soft",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/soft",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.soft",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit:soft",
+            "@rlimit/example",
+        ],
+        positionals: [
+            .init(name: "rlimit", parameterName: "rlimit", type: "reference:rlimit", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:rlimit:to-oci",
+        methodID: "rlimit.toOCI",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:rlimit:to-oci",
+        ],
+        resource: "rlimit",
+        operation: "to-oci",
+        shape: .reference,
+        signature: "ghostbox cn:rlimit:to-oci @ -> ",
+        resultType: "oci-posix-rlimit",
+        appleAPISymbol: "LinuxRLimit.toOCI()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxrlimit/tooci()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxRLimit.toOCI()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:rlimit:to-oci",
+            "@rlimit/example",
+        ],
+        positionals: [
+            .init(name: "rlimit", parameterName: "rlimit", type: "reference:rlimit", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:create",
+        methodID: "capabilities.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:create",
+        ],
+        resource: "capabilities",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:capabilities:create \n[--bounding ]...\n[--effective ]...\n[--inheritable ]...\n[--permitted ]...\n[--ambient ]...\n-> @",
+        resultType: "reference:capabilities",
+        appleAPISymbol: "LinuxCapabilities.init(bounding:effective:inheritable:permitted:ambient:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/init(bounding:effective:inheritable:permitted:ambient:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.init(bounding:effective:inheritable:permitted:ambient:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--bounding"], parameterName: "bounding", type: "linux-capability", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--effective"], parameterName: "effective", type: "linux-capability", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--inheritable"], parameterName: "inheritable", type: "linux-capability", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--permitted"], parameterName: "permitted", type: "linux-capability", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--ambient"], parameterName: "ambient", type: "linux-capability", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:create-uniform",
+        methodID: "capabilities.createUniform",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:create-uniform",
+        ],
+        resource: "capabilities",
+        operation: "create-uniform",
+        shape: .create,
+        signature: "ghostbox cn:capabilities:create-uniform \n...\n-> @",
+        resultType: "reference:capabilities",
+        appleAPISymbol: "LinuxCapabilities.init(capabilities:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/init(capabilities:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.init(capabilities:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:create-uniform",
+            "example",
+            "CAP_CHOWN",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "name", required: true, repeatable: false),
+            .init(name: "capability", parameterName: "capability", type: "linux-capability", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:all",
+        methodID: "capabilities.all",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:all",
+        ],
+        resource: "capabilities",
+        operation: "all",
+        shape: .static,
+        signature: "ghostbox cn:capabilities:all -> @",
+        resultType: "reference:capabilities",
+        appleAPISymbol: "LinuxCapabilities.allCapabilities",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/allcapabilities",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.allCapabilities",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:all",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:default-oci",
+        methodID: "capabilities.defaultOCI",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:default-oci",
+        ],
+        resource: "capabilities",
+        operation: "default-oci",
+        shape: .static,
+        signature: "ghostbox cn:capabilities:default-oci -> @",
+        resultType: "reference:capabilities",
+        appleAPISymbol: "LinuxCapabilities.defaultOCICapabilities",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/defaultocicapabilities",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.defaultOCICapabilities",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:default-oci",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:bounding",
+        methodID: "capabilities.bounding",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:bounding",
+        ],
+        resource: "capabilities",
+        operation: "bounding",
+        shape: .reference,
+        signature: "ghostbox cn:capabilities:bounding @ -> ...",
+        resultType: "linux-capability[]",
+        appleAPISymbol: "LinuxCapabilities.bounding",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/bounding",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.bounding",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:bounding",
+            "@capabilities/example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "reference:capabilities", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:effective",
+        methodID: "capabilities.effective",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:effective",
+        ],
+        resource: "capabilities",
+        operation: "effective",
+        shape: .reference,
+        signature: "ghostbox cn:capabilities:effective @ -> ...",
+        resultType: "linux-capability[]",
+        appleAPISymbol: "LinuxCapabilities.effective",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/effective",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.effective",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:effective",
+            "@capabilities/example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "reference:capabilities", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:inheritable",
+        methodID: "capabilities.inheritable",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:inheritable",
+        ],
+        resource: "capabilities",
+        operation: "inheritable",
+        shape: .reference,
+        signature: "ghostbox cn:capabilities:inheritable @ -> ...",
+        resultType: "linux-capability[]",
+        appleAPISymbol: "LinuxCapabilities.inheritable",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/inheritable",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.inheritable",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:inheritable",
+            "@capabilities/example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "reference:capabilities", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:permitted",
+        methodID: "capabilities.permitted",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:permitted",
+        ],
+        resource: "capabilities",
+        operation: "permitted",
+        shape: .reference,
+        signature: "ghostbox cn:capabilities:permitted @ -> ...",
+        resultType: "linux-capability[]",
+        appleAPISymbol: "LinuxCapabilities.permitted",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/permitted",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.permitted",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:permitted",
+            "@capabilities/example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "reference:capabilities", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:ambient",
+        methodID: "capabilities.ambient",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:ambient",
+        ],
+        resource: "capabilities",
+        operation: "ambient",
+        shape: .reference,
+        signature: "ghostbox cn:capabilities:ambient @ -> ...",
+        resultType: "linux-capability[]",
+        appleAPISymbol: "LinuxCapabilities.ambient",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/ambient",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.ambient",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:ambient",
+            "@capabilities/example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "reference:capabilities", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:capabilities:to-oci",
+        methodID: "capabilities.toOCI",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:capabilities:to-oci",
+        ],
+        resource: "capabilities",
+        operation: "to-oci",
+        shape: .reference,
+        signature: "ghostbox cn:capabilities:to-oci @ -> ",
+        resultType: "oci-linux-capabilities",
+        appleAPISymbol: "LinuxCapabilities.toOCI()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcapabilities/tooci()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxCapabilities.toOCI()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:capabilities:to-oci",
+            "@capabilities/example",
+        ],
+        positionals: [
+            .init(name: "capabilities", parameterName: "capabilities", type: "reference:capabilities", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:default-path",
+        methodID: "processConfig.defaultPath",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:default-path",
+        ],
+        resource: "process-config",
+        operation: "default-path",
+        shape: .static,
+        signature: "ghostbox cn:process-config:default-path -> ",
+        resultType: "string",
+        appleAPISymbol: "LinuxProcessConfiguration.defaultPath",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/defaultpath",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.defaultPath",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:default-path",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:create",
+        methodID: "processConfig.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:create",
+        ],
+        resource: "process-config",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:process-config:create \n...\n[--environment ]...\n[--working-directory=/]\n[--user ]\n[--rlimit @]...\n[--no-new-privileges=false]\n[--capabilities @]\n[--terminal=false]\n[--stdin @]\n[--stdout @]\n[--stderr @]\n-> @",
+        resultType: "reference:process-config",
+        appleAPISymbol: "LinuxProcessConfiguration.init(arguments:environmentVariables:workingDirectory:user:rlimits:noNewPrivileges:capabilities:terminal:stdin:stdout:stderr:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/init(arguments:environmentvariables:workingdirectory:user:rlimits:nonewprivileges:capabilities:terminal:stdin:stdout:stderr:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.init(arguments:environmentVariables:workingDirectory:user:rlimits:noNewPrivileges:capabilities:terminal:stdin:stdout:stderr:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:create",
+            "example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "name", required: true, repeatable: false),
+            .init(name: "argument", parameterName: "argument", type: "string", required: true, repeatable: true),
+        ],
+        options: [
+            .init(names: ["--environment"], parameterName: "environment", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--working-directory"], parameterName: "workingDirectory", type: "string", required: false, repeatable: false, defaultValue: .string("/")),
+            .init(names: ["--user"], parameterName: "user", type: "oci-user", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--rlimit"], parameterName: "rlimit", type: "reference:rlimit", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--no-new-privileges"], parameterName: "noNewPrivileges", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--capabilities"], parameterName: "capabilities", type: "reference:capabilities", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--terminal"], parameterName: "terminal", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--stdin"], parameterName: "stdin", type: "reference:reader-stream", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--stdout"], parameterName: "stdout", type: "reference:writer", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--stderr"], parameterName: "stderr", type: "reference:writer", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:from-image-config",
+        methodID: "processConfig.fromImageConfig",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:from-image-config",
+        ],
+        resource: "process-config",
+        operation: "from-image-config",
+        shape: .create,
+        signature: "ghostbox cn:process-config:from-image-config \n\n-> @",
+        resultType: "reference:process-config",
+        appleAPISymbol: "LinuxProcessConfiguration.init(from:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/init(from:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.init(from:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:from-image-config",
+            "example",
+            "{}",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "name", required: true, repeatable: false),
+            .init(name: "image-config", parameterName: "imageConfig", type: "oci-image-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:set-terminal-io",
+        methodID: "processConfig.setTerminalIo",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:set-terminal-io",
+        ],
+        resource: "process-config",
+        operation: "set-terminal-io",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:set-terminal-io @\n@",
+        resultType: "void",
+        appleAPISymbol: "LinuxProcessConfiguration.setTerminalIO(terminal:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/setterminalio(terminal:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.setTerminalIO(terminal:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:set-terminal-io",
+            "@process-config/example",
+            "@terminal/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+            .init(name: "terminal", parameterName: "terminal", type: "reference:terminal", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:arguments",
+        methodID: "processConfig.arguments",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:arguments",
+        ],
+        resource: "process-config",
+        operation: "arguments",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:arguments @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "LinuxProcessConfiguration.arguments",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/arguments",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.arguments",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:arguments",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:environment-variables",
+        methodID: "processConfig.environmentVariables",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:environment-variables",
+        ],
+        resource: "process-config",
+        operation: "environment-variables",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:environment-variables @ -> ...",
+        resultType: "string[]",
+        appleAPISymbol: "LinuxProcessConfiguration.environmentVariables",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/environmentvariables",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.environmentVariables",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:environment-variables",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:working-directory",
+        methodID: "processConfig.workingDirectory",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:working-directory",
+        ],
+        resource: "process-config",
+        operation: "working-directory",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:working-directory @ -> ",
+        resultType: "string",
+        appleAPISymbol: "LinuxProcessConfiguration.workingDirectory",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/workingdirectory",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.workingDirectory",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:working-directory",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:user",
+        methodID: "processConfig.user",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:user",
+        ],
+        resource: "process-config",
+        operation: "user",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:user @ -> ",
+        resultType: "oci-user",
+        appleAPISymbol: "LinuxProcessConfiguration.user",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/user",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.user",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:user",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:rlimits",
+        methodID: "processConfig.rlimits",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:rlimits",
+        ],
+        resource: "process-config",
+        operation: "rlimits",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:rlimits @ -> @...",
+        resultType: "reference:rlimit[]",
+        appleAPISymbol: "LinuxProcessConfiguration.rlimits",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/rlimits",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.rlimits",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:rlimits",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:no-new-privileges",
+        methodID: "processConfig.noNewPrivileges",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:no-new-privileges",
+        ],
+        resource: "process-config",
+        operation: "no-new-privileges",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:no-new-privileges @ -> ",
+        resultType: "bool",
+        appleAPISymbol: "LinuxProcessConfiguration.noNewPrivileges",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/nonewprivileges",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.noNewPrivileges",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:no-new-privileges",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:capabilities",
+        methodID: "processConfig.capabilities",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:capabilities",
+        ],
+        resource: "process-config",
+        operation: "capabilities",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:capabilities @ -> @",
+        resultType: "reference:capabilities",
+        appleAPISymbol: "LinuxProcessConfiguration.capabilities",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/capabilities",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.capabilities",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:capabilities",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:terminal",
+        methodID: "processConfig.terminal",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:terminal",
+        ],
+        resource: "process-config",
+        operation: "terminal",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:terminal @ -> ",
+        resultType: "bool",
+        appleAPISymbol: "LinuxProcessConfiguration.terminal",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/terminal",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.terminal",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:terminal",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:stdin",
+        methodID: "processConfig.stdin",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:stdin",
+        ],
+        resource: "process-config",
+        operation: "stdin",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:stdin @ -> @|null",
+        resultType: "reference:reader-stream?",
+        appleAPISymbol: "LinuxProcessConfiguration.stdin",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/stdin",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.stdin",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:stdin",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:stdout",
+        methodID: "processConfig.stdout",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:stdout",
+        ],
+        resource: "process-config",
+        operation: "stdout",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:stdout @ -> @|null",
+        resultType: "reference:writer?",
+        appleAPISymbol: "LinuxProcessConfiguration.stdout",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/stdout",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.stdout",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:stdout",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process-config:stderr",
+        methodID: "processConfig.stderr",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process-config:stderr",
+        ],
+        resource: "process-config",
+        operation: "stderr",
+        shape: .reference,
+        signature: "ghostbox cn:process-config:stderr @ -> @|null",
+        resultType: "reference:writer?",
+        appleAPISymbol: "LinuxProcessConfiguration.stderr",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocessconfiguration/stderr",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcessConfiguration.stderr",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process-config:stderr",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container-config:create-default",
+        methodID: "containerConfig.createDefault",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container-config:create-default",
+        ],
+        resource: "container-config",
+        operation: "create-default",
+        shape: .create,
+        signature: "ghostbox cn:container-config:create-default \n-> @",
+        resultType: "reference:container-config",
+        appleAPISymbol: "LinuxContainer.Configuration.init()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/configuration/init()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.Configuration.init()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container-config:create-default",
+            "example",
+        ],
+        positionals: [
+            .init(name: "container-config", parameterName: "containerConfig", type: "name", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container-config:create",
+        methodID: "containerConfig.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container-config:create",
+        ],
+        resource: "container-config",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:container-config:create \n--process @\n[--cpus=4]\n[--memory=1073741824]\n[--hostname ]\n[--sysctl ]...\n[--interface @]...\n[--socket @]...\n[--mount @]...\n[--masked-path ]...\n[--readonly-path ]...\n[--dns @]\n[--hosts @]\n[--virtualization=false]\n[--boot-log @]\n[--oci-runtime-path ]\n[--use-init=false]\n[--cpu-overhead=1]\n[--memory-overhead=134217728]\n-> @",
+        resultType: "reference:container-config",
+        appleAPISymbol: "LinuxContainer.Configuration.init(process:cpus:memoryInBytes:hostname:sysctl:interfaces:sockets:mounts:maskedPaths:readonlyPaths:dns:hosts:virtualization:bootLog:ociRuntimePath:useInit:cpuOverhead:memoryOverhead:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/configuration/init(process:cpus:memoryinbytes:hostname:sysctl:interfaces:sockets:mounts:maskedpaths:readonlypaths:dns:hosts:virtualization:bootlog:ociruntimepath:useinit:cpuoverhead:memoryoverhead:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.Configuration.init(process:cpus:memoryInBytes:hostname:sysctl:interfaces:sockets:mounts:maskedPaths:readonlyPaths:dns:hosts:virtualization:bootLog:ociRuntimePath:useInit:cpuOverhead:memoryOverhead:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container-config:create",
+            "example",
+            "--process",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "container-config", parameterName: "containerConfig", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--process"], parameterName: "process", type: "reference:process-config", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpus"], parameterName: "cpus", type: "int", required: false, repeatable: false, defaultValue: .integer(4)),
+            .init(names: ["--memory"], parameterName: "memory", type: "uint64", required: false, repeatable: false, defaultValue: .unsignedInteger(1073741824)),
+            .init(names: ["--hostname"], parameterName: "hostname", type: "string", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--sysctl"], parameterName: "sysctl", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--interface"], parameterName: "interface", type: "reference:interface", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--socket"], parameterName: "socket", type: "reference:socket", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--mount"], parameterName: "mount", type: "reference:mount", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--masked-path"], parameterName: "maskedPath", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--readonly-path"], parameterName: "readonlyPath", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--dns"], parameterName: "dns", type: "reference:dns", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hosts"], parameterName: "hosts", type: "reference:hosts", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--virtualization"], parameterName: "virtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--boot-log"], parameterName: "bootLog", type: "reference:boot-log", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--oci-runtime-path"], parameterName: "ociRuntimePath", type: "container-path", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--use-init"], parameterName: "useInit", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--cpu-overhead"], parameterName: "cpuOverhead", type: "int", required: false, repeatable: false, defaultValue: .integer(1)),
+            .init(names: ["--memory-overhead"], parameterName: "memoryOverhead", type: "uint64", required: false, repeatable: false, defaultValue: .unsignedInteger(134217728)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:default-mounts",
+        methodID: "container.defaultMounts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:default-mounts",
+        ],
+        resource: "container",
+        operation: "default-mounts",
+        shape: .static,
+        signature: "ghostbox cn:container:default-mounts -> @...",
+        resultType: "reference:mount[]",
+        appleAPISymbol: "LinuxContainer.defaultMounts()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultmounts()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.defaultMounts()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:default-mounts",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:default-oci-mounts",
+        methodID: "container.defaultOCIMounts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:default-oci-mounts",
+        ],
+        resource: "container",
+        operation: "default-oci-mounts",
+        shape: .static,
+        signature: "ghostbox cn:container:default-oci-mounts -> ...",
+        resultType: "oci-mount[]",
+        appleAPISymbol: "LinuxContainer.defaultOCIMounts()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultocimounts()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.defaultOCIMounts()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:default-oci-mounts",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:default-masked-paths",
+        methodID: "container.defaultMaskedPaths",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:default-masked-paths",
+        ],
+        resource: "container",
+        operation: "default-masked-paths",
+        shape: .static,
+        signature: "ghostbox cn:container:default-masked-paths -> ...",
+        resultType: "container-path[]",
+        appleAPISymbol: "LinuxContainer.defaultMaskedPaths()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultmaskedpaths()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.defaultMaskedPaths()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:default-masked-paths",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:default-readonly-paths",
+        methodID: "container.defaultReadonlyPaths",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:default-readonly-paths",
+        ],
+        resource: "container",
+        operation: "default-readonly-paths",
+        shape: .static,
+        signature: "ghostbox cn:container:default-readonly-paths -> ...",
+        resultType: "container-path[]",
+        appleAPISymbol: "LinuxContainer.defaultReadonlyPaths()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultreadonlypaths()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.defaultReadonlyPaths()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:default-readonly-paths",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:default-copy-chunk-size",
+        methodID: "container.defaultCopyChunkSize",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:default-copy-chunk-size",
+        ],
+        resource: "container",
+        operation: "default-copy-chunk-size",
+        shape: .static,
+        signature: "ghostbox cn:container:default-copy-chunk-size -> ",
+        resultType: "int",
+        appleAPISymbol: "LinuxContainer.defaultCopyChunkSize",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/defaultcopychunksize",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.defaultCopyChunkSize",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:default-copy-chunk-size",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:max-id-length",
+        methodID: "container.maxIDLength",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:max-id-length",
+        ],
+        resource: "container",
+        operation: "max-id-length",
+        shape: .static,
+        signature: "ghostbox cn:container:max-id-length -> ",
+        resultType: "int",
+        appleAPISymbol: "LinuxContainer.maxIDLength",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/maxidlength",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.maxIDLength",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:max-id-length",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create",
+        methodID: "manager.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create",
+        ],
+        resource: "manager",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:manager:create \n--kernel @\n--initfs @\n--image-store @\n[--network @]\n[--rosetta=false]\n[--nested-virtualization=false]\n-> @",
+        resultType: "reference:manager",
+        appleAPISymbol: "ContainerManager.init(kernel:initfs:imageStore:network:rosetta:nestedVirtualization:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfs:imagestore:network:rosetta:nestedvirtualization:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.init(kernel:initfs:imageStore:network:rosetta:nestedVirtualization:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create",
+            "example",
+            "--kernel",
+            "@kernel/example",
+            "--initfs",
+            "@mount/example",
+            "--image-store",
+            "@image-store/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel"], parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--initfs"], parameterName: "initfs", type: "reference:mount", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--image-store"], parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--network"], parameterName: "network", type: "reference:network", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--rosetta"], parameterName: "rosetta", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--nested-virtualization"], parameterName: "nestedVirtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-at-root",
+        methodID: "manager.createAtRoot",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-at-root",
+        ],
+        resource: "manager",
+        operation: "create-at-root",
+        shape: .create,
+        signature: "ghostbox cn:manager:create-at-root \n--kernel @\n--initfs @\n[--root ]\n[--network @]\n[--rosetta=false]\n[--nested-virtualization=false]\n-> @",
+        resultType: "reference:manager",
+        appleAPISymbol: "ContainerManager.init(kernel:initfs:root:network:rosetta:nestedVirtualization:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfs:root:network:rosetta:nestedvirtualization:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.init(kernel:initfs:root:network:rosetta:nestedVirtualization:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-at-root",
+            "example",
+            "--kernel",
+            "@kernel/example",
+            "--initfs",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel"], parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--initfs"], parameterName: "initfs", type: "reference:mount", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--root"], parameterName: "root", type: "host-url", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--network"], parameterName: "network", type: "reference:network", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--rosetta"], parameterName: "rosetta", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--nested-virtualization"], parameterName: "nestedVirtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-from-reference",
+        methodID: "manager.createFromReference",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-from-reference",
+        ],
+        resource: "manager",
+        operation: "create-from-reference",
+        shape: .create,
+        signature: "ghostbox cn:manager:create-from-reference \n--kernel @\n--initfs-reference \n--image-store @\n[--network @]\n[--rosetta=false]\n[--nested-virtualization=false]\n-> @",
+        resultType: "reference:manager",
+        appleAPISymbol: "ContainerManager.init(kernel:initfsReference:imageStore:network:rosetta:nestedVirtualization:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfsreference:imagestore:network:rosetta:nestedvirtualization:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.init(kernel:initfsReference:imageStore:network:rosetta:nestedVirtualization:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-from-reference",
+            "example",
+            "--kernel",
+            "@kernel/example",
+            "--initfs-reference",
+            "example",
+            "--image-store",
+            "@image-store/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel"], parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--initfs-reference"], parameterName: "initfsReference", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--image-store"], parameterName: "imageStore", type: "reference:image-store", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--network"], parameterName: "network", type: "reference:network", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--rosetta"], parameterName: "rosetta", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--nested-virtualization"], parameterName: "nestedVirtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-from-reference-at-root",
+        methodID: "manager.createFromReferenceAtRoot",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-from-reference-at-root",
+        ],
+        resource: "manager",
+        operation: "create-from-reference-at-root",
+        shape: .create,
+        signature: "ghostbox cn:manager:create-from-reference-at-root \n--kernel @\n--initfs-reference \n[--root ]\n[--network @]\n[--rosetta=false]\n[--nested-virtualization=false]\n-> @",
+        resultType: "reference:manager",
+        appleAPISymbol: "ContainerManager.init(kernel:initfsReference:root:network:rosetta:nestedVirtualization:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/init(kernel:initfsreference:root:network:rosetta:nestedvirtualization:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.init(kernel:initfsReference:root:network:rosetta:nestedVirtualization:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-from-reference-at-root",
+            "example",
+            "--kernel",
+            "@kernel/example",
+            "--initfs-reference",
+            "example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--kernel"], parameterName: "kernel", type: "reference:kernel", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--initfs-reference"], parameterName: "initfsReference", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--root"], parameterName: "root", type: "host-url", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--network"], parameterName: "network", type: "reference:network", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--rosetta"], parameterName: "rosetta", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--nested-virtualization"], parameterName: "nestedVirtualization", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-with-vmm",
+        methodID: "manager.createWithVMM",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-with-vmm",
+        ],
+        resource: "manager",
+        operation: "create-with-vmm",
+        shape: .create,
+        signature: "ghostbox cn:manager:create-with-vmm \n--vmm @\n[--network @]\n-> @",
+        resultType: "reference:manager",
+        appleAPISymbol: "ContainerManager.init(vmm:network:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/init(vmm:network:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.init(vmm:network:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-with-vmm",
+            "example",
+            "--vmm",
+            "@vmm/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--vmm"], parameterName: "vmm", type: "reference:vmm", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--network"], parameterName: "network", type: "reference:network", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:image-store",
+        methodID: "manager.imageStore",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:image-store",
+        ],
+        resource: "manager",
+        operation: "image-store",
+        shape: .reference,
+        signature: "ghostbox cn:manager:image-store @ -> @",
+        resultType: "reference:image-store",
+        appleAPISymbol: "ContainerManager.imageStore",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/imagestore",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.imageStore",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:image-store",
+            "@manager/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "reference:manager", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-container",
+        methodID: "manager.createContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-container",
+        ],
+        resource: "manager",
+        operation: "create-container",
+        shape: .reference,
+        signature: "ghostbox cn:manager:create-container @\n\n--reference \n[--rootfs-size=8589934592]\n[--writable-layer-size ]\n[--read-only=false]\n[--networking=true]\n[--progress @]\n[]...\n-> @",
+        resultType: "reference:container",
+        appleAPISymbol: "ContainerManager.create(_:reference:rootfsSizeInBytes:writableLayerSizeInBytes:readOnly:networking:progress:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/create(_:reference:rootfssizeinbytes:writablelayersizeinbytes:readonly:networking:progress:configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.create(_:reference:rootfsSizeInBytes:writableLayerSizeInBytes:readOnly:networking:progress:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-container",
+            "@manager/example",
+            "example",
+            "--reference",
+            "example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "reference:manager", required: true, repeatable: false),
+            .init(name: "container", parameterName: "container", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--reference"], parameterName: "reference", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--rootfs-size"], parameterName: "rootfsSize", type: "uint64", required: false, repeatable: false, defaultValue: .unsignedInteger(8589934592)),
+            .init(names: ["--writable-layer-size"], parameterName: "writableLayerSize", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--read-only"], parameterName: "readOnly", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--networking"], parameterName: "networking", type: "bool", required: false, repeatable: false, defaultValue: .boolean(true)),
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--process"], parameterName: "process", type: "reference:process-config", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpus"], parameterName: "cpus", type: "int", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--memory"], parameterName: "memory", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hostname"], parameterName: "hostname", type: "string", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--sysctl"], parameterName: "sysctl", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--interfaces"], parameterName: "interfaces", type: "reference:interface", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--sockets"], parameterName: "sockets", type: "reference:socket", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--mounts"], parameterName: "mounts", type: "reference:mount", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--masked-paths"], parameterName: "maskedPaths", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--readonly-paths"], parameterName: "readonlyPaths", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--dns"], parameterName: "dns", type: "reference:dns", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hosts"], parameterName: "hosts", type: "reference:hosts", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--virtualization"], parameterName: "virtualization", type: "bool", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--boot-log"], parameterName: "bootLog", type: "reference:boot-log", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--oci-runtime-path"], parameterName: "ociRuntimePath", type: "container-path", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--use-init"], parameterName: "useInit", type: "bool", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpu-overhead"], parameterName: "cpuOverhead", type: "int", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--memory-overhead"], parameterName: "memoryOverhead", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-container-from-image",
+        methodID: "manager.createContainerFromImage",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-container-from-image",
+        ],
+        resource: "manager",
+        operation: "create-container-from-image",
+        shape: .reference,
+        signature: "ghostbox cn:manager:create-container-from-image @\n\n--image @\n[--rootfs-size=8589934592]\n[--writable-layer-size ]\n[--read-only=false]\n[--networking=true]\n[--progress @]\n[]...\n-> @",
+        resultType: "reference:container",
+        appleAPISymbol: "ContainerManager.create(_:image:rootfsSizeInBytes:writableLayerSizeInBytes:readOnly:networking:progress:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/create(_:image:rootfssizeinbytes:writablelayersizeinbytes:readonly:networking:progress:configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.create(_:image:rootfsSizeInBytes:writableLayerSizeInBytes:readOnly:networking:progress:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-container-from-image",
+            "@manager/example",
+            "example",
+            "--image",
+            "@image/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "reference:manager", required: true, repeatable: false),
+            .init(name: "container", parameterName: "container", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--image"], parameterName: "image", type: "reference:image", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--rootfs-size"], parameterName: "rootfsSize", type: "uint64", required: false, repeatable: false, defaultValue: .unsignedInteger(8589934592)),
+            .init(names: ["--writable-layer-size"], parameterName: "writableLayerSize", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--read-only"], parameterName: "readOnly", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+            .init(names: ["--networking"], parameterName: "networking", type: "bool", required: false, repeatable: false, defaultValue: .boolean(true)),
+            .init(names: ["--progress"], parameterName: "progress", type: "reference:progress-handler", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--process"], parameterName: "process", type: "reference:process-config", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpus"], parameterName: "cpus", type: "int", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--memory"], parameterName: "memory", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hostname"], parameterName: "hostname", type: "string", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--sysctl"], parameterName: "sysctl", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--interfaces"], parameterName: "interfaces", type: "reference:interface", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--sockets"], parameterName: "sockets", type: "reference:socket", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--mounts"], parameterName: "mounts", type: "reference:mount", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--masked-paths"], parameterName: "maskedPaths", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--readonly-paths"], parameterName: "readonlyPaths", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--dns"], parameterName: "dns", type: "reference:dns", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hosts"], parameterName: "hosts", type: "reference:hosts", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--virtualization"], parameterName: "virtualization", type: "bool", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--boot-log"], parameterName: "bootLog", type: "reference:boot-log", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--oci-runtime-path"], parameterName: "ociRuntimePath", type: "container-path", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--use-init"], parameterName: "useInit", type: "bool", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpu-overhead"], parameterName: "cpuOverhead", type: "int", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--memory-overhead"], parameterName: "memoryOverhead", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:create-container-from-mounts",
+        methodID: "manager.createContainerFromMounts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:create-container-from-mounts",
+        ],
+        resource: "manager",
+        operation: "create-container-from-mounts",
+        shape: .reference,
+        signature: "ghostbox cn:manager:create-container-from-mounts @\n\n--image @\n--rootfs @\n[--writable-layer @]\n[--networking=true]\n[]...\n-> @",
+        resultType: "reference:container",
+        appleAPISymbol: "ContainerManager.create(_:image:rootfs:writableLayer:networking:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/create(_:image:rootfs:writablelayer:networking:configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.create(_:image:rootfs:writableLayer:networking:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:create-container-from-mounts",
+            "@manager/example",
+            "example",
+            "--image",
+            "@image/example",
+            "--rootfs",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "reference:manager", required: true, repeatable: false),
+            .init(name: "container", parameterName: "container", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--image"], parameterName: "image", type: "reference:image", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--rootfs"], parameterName: "rootfs", type: "reference:mount", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--writable-layer"], parameterName: "writableLayer", type: "reference:mount", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--networking"], parameterName: "networking", type: "bool", required: false, repeatable: false, defaultValue: .boolean(true)),
+            .init(names: ["--process"], parameterName: "process", type: "reference:process-config", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpus"], parameterName: "cpus", type: "int", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--memory"], parameterName: "memory", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hostname"], parameterName: "hostname", type: "string", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--sysctl"], parameterName: "sysctl", type: "string", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--interfaces"], parameterName: "interfaces", type: "reference:interface", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--sockets"], parameterName: "sockets", type: "reference:socket", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--mounts"], parameterName: "mounts", type: "reference:mount", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--masked-paths"], parameterName: "maskedPaths", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--readonly-paths"], parameterName: "readonlyPaths", type: "container-path", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--dns"], parameterName: "dns", type: "reference:dns", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--hosts"], parameterName: "hosts", type: "reference:hosts", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--virtualization"], parameterName: "virtualization", type: "bool", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--boot-log"], parameterName: "bootLog", type: "reference:boot-log", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--oci-runtime-path"], parameterName: "ociRuntimePath", type: "container-path", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--use-init"], parameterName: "useInit", type: "bool", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--cpu-overhead"], parameterName: "cpuOverhead", type: "int", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--memory-overhead"], parameterName: "memoryOverhead", type: "uint64", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:release-network",
+        methodID: "manager.releaseNetwork",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:release-network",
+        ],
+        resource: "manager",
+        operation: "release-network",
+        shape: .reference,
+        signature: "ghostbox cn:manager:release-network @ @",
+        resultType: "void",
+        appleAPISymbol: "ContainerManager.releaseNetwork(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/releasenetwork(_:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.releaseNetwork(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:release-network",
+            "@manager/example",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "reference:manager", required: true, repeatable: false),
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:manager:delete",
+        methodID: "manager.delete",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:manager:delete",
+        ],
+        resource: "manager",
+        operation: "delete",
+        shape: .reference,
+        signature: "ghostbox cn:manager:delete @ @",
+        resultType: "void",
+        appleAPISymbol: "ContainerManager.delete(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/containermanager/delete(_:)",
+        swiftModule: nil,
+        swiftSymbol: "ContainerManager.delete(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:manager:delete",
+            "@manager/example",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "manager", parameterName: "manager", type: "reference:manager", required: true, repeatable: false),
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:create-direct",
+        methodID: "container.createDirect",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:create-direct",
+        ],
+        resource: "container",
+        operation: "create-direct",
+        shape: .create,
+        signature: "ghostbox cn:container:create-direct \n--rootfs @\n[--writable-layer @]\n--vmm @\n--configuration @\n-> @",
+        resultType: "reference:container",
+        appleAPISymbol: "LinuxContainer.init(_:rootfs:writableLayer:vmm:configuration:logger:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/init(_:rootfs:writablelayer:vmm:configuration:logger:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.init(_:rootfs:writableLayer:vmm:configuration:logger:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:create-direct",
+            "example",
+            "--rootfs",
+            "@mount/example",
+            "--vmm",
+            "@vmm/example",
+            "--configuration",
+            "@container-config/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--rootfs"], parameterName: "rootfs", type: "reference:mount", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--writable-layer"], parameterName: "writableLayer", type: "reference:mount", required: false, repeatable: false, defaultValue: nil),
+            .init(names: ["--vmm"], parameterName: "vmm", type: "reference:vmm", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--configuration"], parameterName: "configuration", type: "reference:container-config", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:id",
+        methodID: "container.id",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:id",
+        ],
+        resource: "container",
+        operation: "id",
+        shape: .reference,
+        signature: "ghostbox cn:container:id @ -> ",
+        resultType: "string",
+        appleAPISymbol: "LinuxContainer.id",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/id",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.id",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:id",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:rootfs",
+        methodID: "container.rootfs",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:rootfs",
+        ],
+        resource: "container",
+        operation: "rootfs",
+        shape: .reference,
+        signature: "ghostbox cn:container:rootfs @ -> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "LinuxContainer.rootfs",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/rootfs",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.rootfs",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:rootfs",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:writable-layer",
+        methodID: "container.writableLayer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:writable-layer",
+        ],
+        resource: "container",
+        operation: "writable-layer",
+        shape: .reference,
+        signature: "ghostbox cn:container:writable-layer @ -> @|null",
+        resultType: "reference:mount?",
+        appleAPISymbol: "LinuxContainer.writableLayer",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/writablelayer",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.writableLayer",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:writable-layer",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:config",
+        methodID: "container.config",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:config",
+        ],
+        resource: "container",
+        operation: "config",
+        shape: .reference,
+        signature: "ghostbox cn:container:config @ -> @",
+        resultType: "reference:container-config",
+        appleAPISymbol: "LinuxContainer.config",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/config",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.config",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:config",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:cpus",
+        methodID: "container.cpus",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:cpus",
+        ],
+        resource: "container",
+        operation: "cpus",
+        shape: .reference,
+        signature: "ghostbox cn:container:cpus @ -> ",
+        resultType: "int",
+        appleAPISymbol: "LinuxContainer.cpus",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/cpus",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.cpus",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:cpus",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:memory",
+        methodID: "container.memory",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:memory",
+        ],
+        resource: "container",
+        operation: "memory",
+        shape: .reference,
+        signature: "ghostbox cn:container:memory @ -> ",
+        resultType: "uint64",
+        appleAPISymbol: "LinuxContainer.memoryInBytes",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/memoryinbytes",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.memoryInBytes",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:memory",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:interfaces",
+        methodID: "container.interfaces",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:interfaces",
+        ],
+        resource: "container",
+        operation: "interfaces",
+        shape: .reference,
+        signature: "ghostbox cn:container:interfaces @ -> @...",
+        resultType: "reference:interface[]",
+        appleAPISymbol: "LinuxContainer.interfaces",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/interfaces",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.interfaces",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:interfaces",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:create",
+        methodID: "container.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:create",
+        ],
+        resource: "container",
+        operation: "create",
+        shape: .reference,
+        signature: "ghostbox cn:container:create @",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.create()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/create()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.create()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:create",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:start",
+        methodID: "container.start",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:start",
+        ],
+        resource: "container",
+        operation: "start",
+        shape: .reference,
+        signature: "ghostbox cn:container:start @",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.start()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/start()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.start()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:start",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:stop",
+        methodID: "container.stop",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:stop",
+        ],
+        resource: "container",
+        operation: "stop",
+        shape: .reference,
+        signature: "ghostbox cn:container:stop @",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.stop()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/stop()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.stop()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:stop",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:kill",
+        methodID: "container.kill",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:kill",
+        ],
+        resource: "container",
+        operation: "kill",
+        shape: .reference,
+        signature: "ghostbox cn:container:kill @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.kill(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/kill(_:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.kill(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:kill",
+            "@container/example",
+            "SIGTERM",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "signal", parameterName: "signal", type: "linux-signal", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:wait",
+        methodID: "container.wait",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:wait",
+        ],
+        resource: "container",
+        operation: "wait",
+        shape: .reference,
+        signature: "ghostbox cn:container:wait @\n[--timeout-seconds ]\n-> ",
+        resultType: "exit-status",
+        appleAPISymbol: "LinuxContainer.wait(timeoutInSeconds:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/wait(timeoutinseconds:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.wait(timeoutInSeconds:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:wait",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--timeout-seconds"], parameterName: "timeoutSeconds", type: "int64", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:resize",
+        methodID: "container.resize",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:resize",
+        ],
+        resource: "container",
+        operation: "resize",
+        shape: .reference,
+        signature: "ghostbox cn:container:resize @\n\n",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.resize(to:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/resize(to:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.resize(to:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:resize",
+            "@container/example",
+            "1",
+            "1",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "width", parameterName: "width", type: "uint16", required: true, repeatable: false),
+            .init(name: "height", parameterName: "height", type: "uint16", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:exec",
+        methodID: "container.exec",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:exec",
+        ],
+        resource: "container",
+        operation: "exec",
+        shape: .reference,
+        signature: "ghostbox cn:container:exec @\n\n--configuration @\n-> @",
+        resultType: "reference:process",
+        appleAPISymbol: "LinuxContainer.exec(_:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/exec(_:configuration:)-7nhhe",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.exec(_:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:exec",
+            "@container/example",
+            "example",
+            "--configuration",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "process", parameterName: "process", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--configuration"], parameterName: "configuration", type: "reference:process-config", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:dial-vsock",
+        methodID: "container.dialVsock",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:dial-vsock",
+        ],
+        resource: "container",
+        operation: "dial-vsock",
+        shape: .reference,
+        signature: "ghostbox cn:container:dial-vsock @\n\n-> @",
+        resultType: "reference:file-handle",
+        appleAPISymbol: "LinuxContainer.dialVsock(port:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/dialvsock(port:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.dialVsock(port:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:dial-vsock",
+            "@container/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "port", parameterName: "port", type: "uint32", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:close-stdin",
+        methodID: "container.closeStdin",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:close-stdin",
+        ],
+        resource: "container",
+        operation: "close-stdin",
+        shape: .reference,
+        signature: "ghostbox cn:container:close-stdin @",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.closeStdin()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/closestdin()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.closeStdin()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:close-stdin",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:statistics",
+        methodID: "container.statistics",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:statistics",
+        ],
+        resource: "container",
+        operation: "statistics",
+        shape: .reference,
+        signature: "ghostbox cn:container:statistics @\n[--category ]...\n-> ",
+        resultType: "container-statistics",
+        appleAPISymbol: "LinuxContainer.statistics(categories:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/statistics(categories:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.statistics(categories:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:statistics",
+            "@container/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--category"], parameterName: "category", type: "statistics-category", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:filesystem-operation",
+        methodID: "container.filesystemOperation",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:filesystem-operation",
+        ],
+        resource: "container",
+        operation: "filesystem-operation",
+        shape: .reference,
+        signature: "ghostbox cn:container:filesystem-operation @\n\n",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.filesystemOperation(operation:path:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/filesystemoperation(operation:path:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.filesystemOperation(operation:path:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:filesystem-operation",
+            "@container/example",
+            "freeze",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "operation", parameterName: "operation", type: "freeze|thaw|trim", required: true, repeatable: false),
+            .init(name: "path", parameterName: "path", type: "container-path", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:copy-in",
+        methodID: "container.copyIn",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:copy-in",
+        ],
+        resource: "container",
+        operation: "copy-in",
+        shape: .reference,
+        signature: "ghostbox cn:container:copy-in @\n\n\n[--mode=0644]\n[--create-parents=true]\n[--chunk-size=1048576]",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.copyIn(from:to:mode:createParents:chunkSize:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/copyin(from:to:mode:createparents:chunksize:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.copyIn(from:to:mode:createParents:chunkSize:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:copy-in",
+            "@container/example",
+            "/tmp/example",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "source", parameterName: "source", type: "host-url", required: true, repeatable: false),
+            .init(name: "destination", parameterName: "destination", type: "container-url", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--mode"], parameterName: "mode", type: "file-permissions", required: false, repeatable: false, defaultValue: .string("0644")),
+            .init(names: ["--create-parents"], parameterName: "createParents", type: "bool", required: false, repeatable: false, defaultValue: .boolean(true)),
+            .init(names: ["--chunk-size"], parameterName: "chunkSize", type: "int", required: false, repeatable: false, defaultValue: .integer(1048576)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:container:copy-out",
+        methodID: "container.copyOut",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:container:copy-out",
+        ],
+        resource: "container",
+        operation: "copy-out",
+        shape: .reference,
+        signature: "ghostbox cn:container:copy-out @\n\n\n[--create-parents=true]\n[--chunk-size=1048576]",
+        resultType: "void",
+        appleAPISymbol: "LinuxContainer.copyOut(from:to:createParents:chunkSize:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxcontainer/copyout(from:to:createparents:chunksize:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxContainer.copyOut(from:to:createParents:chunkSize:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:container:copy-out",
+            "@container/example",
+            "/example",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "container", parameterName: "container", type: "reference:container", required: true, repeatable: false),
+            .init(name: "source", parameterName: "source", type: "container-url", required: true, repeatable: false),
+            .init(name: "destination", parameterName: "destination", type: "host-url", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--create-parents"], parameterName: "createParents", type: "bool", required: false, repeatable: false, defaultValue: .boolean(true)),
+            .init(names: ["--chunk-size"], parameterName: "chunkSize", type: "int", required: false, repeatable: false, defaultValue: .integer(1048576)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:id",
+        methodID: "process.id",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:id",
+        ],
+        resource: "process",
+        operation: "id",
+        shape: .reference,
+        signature: "ghostbox cn:process:id @ -> ",
+        resultType: "string",
+        appleAPISymbol: "LinuxProcess.id",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/id",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.id",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:id",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:owning-container",
+        methodID: "process.owningContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:owning-container",
+        ],
+        resource: "process",
+        operation: "owning-container",
+        shape: .reference,
+        signature: "ghostbox cn:process:owning-container @ -> |null",
+        resultType: "string?",
+        appleAPISymbol: "LinuxProcess.owningContainer",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/owningcontainer",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.owningContainer",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:owning-container",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:pid",
+        methodID: "process.pid",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:pid",
+        ],
+        resource: "process",
+        operation: "pid",
+        shape: .reference,
+        signature: "ghostbox cn:process:pid @ -> ",
+        resultType: "int32",
+        appleAPISymbol: "LinuxProcess.pid",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/pid",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.pid",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:pid",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:start",
+        methodID: "process.start",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:start",
+        ],
+        resource: "process",
+        operation: "start",
+        shape: .reference,
+        signature: "ghostbox cn:process:start @",
+        resultType: "void",
+        appleAPISymbol: "LinuxProcess.start()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/start()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.start()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:start",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:kill",
+        methodID: "process.kill",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:kill",
+        ],
+        resource: "process",
+        operation: "kill",
+        shape: .reference,
+        signature: "ghostbox cn:process:kill @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxProcess.kill(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/kill(_:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.kill(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:kill",
+            "@process/example",
+            "SIGTERM",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+            .init(name: "signal", parameterName: "signal", type: "linux-signal", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:resize",
+        methodID: "process.resize",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:resize",
+        ],
+        resource: "process",
+        operation: "resize",
+        shape: .reference,
+        signature: "ghostbox cn:process:resize @\n\n",
+        resultType: "void",
+        appleAPISymbol: "LinuxProcess.resize(to:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/resize(to:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.resize(to:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:resize",
+            "@process/example",
+            "1",
+            "1",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+            .init(name: "width", parameterName: "width", type: "uint16", required: true, repeatable: false),
+            .init(name: "height", parameterName: "height", type: "uint16", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:close-stdin",
+        methodID: "process.closeStdin",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:close-stdin",
+        ],
+        resource: "process",
+        operation: "close-stdin",
+        shape: .reference,
+        signature: "ghostbox cn:process:close-stdin @",
+        resultType: "void",
+        appleAPISymbol: "LinuxProcess.closeStdin()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/closestdin()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.closeStdin()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:close-stdin",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:wait",
+        methodID: "process.wait",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:wait",
+        ],
+        resource: "process",
+        operation: "wait",
+        shape: .reference,
+        signature: "ghostbox cn:process:wait @\n[--timeout-seconds ]\n-> ",
+        resultType: "exit-status",
+        appleAPISymbol: "LinuxProcess.wait(timeoutInSeconds:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/wait(timeoutinseconds:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.wait(timeoutInSeconds:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:wait",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--timeout-seconds"], parameterName: "timeoutSeconds", type: "int64", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:process:delete",
+        methodID: "process.delete",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:process:delete",
+        ],
+        resource: "process",
+        operation: "delete",
+        shape: .reference,
+        signature: "ghostbox cn:process:delete @",
+        resultType: "void",
+        appleAPISymbol: "LinuxProcess.delete()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxprocess/delete()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxProcess.delete()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:process:delete",
+            "@process/example",
+        ],
+        positionals: [
+            .init(name: "process", parameterName: "process", type: "reference:process", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-volume:create",
+        methodID: "podVolume.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-volume:create",
+        ],
+        resource: "pod-volume",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:pod-volume:create \n--name \n--source \n--format \n-> @",
+        resultType: "reference:pod-volume",
+        appleAPISymbol: "LinuxPod.PodVolume.init(name:source:format:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/podvolume/init(name:source:format:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.PodVolume.init(name:source:format:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-volume:create",
+            "example",
+            "--name",
+            "example",
+            "--source",
+            "{}",
+            "--format",
+            "example",
+        ],
+        positionals: [
+            .init(name: "pod-volume", parameterName: "podVolume", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--name"], parameterName: "name", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--source"], parameterName: "source", type: "pod-volume-source", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--format"], parameterName: "format", type: "string", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:create",
+        methodID: "podConfig.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:create",
+        ],
+        resource: "pod-config",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:pod-config:create  -> @",
+        resultType: "reference:pod-config",
+        appleAPISymbol: "LinuxPod.Configuration.init()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/init()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.init()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "name", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-cpus",
+        methodID: "podConfig.setCPUs",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-cpus",
+        ],
+        resource: "pod-config",
+        operation: "set-cpus",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-cpus @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.cpus",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/cpus",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.cpus",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-cpus",
+            "@pod-config/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "cpus", parameterName: "cpus", type: "int", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-memory",
+        methodID: "podConfig.setMemory",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-memory",
+        ],
+        resource: "pod-config",
+        operation: "set-memory",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-memory @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.memoryInBytes",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/memoryinbytes",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.memoryInBytes",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-memory",
+            "@pod-config/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "bytes", parameterName: "bytes", type: "uint64", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-interfaces",
+        methodID: "podConfig.setInterfaces",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-interfaces",
+        ],
+        resource: "pod-config",
+        operation: "set-interfaces",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-interfaces @ @...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.interfaces",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/interfaces",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.interfaces",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-interfaces",
+            "@pod-config/example",
+            "@interface/example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "interface", parameterName: "interface", type: "reference:interface", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-virtualization",
+        methodID: "podConfig.setVirtualization",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-virtualization",
+        ],
+        resource: "pod-config",
+        operation: "set-virtualization",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-virtualization @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.virtualization",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/virtualization",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.virtualization",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-virtualization",
+            "@pod-config/example",
+            "true",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "enabled", parameterName: "enabled", type: "bool", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-boot-log",
+        methodID: "podConfig.setBootLog",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-boot-log",
+        ],
+        resource: "pod-config",
+        operation: "set-boot-log",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-boot-log @ @|null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.bootLog",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/bootlog",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.bootLog",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-boot-log",
+            "@pod-config/example",
+            "@boot-log/example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "boot-log", parameterName: "bootLog", type: "reference:boot-log?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-share-process-namespace",
+        methodID: "podConfig.setShareProcessNamespace",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-share-process-namespace",
+        ],
+        resource: "pod-config",
+        operation: "set-share-process-namespace",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-share-process-namespace @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.shareProcessNamespace",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/shareprocessnamespace",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.shareProcessNamespace",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-share-process-namespace",
+            "@pod-config/example",
+            "true",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "enabled", parameterName: "enabled", type: "bool", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-hostname",
+        methodID: "podConfig.setHostname",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-hostname",
+        ],
+        resource: "pod-config",
+        operation: "set-hostname",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-hostname @ |null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.hostname",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/hostname",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.hostname",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-hostname",
+            "@pod-config/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "hostname", parameterName: "hostname", type: "string?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-dns",
+        methodID: "podConfig.setDNS",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-dns",
+        ],
+        resource: "pod-config",
+        operation: "set-dns",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-dns @ @|null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.dns",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/dns",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.dns",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-dns",
+            "@pod-config/example",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "dns", parameterName: "dns", type: "reference:dns?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-hosts",
+        methodID: "podConfig.setHosts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-hosts",
+        ],
+        resource: "pod-config",
+        operation: "set-hosts",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-hosts @ @|null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.hosts",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/hosts",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.hosts",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-hosts",
+            "@pod-config/example",
+            "@hosts/example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "hosts", parameterName: "hosts", type: "reference:hosts?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-config:set-volumes",
+        methodID: "podConfig.setVolumes",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-config:set-volumes",
+        ],
+        resource: "pod-config",
+        operation: "set-volumes",
+        shape: .reference,
+        signature: "ghostbox cn:pod-config:set-volumes @ @...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.Configuration.volumes",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/configuration/volumes",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.Configuration.volumes",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-config:set-volumes",
+            "@pod-config/example",
+            "@pod-volume/example",
+        ],
+        positionals: [
+            .init(name: "pod-config", parameterName: "podConfig", type: "reference:pod-config", required: true, repeatable: false),
+            .init(name: "pod-volume", parameterName: "podVolume", type: "reference:pod-volume", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:create",
+        methodID: "podContainerConfig.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:create",
+        ],
+        resource: "pod-container-config",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:pod-container-config:create  -> @",
+        resultType: "reference:pod-container-config",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.init()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/init()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.init()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "name", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-process",
+        methodID: "podContainerConfig.setProcess",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-process",
+        ],
+        resource: "pod-container-config",
+        operation: "set-process",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-process @ @",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.process",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/process",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.process",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-process",
+            "@pod-container-config/example",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "process-config", parameterName: "processConfig", type: "reference:process-config", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-cpus",
+        methodID: "podContainerConfig.setCPUs",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-cpus",
+        ],
+        resource: "pod-container-config",
+        operation: "set-cpus",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-cpus @ |null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.cpus",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/cpus",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.cpus",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-cpus",
+            "@pod-container-config/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "cpus", parameterName: "cpus", type: "int?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-memory",
+        methodID: "podContainerConfig.setMemory",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-memory",
+        ],
+        resource: "pod-container-config",
+        operation: "set-memory",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-memory @ |null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.memoryInBytes",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/memoryinbytes",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.memoryInBytes",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-memory",
+            "@pod-container-config/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "bytes", parameterName: "bytes", type: "uint64?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-hostname",
+        methodID: "podContainerConfig.setHostname",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-hostname",
+        ],
+        resource: "pod-container-config",
+        operation: "set-hostname",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-hostname @ |null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.hostname",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/hostname",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.hostname",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-hostname",
+            "@pod-container-config/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "hostname", parameterName: "hostname", type: "string?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-sysctl",
+        methodID: "podContainerConfig.setSysctl",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-sysctl",
+        ],
+        resource: "pod-container-config",
+        operation: "set-sysctl",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-sysctl @ ...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.sysctl",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/sysctl",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.sysctl",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-sysctl",
+            "@pod-container-config/example",
+            "key=value",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "key-value", parameterName: "keyValue", type: "string", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-mounts",
+        methodID: "podContainerConfig.setMounts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-mounts",
+        ],
+        resource: "pod-container-config",
+        operation: "set-mounts",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-mounts @ @...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.mounts",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/mounts",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.mounts",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-mounts",
+            "@pod-container-config/example",
+            "@mount/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "mount", parameterName: "mount", type: "reference:mount", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-masked-paths",
+        methodID: "podContainerConfig.setMaskedPaths",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-masked-paths",
+        ],
+        resource: "pod-container-config",
+        operation: "set-masked-paths",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-masked-paths @ ...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.maskedPaths",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/maskedpaths",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.maskedPaths",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-masked-paths",
+            "@pod-container-config/example",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "path", parameterName: "path", type: "container-path", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-readonly-paths",
+        methodID: "podContainerConfig.setReadonlyPaths",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-readonly-paths",
+        ],
+        resource: "pod-container-config",
+        operation: "set-readonly-paths",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-readonly-paths @ ...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.readonlyPaths",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/readonlypaths",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.readonlyPaths",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-readonly-paths",
+            "@pod-container-config/example",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "path", parameterName: "path", type: "container-path", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-sockets",
+        methodID: "podContainerConfig.setSockets",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-sockets",
+        ],
+        resource: "pod-container-config",
+        operation: "set-sockets",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-sockets @ @...",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.sockets",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/sockets",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.sockets",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-sockets",
+            "@pod-container-config/example",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-dns",
+        methodID: "podContainerConfig.setDNS",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-dns",
+        ],
+        resource: "pod-container-config",
+        operation: "set-dns",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-dns @ @|null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.dns",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/dns",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.dns",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-dns",
+            "@pod-container-config/example",
+            "@dns/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "dns", parameterName: "dns", type: "reference:dns?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-hosts",
+        methodID: "podContainerConfig.setHosts",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-hosts",
+        ],
+        resource: "pod-container-config",
+        operation: "set-hosts",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-hosts @ @|null",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.hosts",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/hosts",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.hosts",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-hosts",
+            "@pod-container-config/example",
+            "@hosts/example",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "hosts", parameterName: "hosts", type: "reference:hosts?", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod-container-config:set-use-init",
+        methodID: "podContainerConfig.setUseInit",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod-container-config:set-use-init",
+        ],
+        resource: "pod-container-config",
+        operation: "set-use-init",
+        shape: .reference,
+        signature: "ghostbox cn:pod-container-config:set-use-init @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.ContainerConfiguration.useInit",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/containerconfiguration/useinit",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.ContainerConfiguration.useInit",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod-container-config:set-use-init",
+            "@pod-container-config/example",
+            "true",
+        ],
+        positionals: [
+            .init(name: "pod-container-config", parameterName: "podContainerConfig", type: "reference:pod-container-config", required: true, repeatable: false),
+            .init(name: "enabled", parameterName: "enabled", type: "bool", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:create-direct",
+        methodID: "pod.createDirect",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:create-direct",
+        ],
+        resource: "pod",
+        operation: "create-direct",
+        shape: .create,
+        signature: "ghostbox cn:pod:create-direct \n--vmm @\n--configuration @\n-> @",
+        resultType: "reference:pod",
+        appleAPISymbol: "LinuxPod.init(_:vmm:logger:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/init(_:vmm:logger:configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.init(_:vmm:logger:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:create-direct",
+            "example",
+            "--vmm",
+            "@vmm/example",
+            "--configuration",
+            "@pod-config/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--vmm"], parameterName: "vmm", type: "reference:vmm", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--configuration"], parameterName: "configuration", type: "reference:pod-config", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:id",
+        methodID: "pod.id",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:id",
+        ],
+        resource: "pod",
+        operation: "id",
+        shape: .reference,
+        signature: "ghostbox cn:pod:id @ -> ",
+        resultType: "string",
+        appleAPISymbol: "LinuxPod.id",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/id",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.id",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:id",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:config",
+        methodID: "pod.config",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:config",
+        ],
+        resource: "pod",
+        operation: "config",
+        shape: .reference,
+        signature: "ghostbox cn:pod:config @ -> @",
+        resultType: "reference:pod-config",
+        appleAPISymbol: "LinuxPod.config",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/config",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.config",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:config",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:cpus",
+        methodID: "pod.cpus",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:cpus",
+        ],
+        resource: "pod",
+        operation: "cpus",
+        shape: .reference,
+        signature: "ghostbox cn:pod:cpus @ -> ",
+        resultType: "int",
+        appleAPISymbol: "LinuxPod.cpus",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/cpus",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.cpus",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:cpus",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:memory",
+        methodID: "pod.memory",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:memory",
+        ],
+        resource: "pod",
+        operation: "memory",
+        shape: .reference,
+        signature: "ghostbox cn:pod:memory @ -> ",
+        resultType: "uint64",
+        appleAPISymbol: "LinuxPod.memoryInBytes",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/memoryinbytes",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.memoryInBytes",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:memory",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:interfaces",
+        methodID: "pod.interfaces",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:interfaces",
+        ],
+        resource: "pod",
+        operation: "interfaces",
+        shape: .reference,
+        signature: "ghostbox cn:pod:interfaces @ -> @...",
+        resultType: "reference:interface[]",
+        appleAPISymbol: "LinuxPod.interfaces",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/interfaces",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.interfaces",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:interfaces",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:add-container",
+        methodID: "pod.addContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:add-container",
+        ],
+        resource: "pod",
+        operation: "add-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:add-container @\n\n--rootfs @\n--configuration @\n-> @",
+        resultType: "reference:pod-container",
+        appleAPISymbol: "LinuxPod.addContainer(_:rootfs:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/addcontainer(_:rootfs:configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.addContainer(_:rootfs:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:add-container",
+            "@pod/example",
+            "example",
+            "--rootfs",
+            "@mount/example",
+            "--configuration",
+            "@pod-container-config/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "container", parameterName: "container", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--rootfs"], parameterName: "rootfs", type: "reference:mount", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--configuration"], parameterName: "configuration", type: "reference:pod-container-config", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:create",
+        methodID: "pod.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:create",
+        ],
+        resource: "pod",
+        operation: "create",
+        shape: .reference,
+        signature: "ghostbox cn:pod:create @",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.create()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/create()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.create()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:create",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:start-container",
+        methodID: "pod.startContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:start-container",
+        ],
+        resource: "pod",
+        operation: "start-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:start-container @ @",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.startContainer(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/startcontainer(_:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.startContainer(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:start-container",
+            "@pod/example",
+            "@pod-container/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:stop-container",
+        methodID: "pod.stopContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:stop-container",
+        ],
+        resource: "pod",
+        operation: "stop-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:stop-container @ @",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.stopContainer(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/stopcontainer(_:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.stopContainer(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:stop-container",
+            "@pod/example",
+            "@pod-container/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:stop",
+        methodID: "pod.stop",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:stop",
+        ],
+        resource: "pod",
+        operation: "stop",
+        shape: .reference,
+        signature: "ghostbox cn:pod:stop @",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.stop()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/stop()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.stop()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:stop",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:kill-container",
+        methodID: "pod.killContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:kill-container",
+        ],
+        resource: "pod",
+        operation: "kill-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:kill-container @ @ ",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.killContainer(_:signal:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/killcontainer(_:signal:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.killContainer(_:signal:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:kill-container",
+            "@pod/example",
+            "@pod-container/example",
+            "SIGTERM",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+            .init(name: "signal", parameterName: "signal", type: "linux-signal", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:wait-container",
+        methodID: "pod.waitContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:wait-container",
+        ],
+        resource: "pod",
+        operation: "wait-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:wait-container @\n@\n[--timeout-seconds ]\n-> ",
+        resultType: "exit-status",
+        appleAPISymbol: "LinuxPod.waitContainer(_:timeoutInSeconds:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/waitcontainer(_:timeoutinseconds:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.waitContainer(_:timeoutInSeconds:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:wait-container",
+            "@pod/example",
+            "@pod-container/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--timeout-seconds"], parameterName: "timeoutSeconds", type: "int64", required: false, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:resize-container",
+        methodID: "pod.resizeContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:resize-container",
+        ],
+        resource: "pod",
+        operation: "resize-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:resize-container @\n@\n\n",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.resizeContainer(_:to:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/resizecontainer(_:to:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.resizeContainer(_:to:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:resize-container",
+            "@pod/example",
+            "@pod-container/example",
+            "1",
+            "1",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+            .init(name: "width", parameterName: "width", type: "uint16", required: true, repeatable: false),
+            .init(name: "height", parameterName: "height", type: "uint16", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:exec-in-container",
+        methodID: "pod.execInContainer",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:exec-in-container",
+        ],
+        resource: "pod",
+        operation: "exec-in-container",
+        shape: .reference,
+        signature: "ghostbox cn:pod:exec-in-container @\n@\n\n--configuration @\n-> @",
+        resultType: "reference:process",
+        appleAPISymbol: "LinuxPod.execInContainer(_:processID:configuration:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/execincontainer(_:processid:configuration:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.execInContainer(_:processID:configuration:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:exec-in-container",
+            "@pod/example",
+            "@pod-container/example",
+            "example",
+            "--configuration",
+            "@process-config/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+            .init(name: "process", parameterName: "process", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--configuration"], parameterName: "configuration", type: "reference:process-config", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:list-containers",
+        methodID: "pod.listContainers",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:list-containers",
+        ],
+        resource: "pod",
+        operation: "list-containers",
+        shape: .reference,
+        signature: "ghostbox cn:pod:list-containers @ -> @...",
+        resultType: "reference:pod-container[]",
+        appleAPISymbol: "LinuxPod.listContainers()",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/listcontainers()",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.listContainers()",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:list-containers",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:statistics",
+        methodID: "pod.statistics",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:statistics",
+        ],
+        resource: "pod",
+        operation: "statistics",
+        shape: .reference,
+        signature: "ghostbox cn:pod:statistics @\n[--container @]...\n[--category ]...\n-> ...",
+        resultType: "container-statistics[]",
+        appleAPISymbol: "LinuxPod.statistics(containerIDs:categories:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/statistics(containerids:categories:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.statistics(containerIDs:categories:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:statistics",
+            "@pod/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--container"], parameterName: "container", type: "reference:pod-container", required: false, repeatable: true, defaultValue: nil),
+            .init(names: ["--category"], parameterName: "category", type: "statistics-category", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:dial-vsock",
+        methodID: "pod.dialVsock",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:dial-vsock",
+        ],
+        resource: "pod",
+        operation: "dial-vsock",
+        shape: .reference,
+        signature: "ghostbox cn:pod:dial-vsock @\n\n-> @",
+        resultType: "reference:file-handle",
+        appleAPISymbol: "LinuxPod.dialVsock(port:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/dialvsock(port:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.dialVsock(port:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:dial-vsock",
+            "@pod/example",
+            "1",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "port", parameterName: "port", type: "uint32", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:filesystem-operation",
+        methodID: "pod.filesystemOperation",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:filesystem-operation",
+        ],
+        resource: "pod",
+        operation: "filesystem-operation",
+        shape: .reference,
+        signature: "ghostbox cn:pod:filesystem-operation @\n@\n\n",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.filesystemOperation(_:operation:path:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/filesystemoperation(_:operation:path:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.filesystemOperation(_:operation:path:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:filesystem-operation",
+            "@pod/example",
+            "@pod-container/example",
+            "freeze",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+            .init(name: "operation", parameterName: "operation", type: "freeze|thaw|trim", required: true, repeatable: false),
+            .init(name: "path", parameterName: "path", type: "container-path", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:close-container-stdin",
+        methodID: "pod.closeContainerStdin",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:close-container-stdin",
+        ],
+        resource: "pod",
+        operation: "close-container-stdin",
+        shape: .reference,
+        signature: "ghostbox cn:pod:close-container-stdin @ @",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.closeContainerStdin(_:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/closecontainerstdin(_:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.closeContainerStdin(_:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:close-container-stdin",
+            "@pod/example",
+            "@pod-container/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:pod:relay-unix-socket",
+        methodID: "pod.relayUnixSocket",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:pod:relay-unix-socket",
+        ],
+        resource: "pod",
+        operation: "relay-unix-socket",
+        shape: .reference,
+        signature: "ghostbox cn:pod:relay-unix-socket @\n@\n@",
+        resultType: "void",
+        appleAPISymbol: "LinuxPod.relayUnixSocket(_:socket:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerization/linuxpod/relayunixsocket(_:socket:)",
+        swiftModule: nil,
+        swiftSymbol: "LinuxPod.relayUnixSocket(_:socket:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:pod:relay-unix-socket",
+            "@pod/example",
+            "@pod-container/example",
+            "@socket/example",
+        ],
+        positionals: [
+            .init(name: "pod", parameterName: "pod", type: "reference:pod", required: true, repeatable: false),
+            .init(name: "pod-container", parameterName: "podContainer", type: "reference:pod-container", required: true, repeatable: false),
+            .init(name: "socket", parameterName: "socket", type: "reference:socket", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:content-store:create",
+        methodID: "contentStore.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:content-store:create",
+        ],
+        resource: "content-store",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:content-store:create \n--path \n-> @",
+        resultType: "reference:content-store",
+        appleAPISymbol: "LocalContentStore.init(path:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/localcontentstore/init(path:)",
+        swiftModule: nil,
+        swiftSymbol: "LocalContentStore.init(path:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:content-store:create",
+            "example",
+            "--path",
+            "/tmp/example",
+        ],
+        positionals: [
+            .init(name: "content-store", parameterName: "contentStore", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--path"], parameterName: "path", type: "host-url", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:authentication:create-basic",
+        methodID: "authentication.createBasic",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:authentication:create-basic",
+        ],
+        resource: "authentication",
+        operation: "create-basic",
+        shape: .create,
+        signature: "ghostbox cn:authentication:create-basic \n--username \n--password \n-> @",
+        resultType: "reference:authentication",
+        appleAPISymbol: "BasicAuthentication.init(username:password:)",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationoci/basicauthentication/init(username:password:)",
+        swiftModule: nil,
+        swiftSymbol: "BasicAuthentication.init(username:password:)",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:authentication:create-basic",
+            "example",
+            "--username",
+            "example",
+            "--password",
+            "example",
+        ],
+        positionals: [
+            .init(name: "authentication", parameterName: "authentication", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--username"], parameterName: "username", type: "string", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--password"], parameterName: "password", type: "string", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cn:progress-handler:create",
+        methodID: "progressHandler.create",
+        namespace: "cn",
+        sourceKind: "direct",
+        aliases: [
+            "containerization:progress-handler:create",
+        ],
+        resource: "progress-handler",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cn:progress-handler:create \n--writer @\n-> @",
+        resultType: "reference:progress-handler",
+        appleAPISymbol: "ProgressHandler",
+        appleDocumentationURL: "https://apple.github.io/containerization/documentation/containerizationextras/progresshandler",
+        swiftModule: nil,
+        swiftSymbol: "ProgressHandler",
+        swiftSource: nil,
+        exampleArguments: [
+            "cn:progress-handler:create",
+            "example",
+            "--writer",
+            "@writer/example",
+        ],
+        positionals: [
+            .init(name: "progress-handler", parameterName: "progressHandler", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--writer"], parameterName: "writer", type: "reference:writer", required: true, repeatable: false, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:volume:create",
+        methodID: "volume.create",
+        namespace: "cr",
+        sourceKind: "ghostvm-adapter",
+        aliases: [
+            "container:volume:create",
+        ],
+        resource: "volume",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cr:volume:create \n[--size=8589934592]\n-> @",
+        resultType: "reference:volume",
+        appleAPISymbol: "GhostboxVolumeStore.create(name:sizeInBytes:)",
+        appleDocumentationURL: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L32-L85",
+        swiftModule: "GhostVMContainerRuntime",
+        swiftSymbol: "GhostboxVolumeStore.create(name:sizeInBytes:)",
+        swiftSource: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:32",
+        exampleArguments: [
+            "cr:volume:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "volume", parameterName: "volume", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--size"], parameterName: "size", type: "uint64", required: false, repeatable: false, defaultValue: .unsignedInteger(8589934592)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:volume:list",
+        methodID: "volume.list",
+        namespace: "cr",
+        sourceKind: "ghostvm-adapter",
+        aliases: [
+            "container:volume:list",
+        ],
+        resource: "volume",
+        operation: "list",
+        shape: .static,
+        signature: "ghostbox cr:volume:list -> @...",
+        resultType: "reference:volume[]",
+        appleAPISymbol: "GhostboxVolumeStore.list()",
+        appleDocumentationURL: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L88-L91",
+        swiftModule: "GhostVMContainerRuntime",
+        swiftSymbol: "GhostboxVolumeStore.list()",
+        swiftSource: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:88",
+        exampleArguments: [
+            "cr:volume:list",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:volume:inspect",
+        methodID: "volume.inspect",
+        namespace: "cr",
+        sourceKind: "ghostvm-adapter",
+        aliases: [
+            "container:volume:inspect",
+        ],
+        resource: "volume",
+        operation: "inspect",
+        shape: .reference,
+        signature: "ghostbox cr:volume:inspect @ -> ",
+        resultType: "volume-metadata",
+        appleAPISymbol: "GhostboxVolumeStore.inspect(name:)",
+        appleDocumentationURL: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L93-L96",
+        swiftModule: "GhostVMContainerRuntime",
+        swiftSymbol: "GhostboxVolumeStore.inspect(name:)",
+        swiftSource: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:93",
+        exampleArguments: [
+            "cr:volume:inspect",
+            "@volume/example",
+        ],
+        positionals: [
+            .init(name: "volume", parameterName: "volume", type: "reference:volume", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:volume:mount",
+        methodID: "volume.mount",
+        namespace: "cr",
+        sourceKind: "ghostvm-adapter",
+        aliases: [
+            "container:volume:mount",
+        ],
+        resource: "volume",
+        operation: "mount",
+        shape: .reference,
+        signature: "ghostbox cr:volume:mount @\n\n--destination \n[--read-only=false]\n-> @",
+        resultType: "reference:mount",
+        appleAPISymbol: "GhostboxVolumeStore.makeMount(volumeName:mountReference:destination:readOnly:)",
+        appleDocumentationURL: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L110-L130",
+        swiftModule: "GhostVMContainerRuntime",
+        swiftSymbol: "GhostboxVolumeStore.makeMount(volumeName:mountReference:destination:readOnly:)",
+        swiftSource: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:110",
+        exampleArguments: [
+            "cr:volume:mount",
+            "@volume/example",
+            "example",
+            "--destination",
+            "/example",
+        ],
+        positionals: [
+            .init(name: "volume", parameterName: "volume", type: "reference:volume", required: true, repeatable: false),
+            .init(name: "mount", parameterName: "mount", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--destination"], parameterName: "destination", type: "container-path", required: true, repeatable: false, defaultValue: nil),
+            .init(names: ["--read-only"], parameterName: "readOnly", type: "bool", required: false, repeatable: false, defaultValue: .boolean(false)),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:volume:delete",
+        methodID: "volume.delete",
+        namespace: "cr",
+        sourceKind: "ghostvm-adapter",
+        aliases: [
+            "container:volume:delete",
+        ],
+        resource: "volume",
+        operation: "delete",
+        shape: .reference,
+        signature: "ghostbox cr:volume:delete @",
+        resultType: "void",
+        appleAPISymbol: "GhostboxVolumeStore.delete(name:)",
+        appleDocumentationURL: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift#L98-L108",
+        swiftModule: "GhostVMContainerRuntime",
+        swiftSymbol: "GhostboxVolumeStore.delete(name:)",
+        swiftSource: "macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift:98",
+        exampleArguments: [
+            "cr:volume:delete",
+            "@volume/example",
+        ],
+        positionals: [
+            .init(name: "volume", parameterName: "volume", type: "reference:volume", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:memory-size:create",
+        methodID: "crMemorySize.create",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:memory-size:create",
+        ],
+        resource: "memory-size",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cr:memory-size:create  \n-> @",
+        resultType: "reference:memory-size",
+        appleAPISymbol: "MemorySize.init(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L27-L29",
+        swiftModule: "ContainerPersistence",
+        swiftSymbol: "MemorySize.init(_:)",
+        swiftSource: "Sources/ContainerPersistence/MemorySize.swift:27",
+        exampleArguments: [
+            "cr:memory-size:create",
+            "example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "memory-size", parameterName: "memorySize", type: "name", required: true, repeatable: false),
+            .init(name: "value", parameterName: "value", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:memory-size:formatted",
+        methodID: "crMemorySize.formatted",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:memory-size:formatted",
+        ],
+        resource: "memory-size",
+        operation: "formatted",
+        shape: .reference,
+        signature: "ghostbox cr:memory-size:formatted @ -> ",
+        resultType: "string",
+        appleAPISymbol: "MemorySize.formatted",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L51-L55",
+        swiftModule: "ContainerPersistence",
+        swiftSymbol: "MemorySize.formatted",
+        swiftSource: "Sources/ContainerPersistence/MemorySize.swift:51",
+        exampleArguments: [
+            "cr:memory-size:formatted",
+            "@memory-size/example",
+        ],
+        positionals: [
+            .init(name: "memory-size", parameterName: "memorySize", type: "reference:memory-size", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:memory-size:to-uint64",
+        methodID: "crMemorySize.toUInt64",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:memory-size:to-uint64",
+        ],
+        resource: "memory-size",
+        operation: "to-uint64",
+        shape: .reference,
+        signature: "ghostbox cr:memory-size:to-uint64 @\n\n-> ",
+        resultType: "uint64",
+        appleAPISymbol: "MemorySize.toUInt64(unit:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerPersistence/MemorySize.swift#L59-L61",
+        swiftModule: "ContainerPersistence",
+        swiftSymbol: "MemorySize.toUInt64(unit:)",
+        swiftSource: "Sources/ContainerPersistence/MemorySize.swift:59",
+        exampleArguments: [
+            "cr:memory-size:to-uint64",
+            "@memory-size/example",
+            "bytes",
+        ],
+        positionals: [
+            .init(name: "memory-size", parameterName: "memorySize", type: "reference:memory-size", required: true, repeatable: false),
+            .init(name: "unit", parameterName: "unit", type: "bytes|kibibytes|mebibytes|gibibytes|tebibytes|pebibytes", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:create",
+        methodID: "crResourceLabels.create",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:create",
+        ],
+        resource: "resource-labels",
+        operation: "create",
+        shape: .create,
+        signature: "ghostbox cr:resource-labels:create \n[--label ]...\n-> @",
+        resultType: "reference:resource-labels",
+        appleAPISymbol: "ResourceLabels.init(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L39-L44",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.init(_:)",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:39",
+        exampleArguments: [
+            "cr:resource-labels:create",
+            "example",
+        ],
+        positionals: [
+            .init(name: "resource-labels", parameterName: "resourceLabels", type: "name", required: true, repeatable: false),
+        ],
+        options: [
+            .init(names: ["--label"], parameterName: "label", type: "string", required: false, repeatable: true, defaultValue: nil),
+        ],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:validate-key",
+        methodID: "crResourceLabels.validateKey",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:validate-key",
+        ],
+        resource: "resource-labels",
+        operation: "validate-key",
+        shape: .static,
+        signature: "ghostbox cr:resource-labels:validate-key ",
+        resultType: "void",
+        appleAPISymbol: "ResourceLabels.validateLabelKey(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L46-L57",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.validateLabelKey(_:)",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:46",
+        exampleArguments: [
+            "cr:resource-labels:validate-key",
+            "example",
+        ],
+        positionals: [
+            .init(name: "key", parameterName: "key", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:validate",
+        methodID: "crResourceLabels.validate",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:validate",
+        ],
+        resource: "resource-labels",
+        operation: "validate",
+        shape: .static,
+        signature: "ghostbox cr:resource-labels:validate  ",
+        resultType: "void",
+        appleAPISymbol: "ResourceLabels.validateLabel(key:value:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L59-L65",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.validateLabel(key:value:)",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:59",
+        exampleArguments: [
+            "cr:resource-labels:validate",
+            "example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "key", parameterName: "key", type: "string", required: true, repeatable: false),
+            .init(name: "value", parameterName: "value", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:dictionary",
+        methodID: "crResourceLabels.dictionary",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:dictionary",
+        ],
+        resource: "resource-labels",
+        operation: "dictionary",
+        shape: .reference,
+        signature: "ghostbox cr:resource-labels:dictionary @ -> ",
+        resultType: "string-map",
+        appleAPISymbol: "ResourceLabels.dictionary",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L25",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.dictionary",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:25",
+        exampleArguments: [
+            "cr:resource-labels:dictionary",
+            "@resource-labels/example",
+        ],
+        positionals: [
+            .init(name: "resource-labels", parameterName: "resourceLabels", type: "reference:resource-labels", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:value",
+        methodID: "crResourceLabels.value",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:value",
+        ],
+        resource: "resource-labels",
+        operation: "value",
+        shape: .reference,
+        signature: "ghostbox cr:resource-labels:value @\n\n-> |null",
+        resultType: "string?",
+        appleAPISymbol: "ResourceLabels.subscript(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L89-L92",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.subscript(_:)",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:90",
+        exampleArguments: [
+            "cr:resource-labels:value",
+            "@resource-labels/example",
+            "example",
+        ],
+        positionals: [
+            .init(name: "resource-labels", parameterName: "resourceLabels", type: "reference:resource-labels", required: true, repeatable: false),
+            .init(name: "key", parameterName: "key", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:key-length-max",
+        methodID: "crResourceLabels.keyLengthMax",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:key-length-max",
+        ],
+        resource: "resource-labels",
+        operation: "key-length-max",
+        shape: .static,
+        signature: "ghostbox cr:resource-labels:key-length-max -> ",
+        resultType: "int",
+        appleAPISymbol: "ResourceLabels.keyLengthMax",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L21",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.keyLengthMax",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:21",
+        exampleArguments: [
+            "cr:resource-labels:key-length-max",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:resource-labels:label-length-max",
+        methodID: "crResourceLabels.labelLengthMax",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:resource-labels:label-length-max",
+        ],
+        resource: "resource-labels",
+        operation: "label-length-max",
+        shape: .static,
+        signature: "ghostbox cr:resource-labels:label-length-max -> ",
+        resultType: "int",
+        appleAPISymbol: "ResourceLabels.labelLengthMax",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/ContainerResource/Common/ResourceLabels.swift#L23",
+        swiftModule: "ContainerResource",
+        swiftSymbol: "ResourceLabels.labelLengthMax",
+        swiftSource: "Sources/ContainerResource/Common/ResourceLabels.swift:23",
+        exampleArguments: [
+            "cr:resource-labels:label-length-max",
+        ],
+        positionals: [],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:memory-as-mib",
+        methodID: "crParser.memoryAsMiB",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:memory-as-mib",
+        ],
+        resource: "parser",
+        operation: "memory-as-mib",
+        shape: .static,
+        signature: "ghostbox cr:parser:memory-as-mib  -> ",
+        resultType: "int64",
+        appleAPISymbol: "Parser.memoryStringAsMiB(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L57-L61",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.memoryStringAsMiB(_:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:57",
+        exampleArguments: [
+            "cr:parser:memory-as-mib",
+            "example",
+        ],
+        positionals: [
+            .init(name: "memory", parameterName: "memory", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:memory-as-bytes",
+        methodID: "crParser.memoryAsBytes",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:memory-as-bytes",
+        ],
+        resource: "parser",
+        operation: "memory-as-bytes",
+        shape: .static,
+        signature: "ghostbox cr:parser:memory-as-bytes  -> ",
+        resultType: "uint64",
+        appleAPISymbol: "Parser.memoryStringAsBytes(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L63-L67",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.memoryStringAsBytes(_:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:63",
+        exampleArguments: [
+            "cr:parser:memory-as-bytes",
+            "example",
+        ],
+        positionals: [
+            .init(name: "memory", parameterName: "memory", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:labels",
+        methodID: "crParser.labels",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:labels",
+        ],
+        resource: "parser",
+        operation: "labels",
+        shape: .static,
+        signature: "ghostbox cr:parser:labels ... -> ",
+        resultType: "string-map",
+        appleAPISymbol: "Parser.labels(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L244-L261",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.labels(_:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:244",
+        exampleArguments: [
+            "cr:parser:labels",
+            "example",
+        ],
+        positionals: [
+            .init(name: "label", parameterName: "label", type: "string", required: true, repeatable: true),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:platform",
+        methodID: "crParser.platform",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:platform",
+        ],
+        resource: "parser",
+        operation: "platform",
+        shape: .static,
+        signature: "ghostbox cr:parser:platform  -> ",
+        resultType: "oci-platform",
+        appleAPISymbol: "Parser.platform(from:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L101-L103",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.platform(from:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:101",
+        exampleArguments: [
+            "cr:parser:platform",
+            "example",
+        ],
+        positionals: [
+            .init(name: "platform", parameterName: "platform", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:is-valid-domain-name",
+        methodID: "crParser.isValidDomainName",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:is-valid-domain-name",
+        ],
+        resource: "parser",
+        operation: "is-valid-domain-name",
+        shape: .static,
+        signature: "ghostbox cr:parser:is-valid-domain-name  -> ",
+        resultType: "bool",
+        appleAPISymbol: "Parser.isValidDomainName(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L895-L900",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.isValidDomainName(_:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:895",
+        exampleArguments: [
+            "cr:parser:is-valid-domain-name",
+            "example",
+        ],
+        positionals: [
+            .init(name: "name", parameterName: "name", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:is-valid-domain-name-label",
+        methodID: "crParser.isValidDomainNameLabel",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:is-valid-domain-name-label",
+        ],
+        resource: "parser",
+        operation: "is-valid-domain-name-label",
+        shape: .static,
+        signature: "ghostbox cr:parser:is-valid-domain-name-label  -> ",
+        resultType: "bool",
+        appleAPISymbol: "Parser.isValidDomainNameLabel(_:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L902-L908",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.isValidDomainNameLabel(_:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:902",
+        exampleArguments: [
+            "cr:parser:is-valid-domain-name-label",
+            "example",
+        ],
+        positionals: [
+            .init(name: "label", parameterName: "label", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+    .init(
+        commandID: "cr:parser:parse-bool",
+        methodID: "crParser.parseBool",
+        namespace: "cr",
+        sourceKind: "direct",
+        aliases: [
+            "container:parser:parse-bool",
+        ],
+        resource: "parser",
+        operation: "parse-bool",
+        shape: .static,
+        signature: "ghostbox cr:parser:parse-bool  -> |null",
+        resultType: "bool?",
+        appleAPISymbol: "Parser.parseBool(string:)",
+        appleDocumentationURL: "https://github.com/apple/container/blob/6e65319fe476ffe8db8ddaf828a537ed36fe2859/Sources/Services/ContainerAPIService/Client/Parser.swift#L1061-L1063",
+        swiftModule: "ContainerAPIClient",
+        swiftSymbol: "Parser.parseBool(string:)",
+        swiftSource: "Sources/Services/ContainerAPIService/Client/Parser.swift:1061",
+        exampleArguments: [
+            "cr:parser:parse-bool",
+            "example",
+        ],
+        positionals: [
+            .init(name: "value", parameterName: "value", type: "string", required: true, repeatable: false),
+        ],
+        options: [],
+        implicitDefaults: [:]
+    ),
+]
diff --git a/macOS/GhostTools/Sources/ghostbox/Generated/GhostboxCommandFixtures.generated.swift b/macOS/GhostTools/Sources/ghostbox/Generated/GhostboxCommandFixtures.generated.swift
new file mode 100644
index 0000000..d19d87d
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/Generated/GhostboxCommandFixtures.generated.swift
@@ -0,0 +1,292 @@
+// Generated by scripts/generate-ghostbox-command-catalog.py. Do not edit.
+
+struct GhostboxCommandFixture: Sendable {
+    let commandID: String
+    let methodID: String
+    let argv: [String]
+}
+
+let ghostboxCommandFixtures: [GhostboxCommandFixture] = [
+    .init(commandID: "cn:image-store:create", methodID: "imageStore.create", argv: ["cn:image-store:create", "example", "--path", "/tmp/example"]),
+    .init(commandID: "cn:image-store:default", methodID: "imageStore.default", argv: ["cn:image-store:default"]),
+    .init(commandID: "cn:image-store:path", methodID: "imageStore.path", argv: ["cn:image-store:path", "@image-store/example"]),
+    .init(commandID: "cn:image-store:get", methodID: "imageStore.get", argv: ["cn:image-store:get", "@image-store/example", "example"]),
+    .init(commandID: "cn:image-store:list", methodID: "imageStore.list", argv: ["cn:image-store:list", "@image-store/example"]),
+    .init(commandID: "cn:image-store:create-image", methodID: "imageStore.createImage", argv: ["cn:image-store:create-image", "@image-store/example", "@image-description/example"]),
+    .init(commandID: "cn:image-store:delete", methodID: "imageStore.delete", argv: ["cn:image-store:delete", "@image-store/example", "example"]),
+    .init(commandID: "cn:image-store:clean-up-orphaned-blobs", methodID: "imageStore.cleanUpOrphanedBlobs", argv: ["cn:image-store:clean-up-orphaned-blobs", "@image-store/example"]),
+    .init(commandID: "cn:image-store:calculate-orphaned-blobs-size", methodID: "imageStore.calculateOrphanedBlobsSize", argv: ["cn:image-store:calculate-orphaned-blobs-size", "@image-store/example"]),
+    .init(commandID: "cn:image-store:tag", methodID: "imageStore.tag", argv: ["cn:image-store:tag", "@image-store/example", "example", "example"]),
+    .init(commandID: "cn:image-store:pull", methodID: "imageStore.pull", argv: ["cn:image-store:pull", "@image-store/example", "example"]),
+    .init(commandID: "cn:image-store:push", methodID: "imageStore.push", argv: ["cn:image-store:push", "@image-store/example", "example"]),
+    .init(commandID: "cn:image-store:push-many", methodID: "imageStore.pushMany", argv: ["cn:image-store:push-many", "@image-store/example", "example"]),
+    .init(commandID: "cn:image-store:save", methodID: "imageStore.save", argv: ["cn:image-store:save", "@image-store/example", "example", "--out", "/tmp/example"]),
+    .init(commandID: "cn:image-store:load", methodID: "imageStore.load", argv: ["cn:image-store:load", "@image-store/example", "/tmp/example"]),
+    .init(commandID: "cn:image-store:get-init-image", methodID: "imageStore.getInitImage", argv: ["cn:image-store:get-init-image", "@image-store/example", "example"]),
+    .init(commandID: "cn:image-description:create", methodID: "imageDescription.create", argv: ["cn:image-description:create", "example", "example", "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:0000000000000000000000000000000000000000000000000000000000000000\",\"size\":0}"]),
+    .init(commandID: "cn:image-description:reference", methodID: "imageDescription.reference", argv: ["cn:image-description:reference", "@image-description/example"]),
+    .init(commandID: "cn:image-description:descriptor", methodID: "imageDescription.descriptor", argv: ["cn:image-description:descriptor", "@image-description/example"]),
+    .init(commandID: "cn:image-description:digest", methodID: "imageDescription.digest", argv: ["cn:image-description:digest", "@image-description/example"]),
+    .init(commandID: "cn:image-description:media-type", methodID: "imageDescription.mediaType", argv: ["cn:image-description:media-type", "@image-description/example"]),
+    .init(commandID: "cn:image:create", methodID: "image.create", argv: ["cn:image:create", "example", "@image-description/example", "@content-store/example"]),
+    .init(commandID: "cn:image:description", methodID: "image.description", argv: ["cn:image:description", "@image/example"]),
+    .init(commandID: "cn:image:descriptor", methodID: "image.descriptor", argv: ["cn:image:descriptor", "@image/example"]),
+    .init(commandID: "cn:image:digest", methodID: "image.digest", argv: ["cn:image:digest", "@image/example"]),
+    .init(commandID: "cn:image:media-type", methodID: "image.mediaType", argv: ["cn:image:media-type", "@image/example"]),
+    .init(commandID: "cn:image:reference", methodID: "image.reference", argv: ["cn:image:reference", "@image/example"]),
+    .init(commandID: "cn:image:index", methodID: "image.index", argv: ["cn:image:index", "@image/example"]),
+    .init(commandID: "cn:image:manifest", methodID: "image.manifest", argv: ["cn:image:manifest", "@image/example", "linux/arm64"]),
+    .init(commandID: "cn:image:descriptor-for", methodID: "image.descriptorFor", argv: ["cn:image:descriptor-for", "@image/example", "linux/arm64"]),
+    .init(commandID: "cn:image:config", methodID: "image.config", argv: ["cn:image:config", "@image/example", "linux/arm64"]),
+    .init(commandID: "cn:image:referenced-digests", methodID: "image.referencedDigests", argv: ["cn:image:referenced-digests", "@image/example"]),
+    .init(commandID: "cn:image:get-content", methodID: "image.getContent", argv: ["cn:image:get-content", "@image/example", "example"]),
+    .init(commandID: "cn:content:path", methodID: "content.path", argv: ["cn:content:path", "@content/example"]),
+    .init(commandID: "cn:content:digest", methodID: "content.digest", argv: ["cn:content:digest", "@content/example"]),
+    .init(commandID: "cn:content:size", methodID: "content.size", argv: ["cn:content:size", "@content/example"]),
+    .init(commandID: "cn:content:data", methodID: "content.data", argv: ["cn:content:data", "@content/example"]),
+    .init(commandID: "cn:content:data-range", methodID: "content.dataRange", argv: ["cn:content:data-range", "@content/example", "1", "1"]),
+    .init(commandID: "cn:kernel-command-line:create", methodID: "kernelCommandLine.create", argv: ["cn:kernel-command-line:create", "example"]),
+    .init(commandID: "cn:kernel-command-line:create-debug", methodID: "kernelCommandLine.createDebug", argv: ["cn:kernel-command-line:create-debug", "example", "true", "1"]),
+    .init(commandID: "cn:kernel-command-line:add-debug", methodID: "kernelCommandLine.addDebug", argv: ["cn:kernel-command-line:add-debug", "@kernel-command-line/example"]),
+    .init(commandID: "cn:kernel-command-line:add-panic", methodID: "kernelCommandLine.addPanic", argv: ["cn:kernel-command-line:add-panic", "@kernel-command-line/example", "1"]),
+    .init(commandID: "cn:kernel-command-line:set-agent-log-level", methodID: "kernelCommandLine.setAgentLogLevel", argv: ["cn:kernel-command-line:set-agent-log-level", "@kernel-command-line/example", "info"]),
+    .init(commandID: "cn:kernel-command-line:kernel-arguments", methodID: "kernelCommandLine.kernelArguments", argv: ["cn:kernel-command-line:kernel-arguments", "@kernel-command-line/example"]),
+    .init(commandID: "cn:kernel-command-line:init-arguments", methodID: "kernelCommandLine.initArguments", argv: ["cn:kernel-command-line:init-arguments", "@kernel-command-line/example"]),
+    .init(commandID: "cn:kernel:create", methodID: "kernel.create", argv: ["cn:kernel:create", "example", "--path", "/tmp/example", "--platform", "linux/arm64"]),
+    .init(commandID: "cn:kernel:path", methodID: "kernel.path", argv: ["cn:kernel:path", "@kernel/example"]),
+    .init(commandID: "cn:kernel:platform", methodID: "kernel.platform", argv: ["cn:kernel:platform", "@kernel/example"]),
+    .init(commandID: "cn:kernel:kernel-arguments", methodID: "kernel.kernelArguments", argv: ["cn:kernel:kernel-arguments", "@kernel/example"]),
+    .init(commandID: "cn:kernel:init-arguments", methodID: "kernel.initArguments", argv: ["cn:kernel:init-arguments", "@kernel/example"]),
+    .init(commandID: "cn:kernel-image:from-image", methodID: "kernelImage.fromImage", argv: ["cn:kernel-image:from-image", "example", "@image/example"]),
+    .init(commandID: "cn:kernel-image:create", methodID: "kernelImage.create", argv: ["cn:kernel-image:create", "example", "example", "--kernel", "@kernel/example", "--image-store", "@image-store/example", "--content-store", "@content-store/example"]),
+    .init(commandID: "cn:kernel-image:kernel", methodID: "kernelImage.kernel", argv: ["cn:kernel-image:kernel", "@kernel-image/example", "linux/arm64"]),
+    .init(commandID: "cn:kernel-image:name", methodID: "kernelImage.name", argv: ["cn:kernel-image:name", "@kernel-image/example"]),
+    .init(commandID: "cn:kernel-image:media-type", methodID: "kernelImage.mediaType", argv: ["cn:kernel-image:media-type"]),
+    .init(commandID: "cn:init-image:from-image", methodID: "initImage.fromImage", argv: ["cn:init-image:from-image", "example", "@image/example"]),
+    .init(commandID: "cn:init-image:create", methodID: "initImage.create", argv: ["cn:init-image:create", "example", "example", "--rootfs", "/tmp/example", "--platform", "linux/arm64", "--image-store", "@image-store/example", "--content-store", "@content-store/example"]),
+    .init(commandID: "cn:init-image:init-block", methodID: "initImage.initBlock", argv: ["cn:init-image:init-block", "@init-image/example", "--at", "/tmp/example", "--platform", "linux/arm64"]),
+    .init(commandID: "cn:init-image:name", methodID: "initImage.name", argv: ["cn:init-image:name", "@init-image/example"]),
+    .init(commandID: "cn:mount:create", methodID: "mount.create", argv: ["cn:mount:create", "example", "--type", "example", "--source", "example", "--destination", "/example", "--option", "example", "--runtime-options", "{}"]),
+    .init(commandID: "cn:mount:block", methodID: "mount.block", argv: ["cn:mount:block", "example", "--format", "example", "--source", "example", "--destination", "/example"]),
+    .init(commandID: "cn:mount:share", methodID: "mount.share", argv: ["cn:mount:share", "example", "--source", "example", "--destination", "/example"]),
+    .init(commandID: "cn:mount:any", methodID: "mount.any", argv: ["cn:mount:any", "example", "--type", "example", "--source", "example", "--destination", "/example"]),
+    .init(commandID: "cn:mount:shared-mount", methodID: "mount.sharedMount", argv: ["cn:mount:shared-mount", "example", "--name", "example", "--destination", "/example"]),
+    .init(commandID: "cn:mount:clone", methodID: "mount.clone", argv: ["cn:mount:clone", "@mount/example", "--to", "/tmp/example"]),
+    .init(commandID: "cn:mount:is-block", methodID: "mount.isBlock", argv: ["cn:mount:is-block", "@mount/example"]),
+    .init(commandID: "cn:mount:type", methodID: "mount.type", argv: ["cn:mount:type", "@mount/example"]),
+    .init(commandID: "cn:mount:source", methodID: "mount.source", argv: ["cn:mount:source", "@mount/example"]),
+    .init(commandID: "cn:mount:destination", methodID: "mount.destination", argv: ["cn:mount:destination", "@mount/example"]),
+    .init(commandID: "cn:mount:options", methodID: "mount.options", argv: ["cn:mount:options", "@mount/example"]),
+    .init(commandID: "cn:mount:runtime-options", methodID: "mount.runtimeOptions", argv: ["cn:mount:runtime-options", "@mount/example"]),
+    .init(commandID: "cn:dns:create", methodID: "dns.create", argv: ["cn:dns:create", "example"]),
+    .init(commandID: "cn:dns:default-nameservers", methodID: "dns.defaultNameservers", argv: ["cn:dns:default-nameservers"]),
+    .init(commandID: "cn:dns:validate", methodID: "dns.validate", argv: ["cn:dns:validate", "@dns/example"]),
+    .init(commandID: "cn:dns:resolv-conf", methodID: "dns.resolvConf", argv: ["cn:dns:resolv-conf", "@dns/example"]),
+    .init(commandID: "cn:dns:nameservers", methodID: "dns.nameservers", argv: ["cn:dns:nameservers", "@dns/example"]),
+    .init(commandID: "cn:dns:domain", methodID: "dns.domain", argv: ["cn:dns:domain", "@dns/example"]),
+    .init(commandID: "cn:dns:search-domains", methodID: "dns.searchDomains", argv: ["cn:dns:search-domains", "@dns/example"]),
+    .init(commandID: "cn:dns:options", methodID: "dns.options", argv: ["cn:dns:options", "@dns/example"]),
+    .init(commandID: "cn:hosts-entry:create", methodID: "hostsEntry.create", argv: ["cn:hosts-entry:create", "example", "example", "example"]),
+    .init(commandID: "cn:hosts-entry:localhost-ipv4", methodID: "hostsEntry.localhostIpv4", argv: ["cn:hosts-entry:localhost-ipv4", "example"]),
+    .init(commandID: "cn:hosts-entry:localhost-ipv6", methodID: "hostsEntry.localhostIpv6", argv: ["cn:hosts-entry:localhost-ipv6", "example"]),
+    .init(commandID: "cn:hosts-entry:ipv6-localnet", methodID: "hostsEntry.ipv6Localnet", argv: ["cn:hosts-entry:ipv6-localnet", "example"]),
+    .init(commandID: "cn:hosts-entry:ipv6-mcastprefix", methodID: "hostsEntry.ipv6Mcastprefix", argv: ["cn:hosts-entry:ipv6-mcastprefix", "example"]),
+    .init(commandID: "cn:hosts-entry:ipv6-allnodes", methodID: "hostsEntry.ipv6Allnodes", argv: ["cn:hosts-entry:ipv6-allnodes", "example"]),
+    .init(commandID: "cn:hosts-entry:ipv6-allrouters", methodID: "hostsEntry.ipv6Allrouters", argv: ["cn:hosts-entry:ipv6-allrouters", "example"]),
+    .init(commandID: "cn:hosts-entry:rendered", methodID: "hostsEntry.rendered", argv: ["cn:hosts-entry:rendered", "@hosts-entry/example"]),
+    .init(commandID: "cn:hosts-entry:ip-address", methodID: "hostsEntry.ipAddress", argv: ["cn:hosts-entry:ip-address", "@hosts-entry/example"]),
+    .init(commandID: "cn:hosts-entry:hostnames", methodID: "hostsEntry.hostnames", argv: ["cn:hosts-entry:hostnames", "@hosts-entry/example"]),
+    .init(commandID: "cn:hosts-entry:comment", methodID: "hostsEntry.comment", argv: ["cn:hosts-entry:comment", "@hosts-entry/example"]),
+    .init(commandID: "cn:hosts:create", methodID: "hosts.create", argv: ["cn:hosts:create", "example"]),
+    .init(commandID: "cn:hosts:default", methodID: "hosts.default", argv: ["cn:hosts:default"]),
+    .init(commandID: "cn:hosts:hosts-file", methodID: "hosts.hostsFile", argv: ["cn:hosts:hosts-file", "@hosts/example"]),
+    .init(commandID: "cn:hosts:entries", methodID: "hosts.entries", argv: ["cn:hosts:entries", "@hosts/example"]),
+    .init(commandID: "cn:hosts:comment", methodID: "hosts.comment", argv: ["cn:hosts:comment", "@hosts/example"]),
+    .init(commandID: "cn:socket:create", methodID: "socket.create", argv: ["cn:socket:create", "example", "--source", "/tmp/example", "--destination", "/tmp/example"]),
+    .init(commandID: "cn:socket:id", methodID: "socket.id", argv: ["cn:socket:id", "@socket/example"]),
+    .init(commandID: "cn:socket:source", methodID: "socket.source", argv: ["cn:socket:source", "@socket/example"]),
+    .init(commandID: "cn:socket:destination", methodID: "socket.destination", argv: ["cn:socket:destination", "@socket/example"]),
+    .init(commandID: "cn:socket:permissions", methodID: "socket.permissions", argv: ["cn:socket:permissions", "@socket/example"]),
+    .init(commandID: "cn:socket:direction", methodID: "socket.direction", argv: ["cn:socket:direction", "@socket/example"]),
+    .init(commandID: "cn:boot-log:file", methodID: "bootLog.file", argv: ["cn:boot-log:file", "example", "--path", "/tmp/example"]),
+    .init(commandID: "cn:network:vmnet-create", methodID: "network.vmnetCreate", argv: ["cn:network:vmnet-create", "example"]),
+    .init(commandID: "cn:network:subnet", methodID: "network.subnet", argv: ["cn:network:subnet", "@network/example"]),
+    .init(commandID: "cn:network:prefix-v6", methodID: "network.prefixV6", argv: ["cn:network:prefix-v6", "@network/example"]),
+    .init(commandID: "cn:network:ipv4-gateway", methodID: "network.ipv4Gateway", argv: ["cn:network:ipv4-gateway", "@network/example"]),
+    .init(commandID: "cn:network:ipv6-gateway", methodID: "network.ipv6Gateway", argv: ["cn:network:ipv6-gateway", "@network/example"]),
+    .init(commandID: "cn:network:create-interface", methodID: "network.createInterface", argv: ["cn:network:create-interface", "@network/example", "example"]),
+    .init(commandID: "cn:network:create-interface-mtu", methodID: "network.createInterfaceMtu", argv: ["cn:network:create-interface-mtu", "@network/example", "example", "1"]),
+    .init(commandID: "cn:network:create-interface-without-gateway", methodID: "network.createInterfaceWithoutGateway", argv: ["cn:network:create-interface-without-gateway", "@network/example", "example"]),
+    .init(commandID: "cn:network:release-interface", methodID: "network.releaseInterface", argv: ["cn:network:release-interface", "@network/example", "@interface/example"]),
+    .init(commandID: "cn:interface:nat-create", methodID: "interface.natCreate", argv: ["cn:interface:nat-create", "example", "--ipv4-address", "192.0.2.2/24"]),
+    .init(commandID: "cn:interface:ipv4-address", methodID: "interface.ipv4Address", argv: ["cn:interface:ipv4-address", "@interface/example"]),
+    .init(commandID: "cn:interface:ipv4-gateway", methodID: "interface.ipv4Gateway", argv: ["cn:interface:ipv4-gateway", "@interface/example"]),
+    .init(commandID: "cn:interface:ipv6-address", methodID: "interface.ipv6Address", argv: ["cn:interface:ipv6-address", "@interface/example"]),
+    .init(commandID: "cn:interface:ipv6-gateway", methodID: "interface.ipv6Gateway", argv: ["cn:interface:ipv6-gateway", "@interface/example"]),
+    .init(commandID: "cn:interface:mac-address", methodID: "interface.macAddress", argv: ["cn:interface:mac-address", "@interface/example"]),
+    .init(commandID: "cn:interface:mtu", methodID: "interface.mtu", argv: ["cn:interface:mtu", "@interface/example"]),
+    .init(commandID: "cn:vm-config:create", methodID: "vmConfig.create", argv: ["cn:vm-config:create", "example"]),
+    .init(commandID: "cn:standard-vm-config:create", methodID: "standardVmConfig.create", argv: ["cn:standard-vm-config:create", "example", "@vm-config/example"]),
+    .init(commandID: "cn:vmm:create", methodID: "vmm.create", argv: ["cn:vmm:create", "example", "--kernel", "@kernel/example", "--initial-filesystem", "@mount/example"]),
+    .init(commandID: "cn:vmm:create-instance", methodID: "vmm.createInstance", argv: ["cn:vmm:create-instance", "@vmm/example", "@standard-vm-config/example"]),
+    .init(commandID: "cn:vm-instance:state", methodID: "vmInstance.state", argv: ["cn:vm-instance:state", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:mounts", methodID: "vmInstance.mounts", argv: ["cn:vm-instance:mounts", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:virtiofs-layout", methodID: "vmInstance.virtiofsLayout", argv: ["cn:vm-instance:virtiofs-layout", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:start", methodID: "vmInstance.start", argv: ["cn:vm-instance:start", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:stop", methodID: "vmInstance.stop", argv: ["cn:vm-instance:stop", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:pause", methodID: "vmInstance.pause", argv: ["cn:vm-instance:pause", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:resume", methodID: "vmInstance.resume", argv: ["cn:vm-instance:resume", "@vm-instance/example"]),
+    .init(commandID: "cn:vm-instance:dial", methodID: "vmInstance.dial", argv: ["cn:vm-instance:dial", "@vm-instance/example", "1"]),
+    .init(commandID: "cn:rlimit-kind:create", methodID: "rlimitKind.create", argv: ["cn:rlimit-kind:create", "example", "example"]),
+    .init(commandID: "cn:rlimit:create", methodID: "rlimit.create", argv: ["cn:rlimit:create", "example", "--kind", "@rlimit-kind/example", "--hard", "1", "--soft", "1"]),
+    .init(commandID: "cn:rlimit:create-equal", methodID: "rlimit.createEqual", argv: ["cn:rlimit:create-equal", "example", "--kind", "@rlimit-kind/example", "--limit", "1"]),
+    .init(commandID: "cn:rlimit:kind", methodID: "rlimit.kind", argv: ["cn:rlimit:kind", "@rlimit/example"]),
+    .init(commandID: "cn:rlimit:hard", methodID: "rlimit.hard", argv: ["cn:rlimit:hard", "@rlimit/example"]),
+    .init(commandID: "cn:rlimit:soft", methodID: "rlimit.soft", argv: ["cn:rlimit:soft", "@rlimit/example"]),
+    .init(commandID: "cn:rlimit:to-oci", methodID: "rlimit.toOCI", argv: ["cn:rlimit:to-oci", "@rlimit/example"]),
+    .init(commandID: "cn:capabilities:create", methodID: "capabilities.create", argv: ["cn:capabilities:create", "example"]),
+    .init(commandID: "cn:capabilities:create-uniform", methodID: "capabilities.createUniform", argv: ["cn:capabilities:create-uniform", "example", "CAP_CHOWN"]),
+    .init(commandID: "cn:capabilities:all", methodID: "capabilities.all", argv: ["cn:capabilities:all"]),
+    .init(commandID: "cn:capabilities:default-oci", methodID: "capabilities.defaultOCI", argv: ["cn:capabilities:default-oci"]),
+    .init(commandID: "cn:capabilities:bounding", methodID: "capabilities.bounding", argv: ["cn:capabilities:bounding", "@capabilities/example"]),
+    .init(commandID: "cn:capabilities:effective", methodID: "capabilities.effective", argv: ["cn:capabilities:effective", "@capabilities/example"]),
+    .init(commandID: "cn:capabilities:inheritable", methodID: "capabilities.inheritable", argv: ["cn:capabilities:inheritable", "@capabilities/example"]),
+    .init(commandID: "cn:capabilities:permitted", methodID: "capabilities.permitted", argv: ["cn:capabilities:permitted", "@capabilities/example"]),
+    .init(commandID: "cn:capabilities:ambient", methodID: "capabilities.ambient", argv: ["cn:capabilities:ambient", "@capabilities/example"]),
+    .init(commandID: "cn:capabilities:to-oci", methodID: "capabilities.toOCI", argv: ["cn:capabilities:to-oci", "@capabilities/example"]),
+    .init(commandID: "cn:process-config:default-path", methodID: "processConfig.defaultPath", argv: ["cn:process-config:default-path"]),
+    .init(commandID: "cn:process-config:create", methodID: "processConfig.create", argv: ["cn:process-config:create", "example", "example"]),
+    .init(commandID: "cn:process-config:from-image-config", methodID: "processConfig.fromImageConfig", argv: ["cn:process-config:from-image-config", "example", "{}"]),
+    .init(commandID: "cn:process-config:set-terminal-io", methodID: "processConfig.setTerminalIo", argv: ["cn:process-config:set-terminal-io", "@process-config/example", "@terminal/example"]),
+    .init(commandID: "cn:process-config:arguments", methodID: "processConfig.arguments", argv: ["cn:process-config:arguments", "@process-config/example"]),
+    .init(commandID: "cn:process-config:environment-variables", methodID: "processConfig.environmentVariables", argv: ["cn:process-config:environment-variables", "@process-config/example"]),
+    .init(commandID: "cn:process-config:working-directory", methodID: "processConfig.workingDirectory", argv: ["cn:process-config:working-directory", "@process-config/example"]),
+    .init(commandID: "cn:process-config:user", methodID: "processConfig.user", argv: ["cn:process-config:user", "@process-config/example"]),
+    .init(commandID: "cn:process-config:rlimits", methodID: "processConfig.rlimits", argv: ["cn:process-config:rlimits", "@process-config/example"]),
+    .init(commandID: "cn:process-config:no-new-privileges", methodID: "processConfig.noNewPrivileges", argv: ["cn:process-config:no-new-privileges", "@process-config/example"]),
+    .init(commandID: "cn:process-config:capabilities", methodID: "processConfig.capabilities", argv: ["cn:process-config:capabilities", "@process-config/example"]),
+    .init(commandID: "cn:process-config:terminal", methodID: "processConfig.terminal", argv: ["cn:process-config:terminal", "@process-config/example"]),
+    .init(commandID: "cn:process-config:stdin", methodID: "processConfig.stdin", argv: ["cn:process-config:stdin", "@process-config/example"]),
+    .init(commandID: "cn:process-config:stdout", methodID: "processConfig.stdout", argv: ["cn:process-config:stdout", "@process-config/example"]),
+    .init(commandID: "cn:process-config:stderr", methodID: "processConfig.stderr", argv: ["cn:process-config:stderr", "@process-config/example"]),
+    .init(commandID: "cn:container-config:create-default", methodID: "containerConfig.createDefault", argv: ["cn:container-config:create-default", "example"]),
+    .init(commandID: "cn:container-config:create", methodID: "containerConfig.create", argv: ["cn:container-config:create", "example", "--process", "@process-config/example"]),
+    .init(commandID: "cn:container:default-mounts", methodID: "container.defaultMounts", argv: ["cn:container:default-mounts"]),
+    .init(commandID: "cn:container:default-oci-mounts", methodID: "container.defaultOCIMounts", argv: ["cn:container:default-oci-mounts"]),
+    .init(commandID: "cn:container:default-masked-paths", methodID: "container.defaultMaskedPaths", argv: ["cn:container:default-masked-paths"]),
+    .init(commandID: "cn:container:default-readonly-paths", methodID: "container.defaultReadonlyPaths", argv: ["cn:container:default-readonly-paths"]),
+    .init(commandID: "cn:container:default-copy-chunk-size", methodID: "container.defaultCopyChunkSize", argv: ["cn:container:default-copy-chunk-size"]),
+    .init(commandID: "cn:container:max-id-length", methodID: "container.maxIDLength", argv: ["cn:container:max-id-length"]),
+    .init(commandID: "cn:manager:create", methodID: "manager.create", argv: ["cn:manager:create", "example", "--kernel", "@kernel/example", "--initfs", "@mount/example", "--image-store", "@image-store/example"]),
+    .init(commandID: "cn:manager:create-at-root", methodID: "manager.createAtRoot", argv: ["cn:manager:create-at-root", "example", "--kernel", "@kernel/example", "--initfs", "@mount/example"]),
+    .init(commandID: "cn:manager:create-from-reference", methodID: "manager.createFromReference", argv: ["cn:manager:create-from-reference", "example", "--kernel", "@kernel/example", "--initfs-reference", "example", "--image-store", "@image-store/example"]),
+    .init(commandID: "cn:manager:create-from-reference-at-root", methodID: "manager.createFromReferenceAtRoot", argv: ["cn:manager:create-from-reference-at-root", "example", "--kernel", "@kernel/example", "--initfs-reference", "example"]),
+    .init(commandID: "cn:manager:create-with-vmm", methodID: "manager.createWithVMM", argv: ["cn:manager:create-with-vmm", "example", "--vmm", "@vmm/example"]),
+    .init(commandID: "cn:manager:image-store", methodID: "manager.imageStore", argv: ["cn:manager:image-store", "@manager/example"]),
+    .init(commandID: "cn:manager:create-container", methodID: "manager.createContainer", argv: ["cn:manager:create-container", "@manager/example", "example", "--reference", "example"]),
+    .init(commandID: "cn:manager:create-container-from-image", methodID: "manager.createContainerFromImage", argv: ["cn:manager:create-container-from-image", "@manager/example", "example", "--image", "@image/example"]),
+    .init(commandID: "cn:manager:create-container-from-mounts", methodID: "manager.createContainerFromMounts", argv: ["cn:manager:create-container-from-mounts", "@manager/example", "example", "--image", "@image/example", "--rootfs", "@mount/example"]),
+    .init(commandID: "cn:manager:release-network", methodID: "manager.releaseNetwork", argv: ["cn:manager:release-network", "@manager/example", "@container/example"]),
+    .init(commandID: "cn:manager:delete", methodID: "manager.delete", argv: ["cn:manager:delete", "@manager/example", "@container/example"]),
+    .init(commandID: "cn:container:create-direct", methodID: "container.createDirect", argv: ["cn:container:create-direct", "example", "--rootfs", "@mount/example", "--vmm", "@vmm/example", "--configuration", "@container-config/example"]),
+    .init(commandID: "cn:container:id", methodID: "container.id", argv: ["cn:container:id", "@container/example"]),
+    .init(commandID: "cn:container:rootfs", methodID: "container.rootfs", argv: ["cn:container:rootfs", "@container/example"]),
+    .init(commandID: "cn:container:writable-layer", methodID: "container.writableLayer", argv: ["cn:container:writable-layer", "@container/example"]),
+    .init(commandID: "cn:container:config", methodID: "container.config", argv: ["cn:container:config", "@container/example"]),
+    .init(commandID: "cn:container:cpus", methodID: "container.cpus", argv: ["cn:container:cpus", "@container/example"]),
+    .init(commandID: "cn:container:memory", methodID: "container.memory", argv: ["cn:container:memory", "@container/example"]),
+    .init(commandID: "cn:container:interfaces", methodID: "container.interfaces", argv: ["cn:container:interfaces", "@container/example"]),
+    .init(commandID: "cn:container:create", methodID: "container.create", argv: ["cn:container:create", "@container/example"]),
+    .init(commandID: "cn:container:start", methodID: "container.start", argv: ["cn:container:start", "@container/example"]),
+    .init(commandID: "cn:container:stop", methodID: "container.stop", argv: ["cn:container:stop", "@container/example"]),
+    .init(commandID: "cn:container:kill", methodID: "container.kill", argv: ["cn:container:kill", "@container/example", "SIGTERM"]),
+    .init(commandID: "cn:container:wait", methodID: "container.wait", argv: ["cn:container:wait", "@container/example"]),
+    .init(commandID: "cn:container:resize", methodID: "container.resize", argv: ["cn:container:resize", "@container/example", "1", "1"]),
+    .init(commandID: "cn:container:exec", methodID: "container.exec", argv: ["cn:container:exec", "@container/example", "example", "--configuration", "@process-config/example"]),
+    .init(commandID: "cn:container:dial-vsock", methodID: "container.dialVsock", argv: ["cn:container:dial-vsock", "@container/example", "1"]),
+    .init(commandID: "cn:container:close-stdin", methodID: "container.closeStdin", argv: ["cn:container:close-stdin", "@container/example"]),
+    .init(commandID: "cn:container:statistics", methodID: "container.statistics", argv: ["cn:container:statistics", "@container/example"]),
+    .init(commandID: "cn:container:filesystem-operation", methodID: "container.filesystemOperation", argv: ["cn:container:filesystem-operation", "@container/example", "freeze", "/example"]),
+    .init(commandID: "cn:container:copy-in", methodID: "container.copyIn", argv: ["cn:container:copy-in", "@container/example", "/tmp/example", "/example"]),
+    .init(commandID: "cn:container:copy-out", methodID: "container.copyOut", argv: ["cn:container:copy-out", "@container/example", "/example", "/tmp/example"]),
+    .init(commandID: "cn:process:id", methodID: "process.id", argv: ["cn:process:id", "@process/example"]),
+    .init(commandID: "cn:process:owning-container", methodID: "process.owningContainer", argv: ["cn:process:owning-container", "@process/example"]),
+    .init(commandID: "cn:process:pid", methodID: "process.pid", argv: ["cn:process:pid", "@process/example"]),
+    .init(commandID: "cn:process:start", methodID: "process.start", argv: ["cn:process:start", "@process/example"]),
+    .init(commandID: "cn:process:kill", methodID: "process.kill", argv: ["cn:process:kill", "@process/example", "SIGTERM"]),
+    .init(commandID: "cn:process:resize", methodID: "process.resize", argv: ["cn:process:resize", "@process/example", "1", "1"]),
+    .init(commandID: "cn:process:close-stdin", methodID: "process.closeStdin", argv: ["cn:process:close-stdin", "@process/example"]),
+    .init(commandID: "cn:process:wait", methodID: "process.wait", argv: ["cn:process:wait", "@process/example"]),
+    .init(commandID: "cn:process:delete", methodID: "process.delete", argv: ["cn:process:delete", "@process/example"]),
+    .init(commandID: "cn:pod-volume:create", methodID: "podVolume.create", argv: ["cn:pod-volume:create", "example", "--name", "example", "--source", "{}", "--format", "example"]),
+    .init(commandID: "cn:pod-config:create", methodID: "podConfig.create", argv: ["cn:pod-config:create", "example"]),
+    .init(commandID: "cn:pod-config:set-cpus", methodID: "podConfig.setCPUs", argv: ["cn:pod-config:set-cpus", "@pod-config/example", "1"]),
+    .init(commandID: "cn:pod-config:set-memory", methodID: "podConfig.setMemory", argv: ["cn:pod-config:set-memory", "@pod-config/example", "1"]),
+    .init(commandID: "cn:pod-config:set-interfaces", methodID: "podConfig.setInterfaces", argv: ["cn:pod-config:set-interfaces", "@pod-config/example", "@interface/example"]),
+    .init(commandID: "cn:pod-config:set-virtualization", methodID: "podConfig.setVirtualization", argv: ["cn:pod-config:set-virtualization", "@pod-config/example", "true"]),
+    .init(commandID: "cn:pod-config:set-boot-log", methodID: "podConfig.setBootLog", argv: ["cn:pod-config:set-boot-log", "@pod-config/example", "@boot-log/example"]),
+    .init(commandID: "cn:pod-config:set-share-process-namespace", methodID: "podConfig.setShareProcessNamespace", argv: ["cn:pod-config:set-share-process-namespace", "@pod-config/example", "true"]),
+    .init(commandID: "cn:pod-config:set-hostname", methodID: "podConfig.setHostname", argv: ["cn:pod-config:set-hostname", "@pod-config/example", "example"]),
+    .init(commandID: "cn:pod-config:set-dns", methodID: "podConfig.setDNS", argv: ["cn:pod-config:set-dns", "@pod-config/example", "@dns/example"]),
+    .init(commandID: "cn:pod-config:set-hosts", methodID: "podConfig.setHosts", argv: ["cn:pod-config:set-hosts", "@pod-config/example", "@hosts/example"]),
+    .init(commandID: "cn:pod-config:set-volumes", methodID: "podConfig.setVolumes", argv: ["cn:pod-config:set-volumes", "@pod-config/example", "@pod-volume/example"]),
+    .init(commandID: "cn:pod-container-config:create", methodID: "podContainerConfig.create", argv: ["cn:pod-container-config:create", "example"]),
+    .init(commandID: "cn:pod-container-config:set-process", methodID: "podContainerConfig.setProcess", argv: ["cn:pod-container-config:set-process", "@pod-container-config/example", "@process-config/example"]),
+    .init(commandID: "cn:pod-container-config:set-cpus", methodID: "podContainerConfig.setCPUs", argv: ["cn:pod-container-config:set-cpus", "@pod-container-config/example", "1"]),
+    .init(commandID: "cn:pod-container-config:set-memory", methodID: "podContainerConfig.setMemory", argv: ["cn:pod-container-config:set-memory", "@pod-container-config/example", "1"]),
+    .init(commandID: "cn:pod-container-config:set-hostname", methodID: "podContainerConfig.setHostname", argv: ["cn:pod-container-config:set-hostname", "@pod-container-config/example", "example"]),
+    .init(commandID: "cn:pod-container-config:set-sysctl", methodID: "podContainerConfig.setSysctl", argv: ["cn:pod-container-config:set-sysctl", "@pod-container-config/example", "key=value"]),
+    .init(commandID: "cn:pod-container-config:set-mounts", methodID: "podContainerConfig.setMounts", argv: ["cn:pod-container-config:set-mounts", "@pod-container-config/example", "@mount/example"]),
+    .init(commandID: "cn:pod-container-config:set-masked-paths", methodID: "podContainerConfig.setMaskedPaths", argv: ["cn:pod-container-config:set-masked-paths", "@pod-container-config/example", "/example"]),
+    .init(commandID: "cn:pod-container-config:set-readonly-paths", methodID: "podContainerConfig.setReadonlyPaths", argv: ["cn:pod-container-config:set-readonly-paths", "@pod-container-config/example", "/example"]),
+    .init(commandID: "cn:pod-container-config:set-sockets", methodID: "podContainerConfig.setSockets", argv: ["cn:pod-container-config:set-sockets", "@pod-container-config/example", "@socket/example"]),
+    .init(commandID: "cn:pod-container-config:set-dns", methodID: "podContainerConfig.setDNS", argv: ["cn:pod-container-config:set-dns", "@pod-container-config/example", "@dns/example"]),
+    .init(commandID: "cn:pod-container-config:set-hosts", methodID: "podContainerConfig.setHosts", argv: ["cn:pod-container-config:set-hosts", "@pod-container-config/example", "@hosts/example"]),
+    .init(commandID: "cn:pod-container-config:set-use-init", methodID: "podContainerConfig.setUseInit", argv: ["cn:pod-container-config:set-use-init", "@pod-container-config/example", "true"]),
+    .init(commandID: "cn:pod:create-direct", methodID: "pod.createDirect", argv: ["cn:pod:create-direct", "example", "--vmm", "@vmm/example", "--configuration", "@pod-config/example"]),
+    .init(commandID: "cn:pod:id", methodID: "pod.id", argv: ["cn:pod:id", "@pod/example"]),
+    .init(commandID: "cn:pod:config", methodID: "pod.config", argv: ["cn:pod:config", "@pod/example"]),
+    .init(commandID: "cn:pod:cpus", methodID: "pod.cpus", argv: ["cn:pod:cpus", "@pod/example"]),
+    .init(commandID: "cn:pod:memory", methodID: "pod.memory", argv: ["cn:pod:memory", "@pod/example"]),
+    .init(commandID: "cn:pod:interfaces", methodID: "pod.interfaces", argv: ["cn:pod:interfaces", "@pod/example"]),
+    .init(commandID: "cn:pod:add-container", methodID: "pod.addContainer", argv: ["cn:pod:add-container", "@pod/example", "example", "--rootfs", "@mount/example", "--configuration", "@pod-container-config/example"]),
+    .init(commandID: "cn:pod:create", methodID: "pod.create", argv: ["cn:pod:create", "@pod/example"]),
+    .init(commandID: "cn:pod:start-container", methodID: "pod.startContainer", argv: ["cn:pod:start-container", "@pod/example", "@pod-container/example"]),
+    .init(commandID: "cn:pod:stop-container", methodID: "pod.stopContainer", argv: ["cn:pod:stop-container", "@pod/example", "@pod-container/example"]),
+    .init(commandID: "cn:pod:stop", methodID: "pod.stop", argv: ["cn:pod:stop", "@pod/example"]),
+    .init(commandID: "cn:pod:kill-container", methodID: "pod.killContainer", argv: ["cn:pod:kill-container", "@pod/example", "@pod-container/example", "SIGTERM"]),
+    .init(commandID: "cn:pod:wait-container", methodID: "pod.waitContainer", argv: ["cn:pod:wait-container", "@pod/example", "@pod-container/example"]),
+    .init(commandID: "cn:pod:resize-container", methodID: "pod.resizeContainer", argv: ["cn:pod:resize-container", "@pod/example", "@pod-container/example", "1", "1"]),
+    .init(commandID: "cn:pod:exec-in-container", methodID: "pod.execInContainer", argv: ["cn:pod:exec-in-container", "@pod/example", "@pod-container/example", "example", "--configuration", "@process-config/example"]),
+    .init(commandID: "cn:pod:list-containers", methodID: "pod.listContainers", argv: ["cn:pod:list-containers", "@pod/example"]),
+    .init(commandID: "cn:pod:statistics", methodID: "pod.statistics", argv: ["cn:pod:statistics", "@pod/example"]),
+    .init(commandID: "cn:pod:dial-vsock", methodID: "pod.dialVsock", argv: ["cn:pod:dial-vsock", "@pod/example", "1"]),
+    .init(commandID: "cn:pod:filesystem-operation", methodID: "pod.filesystemOperation", argv: ["cn:pod:filesystem-operation", "@pod/example", "@pod-container/example", "freeze", "/example"]),
+    .init(commandID: "cn:pod:close-container-stdin", methodID: "pod.closeContainerStdin", argv: ["cn:pod:close-container-stdin", "@pod/example", "@pod-container/example"]),
+    .init(commandID: "cn:pod:relay-unix-socket", methodID: "pod.relayUnixSocket", argv: ["cn:pod:relay-unix-socket", "@pod/example", "@pod-container/example", "@socket/example"]),
+    .init(commandID: "cn:content-store:create", methodID: "contentStore.create", argv: ["cn:content-store:create", "example", "--path", "/tmp/example"]),
+    .init(commandID: "cn:authentication:create-basic", methodID: "authentication.createBasic", argv: ["cn:authentication:create-basic", "example", "--username", "example", "--password", "example"]),
+    .init(commandID: "cn:progress-handler:create", methodID: "progressHandler.create", argv: ["cn:progress-handler:create", "example", "--writer", "@writer/example"]),
+    .init(commandID: "cr:volume:create", methodID: "volume.create", argv: ["cr:volume:create", "example"]),
+    .init(commandID: "cr:volume:list", methodID: "volume.list", argv: ["cr:volume:list"]),
+    .init(commandID: "cr:volume:inspect", methodID: "volume.inspect", argv: ["cr:volume:inspect", "@volume/example"]),
+    .init(commandID: "cr:volume:mount", methodID: "volume.mount", argv: ["cr:volume:mount", "@volume/example", "example", "--destination", "/example"]),
+    .init(commandID: "cr:volume:delete", methodID: "volume.delete", argv: ["cr:volume:delete", "@volume/example"]),
+    .init(commandID: "cr:memory-size:create", methodID: "crMemorySize.create", argv: ["cr:memory-size:create", "example", "example"]),
+    .init(commandID: "cr:memory-size:formatted", methodID: "crMemorySize.formatted", argv: ["cr:memory-size:formatted", "@memory-size/example"]),
+    .init(commandID: "cr:memory-size:to-uint64", methodID: "crMemorySize.toUInt64", argv: ["cr:memory-size:to-uint64", "@memory-size/example", "bytes"]),
+    .init(commandID: "cr:resource-labels:create", methodID: "crResourceLabels.create", argv: ["cr:resource-labels:create", "example"]),
+    .init(commandID: "cr:resource-labels:validate-key", methodID: "crResourceLabels.validateKey", argv: ["cr:resource-labels:validate-key", "example"]),
+    .init(commandID: "cr:resource-labels:validate", methodID: "crResourceLabels.validate", argv: ["cr:resource-labels:validate", "example", "example"]),
+    .init(commandID: "cr:resource-labels:dictionary", methodID: "crResourceLabels.dictionary", argv: ["cr:resource-labels:dictionary", "@resource-labels/example"]),
+    .init(commandID: "cr:resource-labels:value", methodID: "crResourceLabels.value", argv: ["cr:resource-labels:value", "@resource-labels/example", "example"]),
+    .init(commandID: "cr:resource-labels:key-length-max", methodID: "crResourceLabels.keyLengthMax", argv: ["cr:resource-labels:key-length-max"]),
+    .init(commandID: "cr:resource-labels:label-length-max", methodID: "crResourceLabels.labelLengthMax", argv: ["cr:resource-labels:label-length-max"]),
+    .init(commandID: "cr:parser:memory-as-mib", methodID: "crParser.memoryAsMiB", argv: ["cr:parser:memory-as-mib", "example"]),
+    .init(commandID: "cr:parser:memory-as-bytes", methodID: "crParser.memoryAsBytes", argv: ["cr:parser:memory-as-bytes", "example"]),
+    .init(commandID: "cr:parser:labels", methodID: "crParser.labels", argv: ["cr:parser:labels", "example"]),
+    .init(commandID: "cr:parser:platform", methodID: "crParser.platform", argv: ["cr:parser:platform", "example"]),
+    .init(commandID: "cr:parser:is-valid-domain-name", methodID: "crParser.isValidDomainName", argv: ["cr:parser:is-valid-domain-name", "example"]),
+    .init(commandID: "cr:parser:is-valid-domain-name-label", methodID: "crParser.isValidDomainNameLabel", argv: ["cr:parser:is-valid-domain-name-label", "example"]),
+    .init(commandID: "cr:parser:parse-bool", methodID: "crParser.parseBool", argv: ["cr:parser:parse-bool", "example"]),
+]
diff --git a/macOS/GhostTools/Sources/ghostbox/GhostboxCLI.swift b/macOS/GhostTools/Sources/ghostbox/GhostboxCLI.swift
new file mode 100644
index 0000000..fd04537
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/GhostboxCLI.swift
@@ -0,0 +1,323 @@
+import Foundation
+
+let ghostboxVersion = "0.1.0"
+
+@main
+struct GhostboxCLI {
+    static func main() async {
+        signal(SIGPIPE, SIG_IGN)
+
+        let status: Int32
+        switch parseArguments(Array(CommandLine.arguments.dropFirst())) {
+        case .success(let options):
+            status = await run(options)
+        case .failure(let error):
+            writeStderr((error.errorDescription ?? "error") + "\n")
+            status = 125
+        }
+        exit(status)
+    }
+
+    static func run(_ options: CLIOptions) async -> Int32 {
+        switch options.action {
+        case .help(let topic):
+            switch renderGhostboxHelp(topic) {
+            case .success(let help):
+                writeStdout(Data((help + "\n").utf8))
+                return 0
+            case .failure(let error):
+                writeStderr((error.errorDescription ?? "invalid help topic") + "\n")
+                return 125
+            }
+        case .version:
+            writeStdout(Data("\(ghostboxVersion)\n".utf8))
+            return 0
+        case .direct(let invocation):
+            return runDirect(invocation: invocation, port: kDefaultVsockPort)
+        case .attach(let invocation, let stream):
+            return runAttachment(invocation: invocation, expectedStream: stream, port: kDefaultVsockPort)
+        case .forward(let container, let ports):
+            return await runPortForwarding(container: container, ports: ports, port: kDefaultVsockPort)
+        }
+    }
+}
+
+func runDirect(invocation: GhostboxDirectInvocation, port: UInt32) -> Int32 {
+    do {
+        let value = try invokeDirect(invocation: invocation, port: port)
+        guard writeStdout(try renderDirectValue(value)) else {
+            writeStderr("ghostbox: failed to write direct result (errno \(errno))\n")
+            return 125
+        }
+        return 0
+    } catch let error as DirectInvocationError {
+        writeStderr("ghostbox: \(error.errorDescription ?? "direct invocation failed")\n")
+        return 125
+    } catch {
+        writeStderr("ghostbox: direct invocation failed: \(error)\n")
+        return 125
+    }
+}
+
+enum DirectInvocationError: Error, LocalizedError {
+    case encode(Error)
+    case connect(Error)
+    case send(Int32)
+    case response(String)
+    case host(code: String, message: String)
+
+    var errorDescription: String? {
+        switch self {
+        case .encode(let error): return "failed to encode direct request: \(error)"
+        case .connect(let error): return "cannot connect to host: \(error)"
+        case .send(let code): return "failed to send direct request (errno \(code))"
+        case .response(let message): return "protocol error: \(message)"
+        case .host(let code, let message): return "host error [\(code)]: \(message)"
+        }
+    }
+}
+
+func invokeDirect(invocation: GhostboxDirectInvocation, port: UInt32) throws -> GhostboxDirectValue {
+    let request = GhostboxDirectRequest(invocation: invocation)
+    let line: Data
+    do {
+        line = try encodeDirectRequestLine(request)
+    } catch {
+        throw DirectInvocationError.encode(error)
+    }
+
+    let fd: Int32
+    do {
+        fd = try vsockDialHost(port: port)
+    } catch {
+        throw DirectInvocationError.connect(error)
+    }
+    defer { Darwin.close(fd) }
+
+    guard writeAll(fd: fd, line) else {
+        throw DirectInvocationError.send(errno)
+    }
+    _ = Darwin.shutdown(fd, SHUT_WR)
+
+    let responseData: Data
+    do {
+        let reader = LineReader(fd: fd, maxLineBytes: kMaxDirectResponseLineBytes)
+        guard let response = try reader.readLine(), !response.isEmpty else {
+            throw DirectInvocationError.response("connection closed before direct response")
+        }
+        responseData = response
+    } catch {
+        if let error = error as? DirectInvocationError { throw error }
+        throw DirectInvocationError.response("failed to read direct response: \(error)")
+    }
+
+    switch decodeDirectResponse(responseData, requestID: request.id) {
+    case .result(let value):
+        return value
+    case .error(let code, let message):
+        throw DirectInvocationError.host(code: code, message: message)
+    case .protocolError(let message):
+        throw DirectInvocationError.response(message)
+    }
+}
+
+func runPortForwarding(container: String, ports: [PublishedPort], port: UInt32) async -> Int32 {
+    #if DEBUG
+    let signalTestControl = ProcessInfo.processInfo.environment["GHOSTBOX_FORWARD_SIGNAL_TEST_CONTROL"] == "1"
+    #endif
+
+    let addressResult: Result
+    #if DEBUG
+    if signalTestControl {
+        addressResult = .success("127.0.0.1")
+    } else {
+        addressResult = Result { try resolveContainerIPv4Address(container: container, port: port) }
+    }
+    #else
+    addressResult = Result { try resolveContainerIPv4Address(container: container, port: port) }
+    #endif
+
+    let address: String
+    switch addressResult {
+    case .success(let resolvedAddress):
+        address = resolvedAddress
+    case .failure(let error as DirectInvocationError):
+        writeStderr("ghostbox: cannot resolve container address: \(error.errorDescription ?? "unknown error")\n")
+        return 125
+    case .failure(let error):
+        writeStderr("ghostbox: cannot resolve container address: \(error.localizedDescription)\n")
+        return 125
+    }
+
+    var forwarders: [PublishedPortForwarder] = []
+    do {
+        for publication in ports {
+            forwarders.append(try await PublishedPortForwarder(publication))
+        }
+    } catch {
+        for forwarder in forwarders { await forwarder.stop() }
+        writeStderr("ghostbox: cannot publish port: \(error.localizedDescription)\n")
+        return 125
+    }
+
+    let runState = ForwardingRunState()
+    let signalQueue = DispatchQueue(label: "org.ghostvm.ghostbox.forward-signals")
+    let handledSignals = [SIGINT, SIGTERM, SIGHUP]
+    let signals = handledSignals.map { signalNumber in
+        let source = DispatchSource.makeSignalSource(signal: signalNumber, queue: signalQueue)
+        source.setEventHandler { runState.finish(status: 128 + signalNumber) }
+        return source
+    }
+    for (signalNumber, source) in zip(handledSignals, signals) {
+        signal(signalNumber, SIG_IGN)
+        source.resume()
+    }
+    forwarders.forEach { forwarder in
+        forwarder.start(targetAddress: address) { error in
+            runState.finish(status: 125) {
+                writeStderr("ghostbox: port forwarding stopped: \(error.localizedDescription)\n")
+            }
+        }
+    }
+    #if DEBUG
+    if signalTestControl { writeStdout(Data("READY\n".utf8)) }
+    #endif
+    let status = await runState.wait()
+    #if DEBUG
+    if signalTestControl {
+        writeStdout(Data("CLEANUP\n".utf8))
+        _ = FileHandle.standardInput.readData(ofLength: 1)
+    }
+    #endif
+    for forwarder in forwarders { await forwarder.stop() }
+    #if DEBUG
+    if signalTestControl {
+        writeStdout(Data("STOPPED\n".utf8))
+        _ = FileHandle.standardInput.readData(ofLength: 1)
+    }
+    #endif
+    signals.forEach { $0.cancel() }
+    // Keep these signals ignored until main exits; restoring SIG_DFL here would
+    // let a repeated signal replace the selected exit status after cleanup.
+    return status
+}
+
+private func resolveContainerIPv4Address(container: String, port: UInt32) throws -> String {
+    let interfaces = try invokeDirect(
+        invocation: .init(
+            method: .init(rawValue: "container.interfaces"),
+            parameters: ["container": .string(container)]
+        ),
+        port: port
+    )
+    guard case .references(let references) = interfaces.storage, !references.isEmpty else {
+        throw DirectInvocationError.response("container has no network interface")
+    }
+    for interface in references {
+        let addressValue = try invokeDirect(
+            invocation: .init(
+                method: .init(rawValue: "interface.ipv4Address"),
+                parameters: ["interface": .string(interface)]
+            ),
+            port: port
+        )
+        if case .json(.string(let cidr)) = addressValue.storage, !cidr.isEmpty {
+            return cidr.split(separator: "/", maxSplits: 1).first.map(String.init) ?? cidr
+        }
+    }
+    throw DirectInvocationError.response("container interfaces have no IPv4 address")
+}
+
+private final class ForwardingRunState: @unchecked Sendable {
+    private let lock = NSLock()
+    private var status: Int32?
+    private var continuation: CheckedContinuation?
+
+    @discardableResult
+    func finish(status: Int32, onFinish: () -> Void = {}) -> Bool {
+        let (finished, continuation): (Bool, CheckedContinuation?) = lock.withLock {
+            guard self.status == nil else { return (false, nil) }
+            self.status = status
+            defer { self.continuation = nil }
+            return (true, self.continuation)
+        }
+        guard finished else { return false }
+        continuation?.resume(returning: status)
+        onFinish()
+        return true
+    }
+
+    func wait() async -> Int32 {
+        await withCheckedContinuation { continuation in
+            let status = lock.withLock { () -> Int32? in
+                if let status = self.status { return status }
+                self.continuation = continuation
+                return nil
+            }
+            if let status { continuation.resume(returning: status) }
+        }
+    }
+}
+
+func renderDirectValue(_ value: GhostboxDirectValue) throws -> Data {
+    switch value.storage {
+    case .json(let json):
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+        var data = try encoder.encode(RenderedJSON(json))
+        data.append(0x0A)
+        return data
+    case .references(let values):
+        guard !values.isEmpty else { return Data() }
+        return Data((values.joined(separator: "\n") + "\n").utf8)
+    case .bytes(let value):
+        return value
+    case .void:
+        return Data()
+    case .reference(let value):
+        return Data((value + "\n").utf8)
+    }
+}
+
+private struct RenderedJSON: Encodable {
+    let value: GhostboxJSONValue
+
+    init(_ value: GhostboxJSONValue) {
+        self.value = value
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        switch value {
+        case .null:
+            try container.encodeNil()
+        case .boolean(let value):
+            try container.encode(value)
+        case .string(let value):
+            try container.encode(value)
+        case .integer(let value):
+            try container.encode(value)
+        case .unsignedInteger(let value):
+            try container.encode(value)
+        case .array(let values):
+            try container.encode(values.map(RenderedJSON.init))
+        case .object(let values):
+            try container.encode(values.mapValues(RenderedJSON.init))
+        }
+    }
+}
+
+@discardableResult
+func writeStdout(_ data: Data) -> Bool {
+    writeAll(fd: STDOUT_FILENO, data)
+}
+
+@discardableResult
+func writeStderr(_ data: Data) -> Bool {
+    writeAll(fd: STDERR_FILENO, data)
+}
+
+@discardableResult
+func writeStderr(_ string: String) -> Bool {
+    writeStderr(Data(string.utf8))
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/Help.swift b/macOS/GhostTools/Sources/ghostbox/Help.swift
new file mode 100644
index 0000000..284e585
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/Help.swift
@@ -0,0 +1,545 @@
+import Foundation
+
+let ghostboxHelp = renderRootGhostboxHelp()
+
+func renderGhostboxHelp(_ topic: [String]) -> Result {
+    guard !topic.isEmpty else { return .success(ghostboxHelp) }
+
+    if topic.count == 1, let namespace = canonicalHelpNamespace(topic[0]) {
+        return .success(renderNamespaceHelp(namespace))
+    }
+    if topic.count == 2, let namespace = canonicalHelpNamespace(topic[0]) {
+        return renderResourceHelp(namespace: namespace, resource: topic[1])
+    }
+    guard topic.count == 1, let qualified = GhostboxQualifiedCommand(topic[0]) else {
+        return .failure(.invalidDirect(
+            "help expects cn:help, cr:help, NAMESPACE:RESOURCE:help, or NAMESPACE:RESOURCE:OPERATION"
+        ))
+    }
+    if qualified.operation == "help" {
+        return renderResourceHelp(namespace: qualified.namespace, resource: qualified.resource)
+    }
+    if let command = ghostboxCommandCatalog.first(where: {
+        $0.commandID == qualified.canonical || $0.aliases.contains(topic[0])
+    }) {
+        return .success(renderCommandHelp(command))
+    }
+    if qualified.namespace == "cn", let help = renderContainerizationExtensionHelp(qualified) {
+        return .success(help)
+    }
+    return .failure(.invalidDirect(
+        "unknown help command '\(topic[0])'; run 'ghostbox \(qualified.namespace):\(qualified.resource):help'"
+    ))
+}
+
+private func canonicalHelpNamespace(_ value: String) -> String? {
+    switch value {
+    case "cn", "containerization": "cn"
+    case "cr", "container": "cr"
+    default: nil
+    }
+}
+
+private func renderNamespaceHelp(_ namespace: String) -> String {
+    let commands = ghostboxCommandCatalog.filter { $0.namespace == namespace }
+    var lines = [
+        namespace == "cn" ? "Containerization namespace (cn):" : "Container namespace (cr):",
+        "",
+        "Use 'ghostbox \(namespace):RESOURCE:help' for resource help.",
+    ]
+    for resource in Set(commands.map(\.resource)).sorted() {
+        lines.append("")
+        lines.append("\(resource):")
+        for command in commands where command.resource == resource {
+            lines.append(contentsOf: renderSignatureReference(command, indent: "  "))
+        }
+    }
+    if namespace == "cn" {
+        lines.append("\nGhostVM Containerization extensions: kernel, cleanup, guest-share, forwarding, and I/O proxy commands.")
+    }
+    return lines.joined(separator: "\n")
+}
+
+private func renderResourceHelp(namespace: String, resource: String) -> Result {
+    let commands = ghostboxCommandCatalog.filter { $0.namespace == namespace && $0.resource == resource }
+    if commands.isEmpty {
+        if namespace == "cn", let help = renderContainerizationExtensionResourceHelp(resource) {
+            return .success(help)
+        }
+        return .failure(.invalidDirect("unknown resource '\(resource)' in namespace '\(namespace)'"))
+    }
+    var help = renderResourceHelp(namespace, resource: resource, commands: commands)
+    guard namespace == "cn" else { return .success(help) }
+    if resource == "kernel" {
+        help += "\n\nHost extensions:\n  ghostbox cn:kernel:install-recommended -> @kernel/default\n  ghostbox cn:kernel:default -> @kernel/default"
+    }
+    if let extensionSignature = ghostboxCleanupExtensionSignatures[resource] {
+        help += "\n\nGhostVM cleanup extension:\n  \(extensionSignature)"
+    }
+    if resource == "mount" {
+        help += "\n\nGhostVM guest-share extension:\n  ghostbox cn:mount:guest-share NAME --source GUEST_PATH --destination CONTAINER_PATH [--read-only=true|false] [--cache-ttl SECONDS]"
+    } else if resource == "container" {
+        help += "\n\nGhostVM port-forward extension:\n  ghostbox cn:container:forward @container/NAME -p [GUEST_IP:]GUEST_PORT:CONTAINER_PORT[/tcp]"
+    }
+    return .success(help)
+}
+
+private func renderContainerizationExtensionHelp(_ command: GhostboxQualifiedCommand) -> String? {
+    if command.resource == "kernel", command.operation == "default" {
+        return "Usage:\n  ghostbox cn:kernel:default -> @kernel/default\n\nMethod: kernel.default\nHost API: KernelService.getDefaultKernel(platform: .linuxArm)"
+    }
+    if command.resource == "kernel", command.operation == "install-recommended" {
+        return "Usage:\n  ghostbox cn:kernel:install-recommended -> @kernel/default\n\nMethod: kernel.installRecommended\nHost APIs: ConfigurationLoader.load(configurationFiles:), KernelService.installKernelFrom(...)"
+    }
+    let legacy = [command.resource, command.operation]
+    return renderCleanupExtensionHelp(legacy)
+        ?? renderContainerBridgeExtensionHelp(legacy)
+        ?? renderIOProxyHelp(legacy)
+}
+
+private func renderContainerizationExtensionResourceHelp(_ resource: String) -> String? {
+    renderIOProxyHelp([resource])
+}
+
+private func renderRootGhostboxHelp() -> String {
+    var lines = [
+        "Usage:",
+        "  ghostbox NAMESPACE:RESOURCE:OPERATION [@RESOURCE/NAME] [ARGUMENTS] [OPTIONS]",
+        "  ghostbox NAMESPACE:RESOURCE:help",
+        "  ghostbox NAMESPACE:RESOURCE:OPERATION --help",
+        "  ghostbox cn:help | cr:help",
+        "",
+        "Source-qualified diagnostic interface to Apple Containerization and container APIs.",
+        "Namespaces: cn (containerization) and cr (container).",
+        "Use resource or operation help for argument, type, default, output, and example details.",
+        "",
+        "Signature conventions:",
+        "         New literal value.",
+        "  @      Existing VMHost-owned object reference.",
+        "  [argument]            Optional argument.",
+        "  argument...           Repeatable argument.",
+        "  -> @   Canonical object reference printed on success.",
+        "  [--argument=default]  Optional argument using the shown framework default.",
+        "",
+        "Output conventions:",
+        "  Object creation and framework-object results print canonical @ references.",
+        "  Property and value results print JSON-compatible values.",
+        "  Byte results are written directly to stdout.",
+        "",
+        "Options:",
+        "  --help, -h   Show root, resource, or operation help.",
+        "  --version    Show version.",
+        "",
+        "VM host extensions:",
+        "  ghostbox cn:kernel:install-recommended -> @kernel/default",
+        "  ghostbox cn:kernel:default -> @kernel/default",
+        "  ghostbox cn:dns:delete @dns/NAME",
+        "  ghostbox cn:mount:guest-share NAME --source GUEST_PATH --destination CONTAINER_PATH",
+        "  ghostbox cr:volume:create NAME [--size BYTES] -> @volume/NAME",
+        "  ghostbox cr:volume:mount @volume/NAME MOUNT --destination PATH -> @mount/MOUNT",
+        "",
+        "VM guest extensions:",
+        "  ghostbox cn:container:forward @container/NAME -p [GUEST_IP:]GUEST_PORT:CONTAINER_PORT[/tcp]",
+        "",
+        "VM I/O proxy extensions:",
+        "  ghostbox cn:reader-stream:create ",
+        "  ghostbox cn:reader-stream:attach|close @reader-stream/NAME",
+        "  ghostbox cn:writer:create ",
+        "  ghostbox cn:writer:attach|close @writer/NAME",
+        "  ghostbox cn:terminal:create  [--width=80] [--height=24]",
+        "  ghostbox cn:terminal:attach @terminal/NAME [--resize-target @container/NAME|@process/NAME]",
+        "  ghostbox cn:terminal:wait-attached|close @terminal/NAME",
+        "  Proxy attach commands forward raw fd 0 or fd 1; terminal attach requires a TTY.",
+        "",
+        "Cataloged signatures:",
+    ]
+
+    for namespace in ["cn", "cr"] {
+        lines.append("")
+        lines.append(namespace == "cn" ? "Containerization (cn):" : "Container (cr):")
+        for command in ghostboxCommandCatalog where command.namespace == namespace {
+            lines.append(contentsOf: renderSignatureReference(command, indent: "  "))
+        }
+    }
+    return lines.joined(separator: "\n")
+}
+
+private func renderVolumeHelp(_ topic: [String]) -> String? {
+    guard topic.first == "volume" else { return nil }
+    if topic.count == 1 {
+        return """
+        Usage:
+          ghostbox cr:volume:create NAME [--size BYTES] -> @volume/NAME
+          ghostbox cr:volume:list -> @volume/NAME...
+          ghostbox cr:volume:inspect @volume/NAME
+          ghostbox cr:volume:mount @volume/NAME MOUNT --destination PATH [--read-only=true|false] -> @mount/MOUNT
+          ghostbox cr:volume:delete @volume/NAME
+
+        Persistent ext4 volumes are stored with the VM and survive container and VM restarts.
+        Delete the returned mount reference before deleting its volume.
+        """
+    }
+    let operation = topic.last
+    switch operation {
+    case "create":
+        return "Usage:\n  ghostbox cr:volume:create NAME [--size BYTES] -> @volume/NAME\n\nCreates a persistent ext4 volume. The default size is 8 GiB."
+    case "list":
+        return "Usage:\n  ghostbox cr:volume:list -> @volume/NAME...\n\nLists persistent volumes in lexical order."
+    case "inspect":
+        return "Usage:\n  ghostbox cr:volume:inspect @volume/NAME\n\nPrints volume metadata without exposing the outer-host backing path."
+    case "mount":
+        return "Usage:\n  ghostbox cr:volume:mount @volume/NAME MOUNT --destination PATH [--read-only=true|false] -> @mount/MOUNT\n\nCreates an ext4 block-mount reference for a container configuration."
+    case "delete":
+        return "Usage:\n  ghostbox cr:volume:delete @volume/NAME\n\nDeletes an unused volume and its contents."
+    default:
+        return nil
+    }
+}
+
+private let ghostboxCleanupExtensionSignatures = [
+    "dns": "ghostbox cn:dns:delete @dns/NAME",
+    "process-config": "ghostbox cn:process-config:delete @process-config/NAME",
+    "network": "ghostbox cn:network:delete @network/NAME",
+    "manager": "ghostbox cn:manager:close @manager/NAME",
+    "mount": "ghostbox cn:mount:delete @mount/NAME",
+]
+
+private func renderCleanupExtensionHelp(_ topic: [String]) -> String? {
+    guard topic.count == 2 || (topic.count == 3 && topic[1].hasPrefix("@")) else { return nil }
+    let resource = topic[0]
+    let operation = topic.last!
+    let expectedOperation = resource == "manager" ? "close" : "delete"
+    guard let signature = ghostboxCleanupExtensionSignatures[resource],
+          operation == expectedOperation else { return nil }
+    let detail: String
+    switch resource {
+    case "network":
+        detail = "Removes the host reference after all interfaces allocated from it have been released."
+    case "manager":
+        detail = "Closes the manager reference after all of its managed containers have been deleted."
+    default:
+        detail = "Removes the host-owned configuration reference. Existing containers retain copied configuration."
+    }
+    return """
+    Usage:
+      \(signature)
+
+    Method: \(resource == "process-config" ? "processConfig" : resource).\(operation)
+    GhostVM host extension
+
+    \(detail)
+    """
+}
+
+private func renderContainerBridgeExtensionHelp(_ topic: [String]) -> String? {
+    if topic == ["mount", "guest-share"] {
+        return """
+        Usage:
+          ghostbox cn:mount:guest-share NAME --source GUEST_PATH --destination CONTAINER_PATH [--read-only=true|false] [--cache-ttl SECONDS] [--option VALUE]... [--runtime-option VALUE]...
+
+        Method: mount.guestShare
+        GhostVM host extension
+
+        Exports the guest path through the private GhostFile bridge, mounts it on the outer host through GhostVMFS, and returns a Containerization Mount.share reference.
+        """
+    }
+    if topic == ["container", "forward"]
+        || (topic.count == 3 && topic[0] == "container" && topic[1].hasPrefix("@") && topic[2] == "forward") {
+        return """
+        Usage:
+          ghostbox cn:container:forward @container/NAME -p|-P [GUEST_IP:]GUEST_PORT:CONTAINER_PORT[/tcp] [-p ...]
+
+        GhostVM guest extension
+
+        Listens in this guest and forwards TCP directly to the container's shared-vmnet IPv4 address until interrupted.
+        """
+    }
+    return nil
+}
+
+private func renderIOProxyHelp(_ topic: [String]) -> String? {
+    guard let resource = topic.first,
+          ["reader-stream", "writer", "terminal"].contains(resource) else { return nil }
+    if topic.count == 1 {
+        switch resource {
+        case "reader-stream":
+            return """
+            Usage:
+              ghostbox cn:reader-stream:create 
+              ghostbox cn:reader-stream:attach @reader-stream/NAME
+              ghostbox cn:reader-stream:close @reader-stream/NAME
+
+            Creates a VM-backed Apple ReaderStream. Attach copies raw stdin into it until EOF.
+            """
+        case "writer":
+            return """
+            Usage:
+              ghostbox cn:writer:create 
+              ghostbox cn:writer:attach @writer/NAME
+              ghostbox cn:writer:close @writer/NAME
+
+            Creates a VM-backed Apple Writer. Attach copies its raw bytes to stdout until closed.
+            """
+        default:
+            return """
+            Usage:
+              ghostbox cn:terminal:create  [--width=80] [--height=24]
+              ghostbox cn:terminal:attach @terminal/NAME [--resize-target @container/NAME|@process/NAME]
+              ghostbox cn:terminal:wait-attached @terminal/NAME
+              ghostbox cn:terminal:close @terminal/NAME
+
+            Creates a VM-backed Apple Terminal. Attach proxies a local TTY in raw mode. Wait-attached blocks until client terminal initialization completes. A resize target forwards dimensions to the container or process PTY.
+            """
+        }
+    }
+
+    let operation: String
+    if topic.count == 2 {
+        operation = topic[1]
+    } else if topic.count == 3, topic[1].hasPrefix("@") {
+        operation = topic[2]
+    } else {
+        return nil
+    }
+    let signatures: [String: Set] = [
+        "reader-stream": ["create", "attach", "close"],
+        "writer": ["create", "attach", "close"],
+        "terminal": ["create", "attach", "wait-attached", "close"],
+    ]
+    guard signatures[resource]?.contains(operation) == true else { return nil }
+    return renderIOProxyHelp([resource])
+}
+
+private func renderResourceHelp(
+    _ namespace: String,
+    resource: String,
+    commands: [GhostboxCommandSignature]
+) -> String {
+    var lines = [
+        "Usage:",
+        "  ghostbox \(namespace):\(resource):OPERATION [@\(resource)/NAME] [ARGUMENTS] [OPTIONS]",
+        "",
+        "\(resource) signatures:",
+    ]
+    for command in commands {
+        lines.append(contentsOf: renderSignatureReference(command, indent: "  "))
+    }
+    lines.append("")
+    lines.append("Run 'ghostbox \(namespace):\(resource):OPERATION --help' for argument and output details.")
+    lines.append("Reference operations do not require a real receiver when requesting help.")
+    return lines.joined(separator: "\n")
+}
+
+private func renderSignatureReference(
+    _ command: GhostboxCommandSignature,
+    indent: String
+) -> [String] {
+    var lines = command.signature.split(separator: "\n", omittingEmptySubsequences: false).enumerated().map {
+        (index, line) in (index == 0 ? indent : indent + "  ") + line
+    }
+    lines.append("\(indent)Apple API: \(command.appleAPISymbol)")
+    lines.append("\(indent)Apple docs: \(command.appleDocumentationURL)")
+    return lines
+}
+
+private func renderCommandHelp(_ command: GhostboxCommandSignature) -> String {
+    var lines = [
+        "Usage:",
+    ]
+    lines.append(contentsOf: command.signature.split(separator: "\n", omittingEmptySubsequences: false).enumerated().map {
+        (index, line) in (index == 0 ? "  " : "    ") + line
+    })
+    lines.append("")
+    lines.append("Method: \(command.methodID)")
+    lines.append("Apple API: \(command.appleAPISymbol)")
+    lines.append("Apple docs: \(command.appleDocumentationURL)")
+
+    if !command.positionals.isEmpty {
+        lines.append("")
+        lines.append("Arguments:")
+        for (index, argument) in command.positionals.enumerated() {
+            let receiver = command.shape == .reference && index == 0
+            var traits = [argument.required ? "required" : "optional"]
+            if receiver { traits.append("receiver") }
+            if argument.repeatable { traits.append("repeatable") }
+            lines.append(
+                "  \(valueSyntax(name: argument.name, type: argument.type))  " +
+                "\(traits.joined(separator: ", ")); \(describeType(argument.type))"
+            )
+        }
+    }
+
+    if !command.options.isEmpty {
+        lines.append("")
+        lines.append("Options:")
+        for option in command.options {
+            var traits = [option.required ? "required" : "optional"]
+            if option.repeatable { traits.append("repeatable") }
+            if let defaultValue = option.defaultValue {
+                traits.append("default: \(renderHelpValue(defaultValue))")
+            }
+            let names = option.names.joined(separator: ", ")
+            lines.append(
+                "  \(names)  \(traits.joined(separator: ", ")); " +
+                "type: \(option.type); \(describeType(option.type))"
+            )
+        }
+    }
+
+    if !command.implicitDefaults.isEmpty {
+        lines.append("")
+        lines.append("Implicit defaults:")
+        for (name, value) in command.implicitDefaults.sorted(by: { $0.key < $1.key }) {
+            lines.append("  \(name): \(renderHelpValue(value))")
+        }
+    }
+
+    lines.append("")
+    lines.append("Output:")
+    if command.resultType == "void" {
+        lines.append("  No output on success.")
+    } else {
+        lines.append("  \(command.resultType): \(describeResultType(command.resultType))")
+    }
+    lines.append("")
+    lines.append("Example:")
+    lines.append("  ghostbox " + command.exampleArguments.map(shellQuoted).joined(separator: " "))
+    return lines.joined(separator: "\n")
+}
+
+private func valueSyntax(name: String, type: String) -> String {
+    let baseType = type.hasSuffix("?") ? String(type.dropLast()) : type
+    if baseType.hasPrefix("reference:") {
+        return "@<\(name):id>"
+    }
+    return "<\(name):\(type)>"
+}
+
+private func describeType(_ type: String) -> String {
+    var baseType = type
+    var traits: [String] = []
+    if baseType.hasSuffix("[]") {
+        baseType.removeLast(2)
+        traits.append("array")
+    }
+    if baseType.hasSuffix("?") {
+        baseType.removeLast()
+        traits.append("null accepted")
+    }
+
+    let description: String
+    if baseType.hasPrefix("reference:") {
+        let kind = String(baseType.dropFirst("reference:".count))
+        description = "existing host-owned \(kind) in @\(kind)/NAME form"
+    } else if let separator = baseType.firstIndex(of: "=") {
+        let keyType = String(baseType[.. String {
+    var baseType = type
+    var traits: [String] = []
+    if baseType.hasSuffix("[]") {
+        baseType.removeLast(2)
+        traits.append("array")
+    }
+    if baseType.hasSuffix("?") {
+        baseType.removeLast()
+        traits.append("nullable")
+    }
+    guard baseType.hasPrefix("reference:") else {
+        return describeType(type)
+    }
+
+    let kind = String(baseType.dropFirst("reference:".count))
+    let reference = "canonical host-owned \(kind) reference in @\(kind)/NAME form"
+    guard !traits.isEmpty else { return reference }
+    return "\(traits.joined(separator: ", ")) of \(reference)"
+}
+
+private let typeDescriptions: [String: String] = [
+    "attached-filesystem-map": "JSON map of attached virtual-machine filesystems",
+    "bool": "true or false",
+    "byte-stream": "raw byte stream written directly to stdout",
+    "cidrv4": "IPv4 network in CIDR notation, such as 192.0.2.2/24",
+    "cidrv6": "IPv6 network in CIDR notation, such as 2001:db8::2/64",
+    "container-path": "absolute path inside a container",
+    "container-statistics": "JSON-compatible container resource statistics",
+    "container-url": "URL or path inside a container",
+    "deleted-digests-and-freed-bytes": "JSON-compatible deleted-digest list and freed-byte count",
+    "exit-status": "JSON-compatible process exit status",
+    "file-permissions": "Unix file mode such as 0644",
+    "host-path": "path on the macOS host",
+    "host-url": "file URL or path on the macOS host",
+    "image-description": "JSON-compatible OCI image description",
+    "int": "signed integer",
+    "int32": "32-bit signed integer",
+    "int64": "64-bit signed integer",
+    "ipv4-address": "IPv4 address such as 192.0.2.1",
+    "ipv6-address": "IPv6 address such as 2001:db8::1",
+    "linux-capability": "Linux capability name such as CAP_CHOWN",
+    "linux-signal": "Linux signal name or number such as SIGTERM",
+    "logger-level": "agent logger level such as info or debug",
+    "mac-address": "MAC address such as 02:00:00:00:00:01",
+    "mount-runtime-options": "JSON object matching Apple's mount runtime options",
+    "name": "object name using letters, digits, '.', '_', or '-' (maximum 128 bytes)",
+    "network-mode": "Apple vmnet network mode, such as shared",
+    "oci-descriptor": "JSON-compatible OCI descriptor",
+    "oci-descriptor-json": "OCI descriptor encoded as a JSON object",
+    "oci-image": "JSON-compatible OCI image value",
+    "oci-image-config": "OCI image configuration encoded as a JSON object",
+    "oci-index": "JSON-compatible OCI image index",
+    "oci-linux-capabilities": "JSON-compatible OCI Linux capabilities",
+    "oci-manifest": "JSON-compatible OCI image manifest",
+    "oci-mount": "JSON-compatible OCI mount",
+    "oci-platform": "OCI platform in OS/architecture form, such as linux/arm64",
+    "oci-posix-rlimit": "JSON-compatible OCI POSIX resource limit",
+    "oci-user": "OCI user encoded as a JSON object",
+    "pod-volume-source": "pod volume source encoded as a JSON object",
+    "sha256-digest": "SHA-256 digest in sha256:HEX form",
+    "statistics-category": "Apple container-statistics category",
+    "string": "string",
+    "system-platform": "system platform in OS/architecture form, such as linux/arm64",
+    "uint16": "16-bit unsigned integer",
+    "uint32": "32-bit unsigned integer",
+    "uint64": "64-bit unsigned integer",
+    "virtiofs-layout": "JSON-compatible virtual-machine virtiofs layout",
+    "vm-state": "virtual-machine lifecycle state",
+]
+
+private func renderHelpValue(_ value: GhostboxJSONValue) -> String {
+    switch value {
+    case .null:
+        return "null"
+    case .boolean(let value):
+        return String(value)
+    case .string(let value):
+        return value
+    case .integer(let value):
+        return String(value)
+    case .unsignedInteger(let value):
+        return String(value)
+    case .array(let values):
+        return "[" + values.map(renderHelpValue).joined(separator: ", ") + "]"
+    case .object(let values):
+        return "{" + values.sorted(by: { $0.key < $1.key }).map {
+            "\($0.key): \(renderHelpValue($0.value))"
+        }.joined(separator: ", ") + "}"
+    }
+}
+
+private func shellQuoted(_ argument: String) -> String {
+    let safe = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "_./@:=,+-"))
+    if !argument.isEmpty && argument.unicodeScalars.allSatisfy(safe.contains) {
+        return argument
+    }
+    return "'" + argument.replacingOccurrences(of: "'", with: "'\\''") + "'"
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/LineReader.swift b/macOS/GhostTools/Sources/ghostbox/LineReader.swift
new file mode 100644
index 0000000..1f08338
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/LineReader.swift
@@ -0,0 +1,66 @@
+import Foundation
+
+/// Errors from the line-based NDJSON reader.
+enum LineReaderError: Error {
+    case lineTooLong(max: Int)
+    case ioError(errno: Int32, op: String)
+}
+
+/// Reads newline-delimited lines from a blocking file descriptor.
+/// Enforces a maximum line length to bound memory in a guest.
+final class LineReader {
+    private let fd: Int32
+    private let maxLineBytes: Int
+    private var buffer: [UInt8] = []
+
+    init(fd: Int32, maxLineBytes: Int = 1_048_576) {
+        self.fd = fd
+        self.maxLineBytes = maxLineBytes
+        self.buffer.reserveCapacity(4096)
+    }
+
+    var hasBufferedLine: Bool {
+        buffer.contains(0x0A)
+    }
+
+    /// Read the next complete line (without the trailing `\n`).
+    /// Returns `nil` on clean EOF before any data.
+    /// Throws on line-too-long or read errors.
+    func readLine() throws -> Data? {
+        while true {
+            if let nlIdx = buffer.firstIndex(of: 0x0A) {
+                guard nlIdx <= maxLineBytes else {
+                    throw LineReaderError.lineTooLong(max: maxLineBytes)
+                }
+                let line = Data(buffer[0.. maxLineBytes {
+                throw LineReaderError.lineTooLong(max: maxLineBytes)
+            }
+
+            let readSize = min(4096, maxLineBytes - buffer.count + 1)
+            var chunk = [UInt8](repeating: 0, count: readSize)
+            let n = Darwin.read(fd, &chunk, chunk.count)
+
+            if n < 0 {
+                let err = errno
+                if err == EINTR { continue }
+                throw LineReaderError.ioError(errno: err, op: "read")
+            }
+
+            if n == 0 {
+                if buffer.isEmpty {
+                    return nil
+                }
+                let remaining = Data(buffer)
+                buffer.removeAll(keepingCapacity: true)
+                return remaining
+            }
+
+            buffer.append(contentsOf: chunk[0.. String) {
+    guard forwardingDiagnosticsEnabled else { return }
+    let formatter = ISO8601DateFormatter()
+    formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+    writeStderr("ghostbox: forward-diagnostic timestamp=\(formatter.string(from: Date())) \(message())\n")
+}
+
+struct PublishedPort: Equatable, Sendable {
+    let hostAddress: String
+    let hostPort: UInt16
+    let containerPort: UInt16
+}
+
+enum PortForwardError: Error, LocalizedError {
+    case invalidAddress(String)
+    case network(operation: String, description: String)
+    case socket(operation: String, code: Int32)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidAddress(let address):
+            return "invalid IPv4 address \(address)"
+        case .network(let operation, let description):
+            return "\(operation) failed: \(description)"
+        case .socket(let operation, let code):
+            return "\(operation) failed: errno \(code) (\(String(cString: strerror(code))))"
+        }
+    }
+}
+
+func parsePublishedPort(_ specification: String) -> Result {
+    let protocolParts = specification.split(separator: "/", omittingEmptySubsequences: false)
+    guard protocolParts.count <= 2 else {
+        return .failure(.invalidDirect("invalid published port: invalid protocol suffix"))
+    }
+    if protocolParts.count == 2, protocolParts[1].lowercased() != "tcp" {
+        return .failure(.invalidDirect("invalid published port: only TCP is supported"))
+    }
+    let fields = protocolParts[0].split(separator: ":", omittingEmptySubsequences: false).map(String.init)
+    guard fields.count == 2 || fields.count == 3 else {
+        return .failure(.invalidDirect("invalid published port: expected [HOST_IP:]HOST_PORT:CONTAINER_PORT[/tcp]"))
+    }
+    let hostAddress = fields.count == 3 ? fields[0] : "127.0.0.1"
+    let hostPortText = fields.count == 3 ? fields[1] : fields[0]
+    let containerPortText = fields.count == 3 ? fields[2] : fields[1]
+    var address = in_addr()
+    guard hostAddress.withCString({ inet_pton(AF_INET, $0, &address) }) == 1 else {
+        return .failure(.invalidDirect("invalid published port: host address must be an IPv4 address"))
+    }
+    guard let hostPort = UInt16(hostPortText), hostPort > 0 else {
+        return .failure(.invalidDirect("invalid published port: host port must be between 1 and 65535"))
+    }
+    guard let containerPort = UInt16(containerPortText), containerPort > 0 else {
+        return .failure(.invalidDirect("invalid published port: container port must be between 1 and 65535"))
+    }
+    return .success(PublishedPort(hostAddress: hostAddress, hostPort: hostPort, containerPort: containerPort))
+}
+
+final class PublishedPortForwarder: @unchecked Sendable {
+    private let publication: PublishedPort
+    private let queue: DispatchQueue
+    private let listener: NWListener
+    private let listenerTermination = ListenerTermination()
+    private let lock = NSLock()
+    private var started = false
+    private var stopped = false
+    private var targetAddress: String?
+    private var pendingConnections: [(id: UUID, connection: NWConnection)] = []
+    private var relays: [UUID: NetworkRelay] = [:]
+    private var onFailure: (@Sendable (Error) -> Void)?
+    private var listenerFailure: Error?
+
+    init(_ publication: PublishedPort) async throws {
+        self.publication = publication
+        queue = DispatchQueue(label: "org.ghostvm.ghostbox.publish.\(publication.hostPort)", qos: .userInitiated)
+        guard let address = IPv4Address(publication.hostAddress),
+              let port = NWEndpoint.Port(rawValue: publication.hostPort) else {
+            throw PortForwardError.invalidAddress(publication.hostAddress)
+        }
+
+        let parameters = NWParameters.tcp
+        parameters.allowLocalEndpointReuse = true
+        parameters.requiredLocalEndpoint = .hostPort(host: .ipv4(address), port: port)
+        do {
+            listener = try NWListener(using: parameters)
+        } catch let error as NWError {
+            throw Self.forwardError(operation: "listen", error: error)
+        }
+
+        let startup = ListenerStartup()
+        let listenerTermination = self.listenerTermination
+        listener.stateUpdateHandler = { [weak self] state in
+            switch state {
+            case .ready:
+                startup.complete(.success(()))
+            case .failed(let error):
+                startup.complete(.failure(Self.forwardError(operation: "listen", error: error)))
+                listenerTermination.complete()
+                self?.listenerFailed(error)
+            case .cancelled:
+                startup.complete(.failure(PortForwardError.network(operation: "listen", description: "cancelled")))
+                listenerTermination.complete()
+            default:
+                break
+            }
+        }
+        listener.newConnectionHandler = { [weak self] connection in
+            guard let self else {
+                connection.cancel()
+                return
+            }
+            self.accept(connection)
+        }
+        listener.start(queue: queue)
+        queue.asyncAfter(deadline: .now() + 5) {
+            startup.complete(.failure(PortForwardError.network(operation: "listen", description: "timed out")))
+        }
+
+        switch await startup.wait() {
+        case .success:
+            break
+        case .failure(let error):
+            listener.cancel()
+            await listenerTermination.wait()
+            throw error
+        }
+    }
+
+    func start(
+        targetAddress: String,
+        onFailure: @escaping @Sendable (Error) -> Void = { _ in }
+    ) {
+        let (pending, failure): ([(id: UUID, connection: NWConnection)], Error?) = lock.withLock {
+            guard !started else { return ([], nil) }
+            started = true
+            guard !stopped else { return ([], listenerFailure) }
+            self.targetAddress = targetAddress
+            self.onFailure = onFailure
+            defer { pendingConnections.removeAll() }
+            return (pendingConnections, nil)
+        }
+        forwardingDiagnostic(
+            "event=start connectionID=- targetAddress=\(targetAddress) pendingConnections.count=\(pending.count)"
+        )
+        if let failure {
+            onFailure(failure)
+            return
+        }
+        pending.forEach { forward($0.connection, connectionID: $0.id, targetAddress: targetAddress) }
+    }
+
+    func stop() async {
+        let active = cancel()
+        await listenerTermination.wait()
+        for relay in active { await relay.waitUntilStopped() }
+    }
+
+    deinit { _ = cancel() }
+
+    private func cancel() -> [NetworkRelay] {
+        let (active, shouldCancel): ([NetworkRelay], Bool) = lock.withLock {
+            let active = Array(relays.values)
+            guard !stopped else { return (active, false) }
+            stopped = true
+            pendingConnections.forEach { $0.connection.cancel() }
+            pendingConnections.removeAll()
+            return (active, true)
+        }
+        if shouldCancel { listener.cancel() }
+        active.forEach { $0.cancel() }
+        return active
+    }
+
+    private func accept(_ connection: NWConnection) {
+        let connectionID = UUID()
+        let state = lock.withLock { () -> (target: String?, pendingCount: Int, stopped: Bool) in
+            guard !stopped else { return (nil, pendingConnections.count, true) }
+            guard let targetAddress else {
+                pendingConnections.append((connectionID, connection))
+                return (nil, pendingConnections.count, false)
+            }
+            return (targetAddress, pendingConnections.count, false)
+        }
+        forwardingDiagnostic(
+            "event=accept connectionID=\(connectionID) targetAddress=\(state.target ?? "nil") "
+                + "pendingConnections.count=\(state.pendingCount) stopped=\(state.stopped)"
+        )
+        if let target = state.target {
+            forward(connection, connectionID: connectionID, targetAddress: target)
+        } else if state.stopped {
+            connection.cancel()
+        }
+    }
+
+    private func forward(_ connection: NWConnection, connectionID: UUID, targetAddress: String) {
+        forwardingDiagnostic(
+            "event=forward connectionID=\(connectionID) targetAddress=\(targetAddress) "
+                + "pendingConnections.count=\(lock.withLock { pendingConnections.count })"
+        )
+        guard let address = IPv4Address(targetAddress),
+              let port = NWEndpoint.Port(rawValue: publication.containerPort) else {
+            connection.cancel()
+            writeStderr("ghostbox: port \(publication.hostPort) forwarding failed: invalid IPv4 address \(targetAddress)\n")
+            return
+        }
+        let relay = NetworkRelay(
+            connectionID: connectionID,
+            targetAddress: targetAddress,
+            client: connection,
+            target: NWConnection(host: .ipv4(address), port: port, using: .tcp),
+            queue: DispatchQueue(label: "org.ghostvm.ghostbox.relay.\(connectionID)", qos: .userInitiated),
+            onTargetFailure: { [publication] error in
+                writeStderr("ghostbox: port \(publication.hostPort) forwarding failed: \(error.localizedDescription)\n")
+            },
+            completion: { [weak self] in self?.removeRelay(connectionID) }
+        )
+        let shouldStart = lock.withLock {
+            guard !stopped else { return false }
+            relays[connectionID] = relay
+            return true
+        }
+        guard shouldStart else {
+            relay.cancelBeforeStart()
+            return
+        }
+        relay.start()
+    }
+
+    private func removeRelay(_ id: UUID) {
+        lock.withLock { _ = relays.removeValue(forKey: id) }
+    }
+
+    private func listenerFailed(_ error: NWError) {
+        let failure = Self.forwardError(operation: "accept", error: error)
+        let (active, callback): ([NetworkRelay], (@Sendable (Error) -> Void)?) = lock.withLock {
+            guard !stopped else { return ([], nil) }
+            stopped = true
+            listenerFailure = failure
+            let active = Array(relays.values)
+            pendingConnections.forEach { $0.connection.cancel() }
+            pendingConnections.removeAll()
+            return (active, started ? onFailure : nil)
+        }
+        listener.cancel()
+        active.forEach { $0.cancel() }
+        callback?(failure)
+    }
+
+    fileprivate static func forwardError(operation: String, error: NWError) -> PortForwardError {
+        if case .posix(let code) = error {
+            return .socket(operation: operation, code: code.rawValue)
+        }
+        return .network(operation: operation, description: String(describing: error))
+    }
+}
+
+private final class ListenerStartup: @unchecked Sendable {
+    private let lock = NSLock()
+    private var result: Result?
+    private var continuation: CheckedContinuation, Never>?
+
+    func complete(_ result: Result) {
+        let continuation: CheckedContinuation, Never>? = lock.withLock {
+            guard self.result == nil else { return nil }
+            self.result = result
+            defer { self.continuation = nil }
+            return self.continuation
+        }
+        continuation?.resume(returning: result)
+    }
+
+    func wait() async -> Result {
+        await withCheckedContinuation { continuation in
+            let result = lock.withLock { () -> Result? in
+                if let result = self.result { return result }
+                self.continuation = continuation
+                return nil
+            }
+            if let result { continuation.resume(returning: result) }
+        }
+    }
+}
+
+private final class ListenerTermination: @unchecked Sendable {
+    private let lock = NSLock()
+    private var completed = false
+    private var continuations: [CheckedContinuation] = []
+
+    func complete() {
+        let continuations: [CheckedContinuation] = lock.withLock {
+            guard !completed else { return [] }
+            completed = true
+            defer { self.continuations.removeAll() }
+            return self.continuations
+        }
+        continuations.forEach { $0.resume() }
+    }
+
+    func wait() async {
+        await withCheckedContinuation { continuation in
+            let completed = lock.withLock {
+                guard !self.completed else { return true }
+                continuations.append(continuation)
+                return false
+            }
+            if completed { continuation.resume() }
+        }
+    }
+}
+
+private final class NetworkRelay: @unchecked Sendable {
+    private let connectionID: UUID
+    private let targetAddress: String
+    private let client: NWConnection
+    private let target: NWConnection
+    private let queue: DispatchQueue
+    private let onTargetFailure: @Sendable (Error) -> Void
+    private let completion: @Sendable () -> Void
+    private let termination = ListenerTermination()
+    private var clientReady = false
+    private var targetReady = false
+    private var pumpsStarted = false
+    private var clientPumpFinished = false
+    private var targetPumpFinished = false
+    private var clientTerminalState = false
+    private var targetTerminalState = false
+    private var started = false
+    private var closed = false
+    private var reportedTargetFailure = false
+
+    init(
+        connectionID: UUID,
+        targetAddress: String,
+        client: NWConnection,
+        target: NWConnection,
+        queue: DispatchQueue,
+        onTargetFailure: @escaping @Sendable (Error) -> Void,
+        completion: @escaping @Sendable () -> Void
+    ) {
+        self.connectionID = connectionID
+        self.targetAddress = targetAddress
+        self.client = client
+        self.target = target
+        self.queue = queue
+        self.onTargetFailure = onTargetFailure
+        self.completion = completion
+    }
+
+    func start() {
+        queue.async { [self] in
+            guard !started, !closed else { return }
+            started = true
+            client.stateUpdateHandler = { [weak self] state in self?.connectionStateChanged(state, isTarget: false) }
+            target.stateUpdateHandler = { [weak self] state in self?.connectionStateChanged(state, isTarget: true) }
+            client.start(queue: queue)
+            target.start(queue: queue)
+        }
+    }
+
+    func cancel() {
+        queue.async { [self] in
+            close()
+        }
+    }
+
+    func cancelBeforeStart() {
+        close()
+    }
+
+    func waitUntilStopped() async {
+        await termination.wait()
+    }
+
+    private func connectionStateChanged(_ state: NWConnection.State, isTarget: Bool) {
+        guard !closed else { return }
+        let (stateName, errorDescription): (String, String) = switch state {
+        case .setup: ("setup", "nil")
+        case .preparing: ("preparing", "nil")
+        case .ready: ("ready", "nil")
+        case .waiting(let error): ("waiting", String(describing: error))
+        case .failed(let error): ("failed", String(describing: error))
+        case .cancelled: ("cancelled", "nil")
+        @unknown default: (String(describing: state), "nil")
+        }
+        forwardingDiagnostic(
+            "event=state connectionID=\(connectionID) targetAddress=\(targetAddress) isTarget=\(isTarget) "
+                + "state=\(stateName) error=\(errorDescription)"
+        )
+        switch state {
+        case .ready:
+            if isTarget { targetReady = true } else { clientReady = true }
+            startPumpsIfReady()
+        case .waiting(let error), .failed(let error):
+            if !pumpsStarted {
+                if isTarget, !targetReady, !reportedTargetFailure {
+                    reportedTargetFailure = true
+                    onTargetFailure(PublishedPortForwarder.forwardError(operation: "connect", error: error))
+                }
+                close()
+            } else if case .failed = state {
+                terminalStateChanged(isTarget: isTarget)
+            }
+        case .cancelled:
+            if !pumpsStarted {
+                close()
+            } else {
+                terminalStateChanged(isTarget: isTarget)
+            }
+        default:
+            break
+        }
+    }
+
+    private func startPumpsIfReady() {
+        forwardingDiagnostic(
+            "event=pump-check connectionID=\(connectionID) targetAddress=\(targetAddress) isTarget=- "
+                + "clientReady=\(clientReady) targetReady=\(targetReady) pumpsStarted=\(pumpsStarted)"
+        )
+        guard clientReady, targetReady, !pumpsStarted else { return }
+        pumpsStarted = true
+        forwardingDiagnostic(
+            "event=pump-started connectionID=\(connectionID) targetAddress=\(targetAddress) isTarget=-"
+        )
+        receive(from: client, sendTo: target, inputIsTarget: false)
+        receive(from: target, sendTo: client, inputIsTarget: true)
+    }
+
+    private func receive(from input: NWConnection, sendTo output: NWConnection, inputIsTarget: Bool) {
+        input.receive(minimumIncompleteLength: 1, maximumLength: 32 * 1024) { [weak self] data, _, isComplete, error in
+            guard let self, !closed else { return }
+            if isComplete {
+                output.send(
+                    content: data,
+                    contentContext: .finalMessage,
+                    isComplete: true,
+                    completion: .contentProcessed { [weak self] error in
+                        guard let self, !closed else { return }
+                        if error == nil { finishPump(isTarget: inputIsTarget) } else { close() }
+                    }
+                )
+            } else if error != nil {
+                guard let data, !data.isEmpty else {
+                    close()
+                    return
+                }
+                output.send(content: data, completion: .contentProcessed { [weak self] _ in self?.close() })
+            } else if let data, !data.isEmpty {
+                output.send(content: data, completion: .contentProcessed { [weak self] error in
+                    guard let self, !closed else { return }
+                    if error == nil {
+                        receive(from: input, sendTo: output, inputIsTarget: inputIsTarget)
+                    } else {
+                        close()
+                    }
+                })
+            } else {
+                receive(from: input, sendTo: output, inputIsTarget: inputIsTarget)
+            }
+        }
+    }
+
+    private func terminalStateChanged(isTarget: Bool) {
+        if isTarget {
+            targetTerminalState = true
+            if targetPumpFinished { close() }
+        } else {
+            clientTerminalState = true
+            if clientPumpFinished { close() }
+        }
+    }
+
+    private func finishPump(isTarget: Bool) {
+        if isTarget {
+            targetPumpFinished = true
+            if targetTerminalState { close() }
+        } else {
+            clientPumpFinished = true
+            if clientTerminalState { close() }
+        }
+        if clientPumpFinished, targetPumpFinished { close() }
+    }
+
+    private func close() {
+        guard !closed else { return }
+        closed = true
+        client.stateUpdateHandler = nil
+        target.stateUpdateHandler = nil
+        client.cancel()
+        target.cancel()
+        completion()
+        termination.complete()
+    }
+}
diff --git a/macOS/GhostTools/Sources/ghostbox/Transport.swift b/macOS/GhostTools/Sources/ghostbox/Transport.swift
new file mode 100644
index 0000000..b2d6bad
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/Transport.swift
@@ -0,0 +1,6 @@
+import Foundation
+
+let kProtocolVersion = 5
+let kDefaultVsockPort: UInt32 = 5004
+let VMADDR_CID_HOST: UInt32 = 2
+let AF_VSOCK: Int32 = 40
diff --git a/macOS/GhostTools/Sources/ghostbox/VsockDial.swift b/macOS/GhostTools/Sources/ghostbox/VsockDial.swift
new file mode 100644
index 0000000..26acf58
--- /dev/null
+++ b/macOS/GhostTools/Sources/ghostbox/VsockDial.swift
@@ -0,0 +1,84 @@
+import Foundation
+
+/// sockaddr_vm structure for AF_VSOCK addressing.
+/// Must match the kernel's sockaddr_vm layout exactly (12 bytes on Darwin).
+struct sockaddr_vm {
+    var svm_len: UInt8
+    var svm_family: UInt8
+    var svm_reserved1: UInt16
+    var svm_port: UInt32
+    var svm_cid: UInt32
+
+    init(port: UInt32, cid: UInt32) {
+        self.svm_len = UInt8(MemoryLayout.size)
+        self.svm_family = UInt8(AF_VSOCK)
+        self.svm_reserved1 = 0
+        self.svm_port = port
+        self.svm_cid = cid
+    }
+}
+
+enum VsockDialError: Error, CustomStringConvertible {
+    case socketCreationFailed(errno: Int32)
+    case connectFailed(errno: Int32)
+
+    var description: String {
+        switch self {
+        case .socketCreationFailed(let err):
+            return "socket(AF_VSOCK) failed: errno \(err) (\(String(cString: strerror(err))))"
+        case .connectFailed(let err):
+            return "connect() failed: errno \(err) (\(String(cString: strerror(err))))"
+        }
+    }
+}
+
+/// Dial the host via AF_VSOCK, returning a blocking file descriptor.
+/// Uses `VMADDR_CID_HOST` (2) to reach the VM host.
+func vsockDialHost(port: UInt32) throws -> Int32 {
+    let fd = socket(AF_VSOCK, SOCK_STREAM, 0)
+    guard fd >= 0 else {
+        throw VsockDialError.socketCreationFailed(errno: errno)
+    }
+
+    var addr = sockaddr_vm(port: port, cid: VMADDR_CID_HOST)
+
+    let rc = withUnsafePointer(to: &addr) { addrPtr in
+        addrPtr.withMemoryRebound(to: sockaddr.self, capacity: 1) { sockaddrPtr in
+            Darwin.connect(fd, sockaddrPtr, socklen_t(MemoryLayout.size))
+        }
+    }
+
+    guard rc == 0 else {
+        let err = errno
+        Darwin.close(fd)
+        throw VsockDialError.connectFailed(errno: err)
+    }
+
+    return fd
+}
+
+/// Write all bytes to a blocking fd, retrying on EINTR.
+@discardableResult
+func writeAll(fd: Int32, _ data: Data) -> Bool {
+    if data.isEmpty { return true }
+    return data.withUnsafeBytes { rawBuffer -> Bool in
+        guard let base = rawBuffer.baseAddress else { return false }
+        var offset = 0
+        while offset < data.count {
+            let written = Darwin.write(fd, base.advanced(by: offset), data.count - offset)
+            if written < 0 {
+                if errno == EINTR { continue }
+                return false
+            }
+            if written == 0 { return false }
+            offset += written
+        }
+        return true
+    }
+}
+
+/// Write a byte sequence to a fd, retrying on EINTR.
+@discardableResult
+func writeBytes(fd: Int32, _ bytes: [UInt8]) -> Bool {
+    return writeAll(fd: fd, Data(bytes))
+}
diff --git a/macOS/GhostTools/Tests/GhostToolsTests/GuestFilesystemRouterTests.swift b/macOS/GhostTools/Tests/GhostToolsTests/GuestFilesystemRouterTests.swift
new file mode 100644
index 0000000..4fb5001
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostToolsTests/GuestFilesystemRouterTests.swift
@@ -0,0 +1,211 @@
+import Foundation
+import XCTest
+@testable import GhostTools
+
+final class GuestFilesystemRouterTests: XCTestCase {
+    private var directory: URL!
+
+    override func setUpWithError() throws {
+        directory = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghosttools-fs-tests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+        try Data("abcdef".utf8).write(to: directory.appendingPathComponent("sample.txt"))
+        try FileManager.default.createDirectory(
+            at: directory.appendingPathComponent("folder", isDirectory: true),
+            withIntermediateDirectories: true
+        )
+        try FileManager.default.createSymbolicLink(
+            atPath: directory.appendingPathComponent("sample-link").path,
+            withDestinationPath: "sample.txt"
+        )
+    }
+
+    override func tearDownWithError() throws {
+        try? FileManager.default.removeItem(at: directory)
+    }
+
+    func testMetadataReturnsRegularFileAttributes() throws {
+        let response = try route(
+            path: "/api/v1/fs/metadata", query: [
+                URLQueryItem(name: "path", value: directory.appendingPathComponent("sample.txt").path),
+            ]
+        )
+
+        XCTAssertEqual(response.status, .ok)
+        let metadata = try JSONDecoder().decode(GuestFileMetadata.self, from: responseData(response))
+        XCTAssertEqual(metadata.name, "sample.txt")
+        XCTAssertEqual(metadata.type, .file)
+        XCTAssertEqual(metadata.size, 6)
+        XCTAssertNotEqual(metadata.inode, 0)
+    }
+
+    func testListReturnsTypedEntries() throws {
+        let response = try route(
+            path: "/api/v1/fs/list", query: [URLQueryItem(name: "path", value: directory.path)]
+        )
+
+        XCTAssertEqual(response.status, .ok)
+        let listing = try JSONDecoder().decode(GuestDirectoryMetadata.self, from: responseData(response))
+        XCTAssertEqual(listing.entries.map(\.name), ["folder", "sample-link", "sample.txt"])
+        XCTAssertEqual(listing.entries.map(\.type), [.directory, .symbolicLink, .file])
+    }
+
+    func testRangeReadReturnsRequestedBytes() throws {
+        let response = try route(
+            path: "/api/v1/fs/read", query: [
+                URLQueryItem(name: "path", value: directory.appendingPathComponent("sample.txt").path),
+                URLQueryItem(name: "offset", value: "2"),
+                URLQueryItem(name: "length", value: "3"),
+            ]
+        )
+
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertEqual(String(data: try responseData(response), encoding: .utf8), "cde")
+    }
+
+    func testRangeReadRejectsMoreThanOneMiB() throws {
+        let response = try route(
+            path: "/api/v1/fs/read", query: [
+                URLQueryItem(name: "path", value: directory.appendingPathComponent("sample.txt").path),
+                URLQueryItem(name: "offset", value: "0"),
+                URLQueryItem(name: "length", value: String(1024 * 1024 + 1)),
+            ]
+        )
+
+        XCTAssertEqual(response.status, .badRequest)
+    }
+
+    func testReadSymbolicLinkReturnsTarget() throws {
+        let response = try route(
+            path: "/api/v1/fs/readlink", query: [
+                URLQueryItem(name: "path", value: directory.appendingPathComponent("sample-link").path),
+            ]
+        )
+
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertEqual(String(data: try responseData(response), encoding: .utf8), "sample.txt")
+    }
+
+    func testMutationLifecycle() throws {
+        let createdURL = directory.appendingPathComponent("created.txt")
+        var response = try route(
+            method: .POST,
+            path: "/api/v1/fs/create",
+            body: try JSONEncoder().encode(FSCreateRequest(path: createdURL.path, type: .file, mode: 0o640))
+        )
+        XCTAssertEqual(response.status, .ok)
+
+        response = try route(
+            method: .PATCH,
+            path: "/api/v1/fs/write",
+            query: [
+                URLQueryItem(name: "path", value: createdURL.path),
+                URLQueryItem(name: "offset", value: "2"),
+            ],
+            body: Data("abc".utf8)
+        )
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertEqual(try Data(contentsOf: createdURL), Data([0, 0]) + Data("abc".utf8))
+
+        response = try route(
+            method: .PATCH,
+            path: "/api/v1/fs/attributes",
+            body: try JSONEncoder().encode(FSSetAttributesRequest(
+                path: createdURL.path,
+                attributes: FSFileAttributes(
+                    mode: 0o600,
+                    size: 4,
+                    modifiedSeconds: 1_700_000_000,
+                    modifiedNanoseconds: 0,
+                    accessedSeconds: nil,
+                    accessedNanoseconds: nil
+                )
+            ))
+        )
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertEqual(try Data(contentsOf: createdURL).count, 4)
+        let attributes = try FileManager.default.attributesOfItem(atPath: createdURL.path)
+        XCTAssertEqual((attributes[.posixPermissions] as? NSNumber)?.uint32Value, 0o600)
+
+        let renamedURL = directory.appendingPathComponent("renamed.txt")
+        response = try route(
+            method: .POST,
+            path: "/api/v1/fs/rename",
+            body: try JSONEncoder().encode(FSRenameRequest(
+                path: createdURL.path,
+                destinationPath: renamedURL.path
+            ))
+        )
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertTrue(FileManager.default.fileExists(atPath: renamedURL.path))
+
+        let linkURL = directory.appendingPathComponent("created-link")
+        response = try route(
+            method: .POST,
+            path: "/api/v1/fs/symlink",
+            body: try JSONEncoder().encode(FSSymbolicLinkRequest(
+                path: linkURL.path,
+                destination: "renamed.txt"
+            ))
+        )
+        XCTAssertEqual(response.status, .ok)
+        XCTAssertEqual(try FileManager.default.destinationOfSymbolicLink(atPath: linkURL.path), "renamed.txt")
+
+        response = try route(
+            method: .DELETE,
+            path: "/api/v1/fs/remove",
+            query: [URLQueryItem(name: "path", value: renamedURL.path)]
+        )
+        XCTAssertEqual(response.status, .noContent)
+        XCTAssertFalse(FileManager.default.fileExists(atPath: renamedURL.path))
+    }
+
+    func testCreateDirectoryAndPreservePOSIXError() throws {
+        let newDirectory = directory.appendingPathComponent("new-directory", isDirectory: true)
+        let requestBody = try JSONEncoder().encode(FSCreateRequest(
+            path: newDirectory.path,
+            type: .directory,
+            mode: 0o750
+        ))
+        XCTAssertEqual(
+            try route(method: .POST, path: "/api/v1/fs/create", body: requestBody).status,
+            .ok
+        )
+
+        let duplicate = try route(method: .POST, path: "/api/v1/fs/create", body: requestBody)
+        XCTAssertEqual(duplicate.status, .conflict)
+        let payload = try JSONDecoder().decode(GuestFilesystemErrorResponse.self, from: responseData(duplicate))
+        XCTAssertEqual(payload.errno, EEXIST)
+    }
+
+    func testReadErrorPreservesPOSIXError() throws {
+        let response = try route(
+            path: "/api/v1/fs/metadata",
+            query: [URLQueryItem(name: "path", value: directory.appendingPathComponent("missing").path)]
+        )
+        XCTAssertEqual(response.status, .notFound)
+        let payload = try JSONDecoder().decode(GuestFilesystemErrorResponse.self, from: responseData(response))
+        XCTAssertEqual(payload.errno, ENOENT)
+    }
+
+    private func route(
+        method: HTTPMethod = .GET,
+        path: String,
+        query: [URLQueryItem] = [],
+        body: Data = Data()
+    ) throws -> HTTPResponse {
+        var components = URLComponents()
+        components.path = path
+        components.queryItems = query
+        let request = HTTPRequest(method: method, path: components.string!, headers: [:])
+        let reader = BodyReader(fd: -1, framing: .knownLength(body.count), prelude: body)
+        return try Router().route(request: request, body: reader)
+    }
+
+    private func responseData(_ response: HTTPResponse) throws -> Data {
+        guard case .bytes(let data) = response.body else {
+            throw XCTSkip("Expected an in-memory response body")
+        }
+        return data
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/ArgsTests.swift b/macOS/GhostTools/Tests/GhostboxTests/ArgsTests.swift
new file mode 100644
index 0000000..5f38401
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/ArgsTests.swift
@@ -0,0 +1,394 @@
+@testable import ghostbox
+import XCTest
+
+final class ArgsTests: XCTestCase {
+    func testNoArgumentsReturnsHelp() {
+        guard case .success(let options) = parseArguments([]), case .help(let topic) = options.action else {
+            return XCTFail("Expected help")
+        }
+        XCTAssertEqual(topic, [])
+    }
+
+    func testHelpAndVersionFlags() {
+        for flag in ["--help", "-h", "help"] {
+            guard case .success(let options) = parseArguments([flag]), case .help(let topic) = options.action else {
+                return XCTFail("Expected help for \(flag)")
+            }
+            XCTAssertEqual(topic, [])
+        }
+        for flag in ["--version", "-v"] {
+            guard case .success(let options) = parseArguments([flag]), case .version = options.action else {
+                return XCTFail("Expected version for \(flag)")
+            }
+        }
+    }
+
+    func testParsesQualifiedHelpTopics() {
+        let cases: [([String], [String])] = [
+            (["cn:help"], ["cn"]),
+            (["containerization:help"], ["cn"]),
+            (["cr:help"], ["cr"]),
+            (["container:help"], ["cr"]),
+            (["cn:image-store:help"], ["cn", "image-store"]),
+            (["containerization:image-store:help"], ["cn", "image-store"]),
+            (["cn:image-store:pull", "--help"], ["cn:image-store:pull"]),
+            (["cn:image-store:pull", "@image-store/default", "--help"], ["cn:image-store:pull"]),
+        ]
+        for (arguments, expectedTopic) in cases {
+            guard case .success(let options) = parseArguments(arguments),
+                  case .help(let topic) = options.action else {
+                return XCTFail("Expected help for \(arguments)")
+            }
+            XCTAssertEqual(topic, expectedTopic)
+        }
+    }
+
+    func testHelpFlagMustBeFinal() {
+        guard case .failure(.invalidDirect(let message)) = parseArguments([
+            "cn:image-store:pull", "--help", "alpine",
+        ]) else {
+            return XCTFail("Expected invalid help placement")
+        }
+        XCTAssertTrue(message.contains("final argument"))
+    }
+
+    func testParsesDNSCreateWithFrameworkDefaults() throws {
+        let invocation = try directInvocation(["cn:dns:create", "default"])
+        XCTAssertEqual(invocation.method, .dnsCreate)
+        XCTAssertEqual(invocation.parameters["name"], .string("default"))
+        XCTAssertNil(invocation.parameters["nameservers"])
+        XCTAssertNil(invocation.parameters["domain"])
+        XCTAssertEqual(invocation.parameters["searchDomains"], .array([]))
+        XCTAssertEqual(invocation.parameters["options"], .array([]))
+    }
+
+    func testParsesConfiguredDNSCreate() throws {
+        let invocation = try directInvocation([
+            "cn:dns:create", "dev",
+            "--nameserver", "1.1.1.1",
+            "--nameserver", "2606:4700:4700::1111",
+            "--domain", "example.test",
+            "--search-domain", "svc.example.test",
+            "--option", "ndots:2",
+        ])
+        XCTAssertEqual(invocation.parameters["nameservers"], .array([.string("1.1.1.1"), .string("2606:4700:4700::1111")]))
+        XCTAssertEqual(invocation.parameters["domain"], .string("example.test"))
+        XCTAssertEqual(invocation.parameters["searchDomains"], .array([.string("svc.example.test")]))
+        XCTAssertEqual(invocation.parameters["options"], .array([.string("ndots:2")]))
+    }
+
+    func testDNSCreatePreservesEmptyInitializerValues() throws {
+        let invocation = try directInvocation([
+            "cn:dns:create", "empty", "--nameserver", "", "--domain", "",
+            "--search-domain", "", "--option", "",
+        ])
+        XCTAssertEqual(invocation.parameters["nameservers"], .array([.string("")]))
+        XCTAssertEqual(invocation.parameters["domain"], .string(""))
+        XCTAssertEqual(invocation.parameters["searchDomains"], .array([.string("")]))
+        XCTAssertEqual(invocation.parameters["options"], .array([.string("")]))
+    }
+
+    func testPreservesAllThirteenEstablishedCommandMappings() throws {
+        let commands: [([String], GhostboxDirectMethod, [String: GhostboxJSONValue])] = [
+            (["cn:dns:create", "dev"], .dnsCreate, ["name": .string("dev"), "searchDomains": .array([]), "options": .array([])]),
+            (["cn:dns:default-nameservers"], .dnsDefaultNameservers, [:]),
+            (["cn:dns:validate", "@dns/dev"], .dnsValidate, ["reference": .string("@dns/dev")]),
+            (["cn:dns:resolv-conf", "@dns/dev"], .dnsResolvConf, ["reference": .string("@dns/dev")]),
+            (["cn:dns:nameservers", "@dns/dev"], .dnsNameservers, ["reference": .string("@dns/dev")]),
+            (["cn:dns:domain", "@dns/dev"], .dnsDomain, ["reference": .string("@dns/dev")]),
+            (["cn:dns:search-domains", "@dns/dev"], .dnsSearchDomains, ["reference": .string("@dns/dev")]),
+            (["cn:dns:options", "@dns/dev"], .dnsOptions, ["reference": .string("@dns/dev")]),
+            (["cn:process-config:default-path"], .processConfigDefaultPath, [:]),
+            (["cn:container:default-masked-paths"], .containerDefaultMaskedPaths, [:]),
+            (["cn:container:default-readonly-paths"], .containerDefaultReadonlyPaths, [:]),
+            (["cn:container:default-copy-chunk-size"], .containerDefaultCopyChunkSize, [:]),
+            (["cn:container:max-id-length"], .containerMaxIDLength, [:]),
+        ]
+
+        XCTAssertEqual(commands.count, 13)
+        for (arguments, method, parameters) in commands {
+            let invocation = try directInvocation(arguments)
+            XCTAssertEqual(invocation.method, method, "Unexpected method for \(arguments)")
+            XCTAssertEqual(invocation.parameters, parameters, "Unexpected parameters for \(arguments)")
+        }
+    }
+
+    func testAcceptsCatalogCommand() throws {
+        let invocation = try directInvocation(["cn:image-store:list", "@image-store/default"])
+        XCTAssertEqual(invocation.method.rawValue, "imageStore.list")
+        XCTAssertEqual(invocation.parameters, ["imageStore": .string("@image-store/default")])
+    }
+
+    func testParsesDefaultHostKernelExtension() throws {
+        let invocation = try directInvocation(["cn:kernel:default"])
+        XCTAssertEqual(invocation.method, .kernelDefault)
+        XCTAssertEqual(invocation.parameters, [:])
+    }
+
+    func testParsesInstallRecommendedHostKernelExtension() throws {
+        let invocation = try directInvocation(["cn:kernel:install-recommended"])
+        XCTAssertEqual(invocation.method, .kernelInstallRecommended)
+        XCTAssertEqual(invocation.parameters, [:])
+    }
+
+    func testCatalogMapsReferencesOptionsAndPositionalsToParameters() throws {
+        let invocation = try directInvocation([
+            "cn:image-store:pull", "@image-store/default", "alpine",
+            "--insecure=false", "--authentication", "@authentication/default",
+        ])
+        XCTAssertEqual(invocation.method.rawValue, "imageStore.pull")
+        XCTAssertEqual(invocation.parameters, [
+            "imageStore": .string("@image-store/default"),
+            "reference": .string("alpine"),
+            "insecure": .boolean(false),
+            "authentication": .string("@authentication/default"),
+            "maxConcurrentDownloads": .integer(3),
+        ])
+    }
+
+    func testRejectsInvalidDNSReference() {
+        guard case .failure(.invalidDirect) = parseArguments(["cn:dns:validate", "@hosts/dev"]) else {
+            return XCTFail("Expected wrong-kind reference rejection")
+        }
+    }
+
+    func testParsesIOProxyCreationAndCloseCommands() throws {
+        let commands: [([String], GhostboxDirectMethod, [String: GhostboxJSONValue])] = [
+            (["cn:reader-stream:create", "input"], .readerStreamCreateProxy, ["readerStream": .string("input")]),
+            (["cn:reader-stream:close", "@reader-stream/input"], .readerStreamCloseProxy, ["readerStream": .string("@reader-stream/input")]),
+            (["cn:writer:create", "output"], .writerCreateProxy, ["writer": .string("output")]),
+            (["cn:writer:close", "@writer/output"], .writerCloseProxy, ["writer": .string("@writer/output")]),
+            (["cn:terminal:create", "shell"], .terminalCreateProxy, [
+                "terminal": .string("shell"), "width": .unsignedInteger(80), "height": .unsignedInteger(24),
+            ]),
+            (["cn:terminal:create", "wide", "--width=132", "--height=43"], .terminalCreateProxy, [
+                "terminal": .string("wide"), "width": .unsignedInteger(132), "height": .unsignedInteger(43),
+            ]),
+            (["cn:terminal:wait-attached", "@terminal/shell"], .terminalWaitAttachedProxy, [
+                "terminal": .string("@terminal/shell"),
+            ]),
+            (["cn:terminal:close", "@terminal/shell"], .terminalCloseProxy, ["terminal": .string("@terminal/shell")]),
+        ]
+        for (arguments, method, parameters) in commands {
+            let invocation = try directInvocation(arguments)
+            XCTAssertEqual(invocation.method, method)
+            XCTAssertEqual(invocation.parameters, parameters)
+        }
+    }
+
+    func testParsesResourceCleanupExtensions() throws {
+        let commands: [([String], GhostboxDirectMethod, [String: GhostboxJSONValue])] = [
+            (["cn:dns:delete", "@dns/dev"], .dnsDelete, ["dns": .string("@dns/dev")]),
+            (["cn:process-config:delete", "@process-config/dev"], .processConfigDelete, [
+                "processConfig": .string("@process-config/dev"),
+            ]),
+            (["cn:network:delete", "@network/dev"], .networkDelete, ["network": .string("@network/dev")]),
+            (["cn:manager:close", "@manager/dev"], .managerClose, ["manager": .string("@manager/dev")]),
+        ]
+        for (arguments, method, parameters) in commands {
+            let invocation = try directInvocation(arguments)
+            XCTAssertEqual(invocation.method, method)
+            XCTAssertEqual(invocation.parameters, parameters)
+        }
+    }
+
+    func testParsesIOProxyAttachments() {
+        let commands: [([String], GhostboxDirectMethod, GhostboxIOStream)] = [
+            (["cn:reader-stream:attach", "@reader-stream/input"], .readerStreamAttachProxy, .input),
+            (["cn:writer:attach", "@writer/output"], .writerAttachProxy, .output),
+            (["cn:terminal:attach", "@terminal/shell"], .terminalAttachProxy, .terminal),
+        ]
+        for (arguments, method, stream) in commands {
+            guard case .success(let options) = parseArguments(arguments),
+                  case .attach(let invocation, let parsedStream) = options.action else {
+                return XCTFail("Expected attachment for \(arguments)")
+            }
+            XCTAssertEqual(invocation.method, method)
+            XCTAssertEqual(parsedStream, stream)
+        }
+
+        guard case .success(let options) = parseArguments([
+            "cn:terminal:attach", "@terminal/shell", "--resize-target", "@container/job",
+        ]), case .attach(let invocation, .terminal) = options.action else {
+            return XCTFail("Expected terminal attachment with resize target")
+        }
+        XCTAssertEqual(invocation.parameters, [
+            "terminal": .string("@terminal/shell"),
+            "resizeTarget": .string("@container/job"),
+        ])
+    }
+
+    func testRejectsMalformedIOProxyCommands() {
+        let commands = [
+            ["cn:reader-stream:create", "bad/name"],
+            ["cn:writer:attach", "@reader-stream/wrong"],
+            ["cn:terminal:create", "shell", "--width=0"],
+            ["cn:terminal:unknown", "@terminal/shell"],
+            ["cn:terminal:wait-attached", "@terminal/shell", "extra"],
+            ["cn:writer:attach", "@writer/output", "extra"],
+            ["cn:terminal:attach", "@terminal/shell", "--resize-target", "@writer/wrong"],
+        ]
+        for arguments in commands {
+            guard case .failure(.invalidDirect) = parseArguments(arguments) else {
+                return XCTFail("Expected rejection for \(arguments)")
+            }
+        }
+    }
+
+    func testIOProxyHelp() throws {
+        for resource in ["reader-stream", "writer", "terminal"] {
+            guard case .success(let help) = renderGhostboxHelp(["cn:\(resource):help"]) else {
+                return XCTFail("Expected help for \(resource)")
+            }
+            XCTAssertTrue(help.contains("ghostbox cn:\(resource):attach"))
+            XCTAssertTrue(help.contains("ghostbox cn:\(resource):close"))
+            if resource == "terminal" {
+                XCTAssertTrue(help.contains("ghostbox cn:terminal:wait-attached"))
+            }
+        }
+    }
+
+    func testParsesGuestShareMountAndCleanup() throws {
+        let create = try directInvocation([
+            "cn:mount:guest-share", "source",
+            "--source", "/Users/guest/project",
+            "--destination", "/workspace",
+            "--read-only=true",
+            "--cache-ttl=0",
+            "--option", "nodev",
+        ])
+        XCTAssertEqual(create.method, .mountGuestShare)
+        XCTAssertEqual(create.parameters, [
+            "mount": .string("source"),
+            "source": .string("/Users/guest/project"),
+            "destination": .string("/workspace"),
+            "readOnly": .boolean(true),
+            "cacheTTL": .unsignedInteger(0),
+            "option": .array([.string("nodev")]),
+            "runtimeOption": .array([]),
+        ])
+
+        let delete = try directInvocation(["cn:mount:delete", "@mount/source"])
+        XCTAssertEqual(delete.method, .mountDelete)
+        XCTAssertEqual(delete.parameters, ["mount": .string("@mount/source")])
+    }
+
+    func testParsesPersistentVolumeLifecycle() throws {
+        let create = try directInvocation(["cr:volume:create", "data", "--size", "67108864"])
+        XCTAssertEqual(create.method, .volumeCreate)
+        XCTAssertEqual(create.parameters, [
+            "volume": .string("data"),
+            "size": .unsignedInteger(67_108_864),
+        ])
+
+        XCTAssertEqual(try directInvocation(["cr:volume:list"]).method, .volumeList)
+        XCTAssertEqual(try directInvocation(["cr:volume:inspect", "@volume/data"]).method, .volumeInspect)
+
+        let mount = try directInvocation([
+            "cr:volume:mount", "@volume/data", "data-mount",
+            "--destination=/var/lib/data", "--read-only",
+        ])
+        XCTAssertEqual(mount.method, .volumeMount)
+        XCTAssertEqual(mount.parameters, [
+            "volume": .string("@volume/data"),
+            "mount": .string("data-mount"),
+            "destination": .string("/var/lib/data"),
+            "readOnly": .boolean(true),
+        ])
+
+        XCTAssertEqual(try directInvocation(["cr:volume:delete", "@volume/data"]).method, .volumeDelete)
+    }
+
+    func testRejectsMalformedPersistentVolumes() {
+        let commands = [
+            ["cr:volume:create", "../data"],
+            ["cr:volume:create", "data", "--size", "many"],
+            ["cr:volume:mount", "@volume/data", "data", "--destination", "/"],
+            ["cr:volume:inspect", "@volume/data", "extra"],
+        ]
+        for command in commands {
+            guard case .failure(.invalidDirect) = parseArguments(command) else {
+                return XCTFail("Expected rejection for \(command)")
+            }
+        }
+    }
+
+    func testCleanupParsingDoesNotClaimResourceNames() throws {
+        let create = try directInvocation([
+            "cn:mount:guest-share", "delete",
+            "--source", "/tmp",
+            "--destination", "/workspace",
+        ])
+        XCTAssertEqual(create.method, .mountGuestShare)
+        XCTAssertEqual(create.parameters["mount"], .string("delete"))
+    }
+
+    func testContainerForwardHelpDoesNotRequireReference() {
+        guard case .success(let help) = renderGhostboxHelp(["cn:container:forward"]) else {
+            return XCTFail("Expected container forward help")
+        }
+        XCTAssertTrue(help.contains("ghostbox cn:container:forward @container/NAME"))
+        XCTAssertTrue(help.contains("GhostVM guest extension"))
+    }
+
+    func testParsesContainerPortForwarding() {
+        guard case .success(let options) = parseArguments([
+            "cn:container:forward", "@container/web",
+            "-P", "8080:80/tcp",
+            "--publish=127.0.0.1:8443:443",
+        ]), case .forward(let container, let ports) = options.action else {
+            return XCTFail("Expected port forwarding")
+        }
+        XCTAssertEqual(container, "@container/web")
+        XCTAssertEqual(ports, [
+            PublishedPort(hostAddress: "127.0.0.1", hostPort: 8080, containerPort: 80),
+            PublishedPort(hostAddress: "127.0.0.1", hostPort: 8443, containerPort: 443),
+        ])
+    }
+
+    func testRejectsMalformedGuestShareAndPortForwarding() {
+        let commands = [
+            ["cn:mount:guest-share", "source", "--source", "relative", "--destination", "/workspace"],
+            ["cn:mount:guest-share", "source", "--source", "/tmp", "--destination", "/"],
+            ["cn:mount:guest-share", "source", "--source", "/tmp", "--destination", "/workspace", "--cache-ttl", "301"],
+            ["cn:container:forward", "@container/web", "-p", "8080:80/udp"],
+            ["cn:container:forward", "@container/web"],
+        ]
+        for command in commands {
+            guard case .failure(.invalidDirect) = parseArguments(command) else {
+                return XCTFail("Expected rejection for \(command)")
+            }
+        }
+    }
+
+    func testRejectsOldUnqualifiedCommandGrammar() {
+        let commands = [
+            ["dns", "create", "dev"],
+            ["dns", "@dns/dev", "validate"],
+            ["image-store", "@image-store/default", "pull", "alpine"],
+            ["container", "@container/web", "forward", "-p", "8080:80"],
+            ["volume", "@volume/data", "inspect"],
+        ]
+        for command in commands {
+            guard case .failure(.invalidDirect) = parseArguments(command) else {
+                return XCTFail("Expected old unqualified grammar rejection for \(command)")
+            }
+        }
+    }
+
+    private func directInvocation(_ arguments: [String]) throws -> GhostboxDirectInvocation {
+        switch parseArguments(arguments) {
+        case .success(let options):
+            guard case .direct(let invocation) = options.action else {
+                throw TestError.notDirect
+            }
+            return invocation
+        case .failure(let error):
+            throw error
+        }
+    }
+
+    private enum TestError: Error {
+        case notDirect
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/AttachmentTerminalTests.swift b/macOS/GhostTools/Tests/GhostboxTests/AttachmentTerminalTests.swift
new file mode 100644
index 0000000..0c51b52
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/AttachmentTerminalTests.swift
@@ -0,0 +1,45 @@
+@testable import ghostbox
+import XCTest
+
+final class AttachmentTerminalTests: XCTestCase {
+    func testSuspendResumeAndFinishRestoreTerminalMode() throws {
+        let master = posix_openpt(O_RDWR | O_NOCTTY)
+        XCTAssertGreaterThanOrEqual(master, 0)
+        guard master >= 0 else { return }
+        defer { Darwin.close(master) }
+        XCTAssertEqual(grantpt(master), 0)
+        XCTAssertEqual(unlockpt(master), 0)
+
+        let slave = Darwin.open(ptsname(master), O_RDWR | O_NOCTTY)
+        XCTAssertGreaterThanOrEqual(slave, 0)
+        guard slave >= 0 else { return }
+        defer { Darwin.close(slave) }
+
+        let terminal = try RawAttachmentTerminal(fd: slave)
+        try terminal.enterRawMode()
+        assertRaw(slave)
+
+        XCTAssertTrue(terminal.suspend())
+        assertCanonical(slave)
+
+        XCTAssertTrue(terminal.resume())
+        assertRaw(slave)
+
+        terminal.finish()
+        assertCanonical(slave)
+        XCTAssertFalse(terminal.resume())
+        assertCanonical(slave)
+    }
+
+    private func assertRaw(_ fd: Int32, file: StaticString = #filePath, line: UInt = #line) {
+        var attributes = termios()
+        XCTAssertEqual(tcgetattr(fd, &attributes), 0, file: file, line: line)
+        XCTAssertEqual(attributes.c_lflag & tcflag_t(ICANON | ECHO), 0, file: file, line: line)
+    }
+
+    private func assertCanonical(_ fd: Int32, file: StaticString = #filePath, line: UInt = #line) {
+        var attributes = termios()
+        XCTAssertEqual(tcgetattr(fd, &attributes), 0, file: file, line: line)
+        XCTAssertNotEqual(attributes.c_lflag & tcflag_t(ICANON), 0, file: file, line: line)
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/CommandCatalogTests.swift b/macOS/GhostTools/Tests/GhostboxTests/CommandCatalogTests.swift
new file mode 100644
index 0000000..c4311f3
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/CommandCatalogTests.swift
@@ -0,0 +1,306 @@
+@testable import ghostbox
+import XCTest
+
+final class CommandCatalogTests: XCTestCase {
+    func testGeneratedCatalogCountsAndUniqueness() {
+        XCTAssertEqual(ghostboxCommandCatalog.count, 282)
+        XCTAssertEqual(ghostboxCommandFixtures.count, 282)
+        XCTAssertEqual(ghostboxCommandCatalog.filter { $0.namespace == "cn" }.count, 260)
+        XCTAssertEqual(ghostboxCommandCatalog.filter { $0.namespace == "cr" }.count, 22)
+        XCTAssertEqual(ghostboxCommandResources.count, 39)
+        XCTAssertEqual(Set(ghostboxCommandResources).count, 39)
+
+        let qualifiedResources = Set(ghostboxCommandCatalog.map { "\($0.namespace):\($0.resource)" })
+        XCTAssertEqual(qualifiedResources.count, 39)
+        XCTAssertEqual(Set(ghostboxCommandCatalog.filter { $0.namespace == "cn" }.map(\.resource)).count, 35)
+        XCTAssertEqual(Set(ghostboxCommandCatalog.filter { $0.namespace == "cr" }.map(\.resource)).count, 4)
+
+        let commandIDs = ghostboxCommandCatalog.map(\.commandID)
+        let methodIDs = ghostboxCommandCatalog.map(\.methodID)
+        XCTAssertEqual(Set(commandIDs).count, commandIDs.count)
+        XCTAssertEqual(Set(methodIDs).count, methodIDs.count)
+        XCTAssertEqual(Set(ghostboxCommandFixtures.map(\.commandID)), Set(commandIDs))
+        XCTAssertEqual(Set(ghostboxCommandFixtures.map(\.methodID)), Set(methodIDs))
+        let signatures = ghostboxCommandCatalog.map {
+            "\($0.namespace)|\($0.resource)|\($0.shape.rawValue)|\($0.operation)"
+        }
+        XCTAssertEqual(Set(signatures).count, signatures.count)
+
+        let sourceKinds = Dictionary(grouping: ghostboxCommandCatalog, by: \.sourceKind).mapValues(\.count)
+        XCTAssertEqual(sourceKinds, ["direct": 277, "ghostvm-adapter": 5])
+    }
+
+    func testCatalogSourceMetadata() {
+        let adapterCommands = ghostboxCommandCatalog.filter { $0.sourceKind == "ghostvm-adapter" }
+        XCTAssertEqual(Set(adapterCommands.map(\.commandID)), [
+            "cr:volume:create",
+            "cr:volume:list",
+            "cr:volume:inspect",
+            "cr:volume:mount",
+            "cr:volume:delete",
+        ])
+        for command in adapterCommands {
+            XCTAssertEqual(command.namespace, "cr", command.commandID)
+            XCTAssertEqual(command.swiftModule, "GhostVMContainerRuntime", command.commandID)
+            XCTAssertNotNil(command.swiftSource, command.commandID)
+            XCTAssertTrue(command.appleDocumentationURL.hasPrefix("macOS/GhostVMContainerRuntime/"), command.commandID)
+        }
+    }
+
+    func testEveryMinimalFixtureAndFullAliasParseIdentically() throws {
+        let catalogByCommandID = Dictionary(uniqueKeysWithValues: ghostboxCommandCatalog.map { ($0.commandID, $0) })
+        for fixture in ghostboxCommandFixtures {
+            guard let command = catalogByCommandID[fixture.commandID] else {
+                return XCTFail("Missing catalog command \(fixture.commandID)")
+            }
+            XCTAssertEqual(fixture.argv.first, fixture.commandID)
+            XCTAssertEqual(command.methodID, fixture.methodID)
+
+            let canonical = try directInvocation(fixture.argv)
+            XCTAssertEqual(canonical.method.rawValue, fixture.methodID, fixture.argv.joined(separator: " "))
+
+            let expectedAlias = command.namespace == "cn"
+                ? command.commandID.replacingOccurrences(of: "cn:", with: "containerization:", options: .anchored)
+                : command.commandID.replacingOccurrences(of: "cr:", with: "container:", options: .anchored)
+            XCTAssertEqual(command.aliases, [expectedAlias], command.commandID)
+            for alias in command.aliases {
+                let aliasArguments = [alias] + fixture.argv.dropFirst()
+                let aliased = try directInvocation(aliasArguments)
+                XCTAssertEqual(aliased.method.rawValue, fixture.methodID, alias)
+                XCTAssertEqual(aliased.parameters, canonical.parameters, alias)
+            }
+        }
+    }
+
+    func testDefaultsUseCatalogTypes() throws {
+        let invocation = try directInvocation(["cn:vm-config:create", "dev"])
+        XCTAssertEqual(invocation.parameters["vmConfig"], .string("dev"))
+        XCTAssertEqual(invocation.parameters["cpus"], .integer(4))
+        XCTAssertEqual(invocation.parameters["memory"], .unsignedInteger(1_073_741_824))
+        XCTAssertEqual(invocation.parameters["nestedVirtualization"], .boolean(false))
+
+        let network = try directInvocation(["cn:network:vmnet-create", "dev"])
+        XCTAssertEqual(network.parameters["mode"], .string("shared"))
+    }
+
+    func testRepeatableOptionsAndOptionEquals() throws {
+        let invocation = try directInvocation([
+            "cn:dns:create", "dev",
+            "--nameserver=1.1.1.1",
+            "--nameserver", "8.8.8.8",
+            "--domain=example.test",
+        ])
+        XCTAssertEqual(invocation.parameters["nameservers"], .array([.string("1.1.1.1"), .string("8.8.8.8")]))
+        XCTAssertEqual(invocation.parameters["domain"], .string("example.test"))
+    }
+
+    func testDoubleDashPreservesVariadicPositionalStrings() throws {
+        let invocation = try directInvocation([
+            "cn:process-config:create", "shell", "--", "--login", "--noprofile",
+        ])
+        XCTAssertEqual(invocation.parameters["argument"], .array([.string("--login"), .string("--noprofile")]))
+    }
+
+    func testJSONArgumentsBecomeObjects() throws {
+        let invocation = try directInvocation([
+            "cn:process-config:from-image-config", "config", #"{"user":"root","env":["A=B"]}"#,
+        ])
+        XCTAssertEqual(invocation.parameters["imageConfig"], .object([
+            "user": .string("root"),
+            "env": .array([.string("A=B")]),
+        ]))
+    }
+
+    func testOCIPlatformExampleRemainsAString() throws {
+        let invocation = try directInvocation([
+            "cn:image:config", "@image/example", "linux/arm64",
+        ])
+        XCTAssertEqual(invocation.parameters["platform"], .string("linux/arm64"))
+    }
+
+    func testRejectsUnknownDuplicateAndMissingOptionValues() {
+        assertInvalid(["cn:dns:create", "dev", "--unknown", "value"])
+        assertInvalid(["cn:dns:create", "dev", "--domain", "one", "--domain=two"])
+        assertInvalid(["cn:dns:create", "dev", "--domain"])
+        assertInvalid(["cn:image-store:create", "store"])
+    }
+
+    func testRejectsMalformedNamesAndReferences() {
+        assertInvalid(["cn:dns:create", "bad/name"])
+        assertInvalid(["cn:dns:validate", "@hosts/dev"])
+        assertInvalid(["cn:dns:validate", "@dns/dev/extra"])
+        assertInvalid(["cn:dns:validate", "@dns/"])
+    }
+
+    func testRejectsNumericOverflowAndInvalidJSON() {
+        assertInvalid(["cn:container:resize", "@container/dev", "65536", "1"])
+        assertInvalid([
+            "cn:rlimit:create", "open-files",
+            "--kind", "@rlimit-kind/nofile",
+            "--hard", "18446744073709551616",
+            "--soft", "1",
+        ])
+        assertInvalid(["cn:process-config:from-image-config", "config", "[]"])
+    }
+
+    func testRootHelpContainsEverySignatureAndAppleDocumentationLink() {
+        XCTAssertTrue(ghostboxHelp.contains("Containerization (cn):"))
+        XCTAssertTrue(ghostboxHelp.contains("Container (cr):"))
+        let normalizedHelp = helpWithoutIndentation(ghostboxHelp)
+        for command in ghostboxCommandCatalog {
+            XCTAssertTrue(normalizedHelp.contains(command.signature), command.methodID)
+            XCTAssertTrue(ghostboxHelp.contains("Apple API: \(command.appleAPISymbol)"), command.methodID)
+            XCTAssertTrue(ghostboxHelp.contains("Apple docs: \(command.appleDocumentationURL)"), command.methodID)
+        }
+    }
+
+    func testNamespaceHelpFiltersCommandsAndResources() throws {
+        for (namespace, otherNamespace) in [("cn", "cr"), ("cr", "cn")] {
+            let help = try helpText([namespace])
+            let normalizedHelp = helpWithoutIndentation(help)
+            let commands = ghostboxCommandCatalog.filter { $0.namespace == namespace }
+            XCTAssertEqual(Set(commands.map(\.resource)).count, namespace == "cn" ? 35 : 4)
+            for command in commands {
+                XCTAssertTrue(normalizedHelp.contains(command.signature), command.commandID)
+            }
+            for command in ghostboxCommandCatalog where command.namespace == otherNamespace {
+                XCTAssertFalse(normalizedHelp.contains(command.signature), command.commandID)
+            }
+        }
+    }
+
+    func testEveryCommandHasDetailedScopedHelp() throws {
+        for command in ghostboxCommandCatalog {
+            let help = try helpText([command.commandID])
+            XCTAssertTrue(helpWithoutIndentation(help).contains(command.signature), command.methodID)
+            XCTAssertTrue(help.contains("Method: \(command.methodID)"), command.methodID)
+            XCTAssertTrue(help.contains("Apple API: \(command.appleAPISymbol)"), command.methodID)
+            XCTAssertTrue(help.contains("Apple docs: \(command.appleDocumentationURL)"), command.methodID)
+            XCTAssertTrue(help.contains("\nOutput:\n"), command.methodID)
+            XCTAssertTrue(help.contains("\nExample:\n  ghostbox "), command.methodID)
+
+            for alias in command.aliases {
+                XCTAssertEqual(try helpText([alias]), help, alias)
+            }
+        }
+    }
+
+    func testDetailedHelpExplainsArgumentsOptionsDefaultsAndOutput() throws {
+        let help = try helpText(["cn:image-store:pull"])
+        XCTAssertTrue(help.contains("@  required, receiver"))
+        XCTAssertTrue(help.contains("  required; string"))
+        XCTAssertTrue(help.contains("--insecure  optional, default: false; type: bool; true or false"))
+        XCTAssertTrue(help.contains("--max-concurrent-downloads  optional, default: 3; type: int"))
+        XCTAssertTrue(help.contains("reference:image: canonical host-owned image reference"))
+        XCTAssertTrue(help.contains("ghostbox cn:image-store:pull @image-store/example example"))
+    }
+
+    func testDefaultHostKernelExtensionHelp() throws {
+        XCTAssertTrue(ghostboxHelp.contains("ghostbox cn:kernel:install-recommended -> @kernel/default"))
+        XCTAssertTrue(ghostboxHelp.contains("ghostbox cn:kernel:default -> @kernel/default"))
+        let help = try helpText(["cn:kernel:default"])
+        XCTAssertTrue(help.contains("Method: kernel.default"))
+        XCTAssertTrue(help.contains("KernelService.getDefaultKernel"))
+
+        let installHelp = try helpText(["cn:kernel:install-recommended"])
+        XCTAssertTrue(installHelp.contains("Method: kernel.installRecommended"))
+        XCTAssertTrue(installHelp.contains("KernelService.installKernelFrom"))
+    }
+
+    func testCleanupExtensionHelp() throws {
+        for topic in [
+            ["cn:dns:delete"],
+            ["cn:process-config:delete"],
+            ["cn:network:delete"],
+            ["cn:manager:close"],
+        ] {
+            let help = try helpText(topic)
+            XCTAssertTrue(help.contains("GhostVM host extension"), topic.joined(separator: " "))
+        }
+    }
+
+    func testQualifiedResourceHelpContainsOnlyThatNamespaceAndResource() throws {
+        let help = try helpText(["cn:kernel-image:help"])
+        let normalizedHelp = helpWithoutIndentation(help)
+        for command in ghostboxCommandCatalog where command.namespace == "cn" && command.resource == "kernel-image" {
+            XCTAssertTrue(normalizedHelp.contains(command.signature), command.methodID)
+        }
+        XCTAssertFalse(help.contains("ghostbox cn:init-image:"))
+        XCTAssertFalse(help.contains("ghostbox cr:"))
+
+        let volumeHelp = try helpText(["cr:volume:help"])
+        XCTAssertTrue(volumeHelp.contains("ghostbox cr:volume:create"))
+        XCTAssertFalse(volumeHelp.contains("ghostbox cn:"))
+        XCTAssertFalse(volumeHelp.contains("cr:memory-size:"))
+    }
+
+    func testHelpRejectsUnknownTopics() {
+        guard case .failure(.invalidDirect(let resourceMessage)) = renderGhostboxHelp(["cn:missing:help"]) else {
+            return XCTFail("Expected unknown resource failure")
+        }
+        XCTAssertTrue(resourceMessage.contains("unknown resource"))
+
+        guard case .failure(.invalidDirect(let operationMessage)) = renderGhostboxHelp([
+            "cn:image-store:missing",
+        ]) else {
+            return XCTFail("Expected unknown operation failure")
+        }
+        XCTAssertTrue(operationMessage.contains("unknown help command"))
+    }
+
+    func testOldUnqualifiedCommandsAndHelpTopicsAreRejected() {
+        for command in [
+            ["dns", "create", "dev"],
+            ["image-store", "@image-store/example", "list"],
+            ["volume", "list"],
+        ] {
+            assertInvalid(command)
+        }
+        for topic in [
+            ["image-store"],
+            ["image-store", "pull"],
+            ["volume", "list"],
+        ] {
+            guard case .failure(.invalidDirect) = renderGhostboxHelp(topic) else {
+                return XCTFail("Expected old unqualified help rejection: \(topic)")
+            }
+        }
+    }
+
+    private func assertInvalid(_ arguments: [String], file: StaticString = #filePath, line: UInt = #line) {
+        guard case .failure(.invalidDirect) = parseArguments(arguments) else {
+            return XCTFail("Expected invalid direct invocation: \(arguments)", file: file, line: line)
+        }
+    }
+
+    private func directInvocation(_ arguments: [String]) throws -> GhostboxDirectInvocation {
+        switch parseArguments(arguments) {
+        case .success(let options):
+            guard case .direct(let invocation) = options.action else {
+                throw TestError.notDirect
+            }
+            return invocation
+        case .failure(let error):
+            throw error
+        }
+    }
+
+    private func helpText(_ topic: [String]) throws -> String {
+        switch renderGhostboxHelp(topic) {
+        case .success(let help):
+            return help
+        case .failure(let error):
+            throw error
+        }
+    }
+
+    private func helpWithoutIndentation(_ help: String) -> String {
+        help.split(separator: "\n", omittingEmptySubsequences: false).map {
+            String($0.drop(while: { $0 == " " }))
+        }.joined(separator: "\n")
+    }
+
+    private enum TestError: Error {
+        case notDirect
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/GhostboxForwardSignalProcessTests.swift b/macOS/GhostTools/Tests/GhostboxTests/GhostboxForwardSignalProcessTests.swift
new file mode 100644
index 0000000..dc9ab39
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/GhostboxForwardSignalProcessTests.swift
@@ -0,0 +1,143 @@
+@testable import ghostbox
+import Darwin
+import Foundation
+import XCTest
+
+final class GhostboxForwardSignalProcessTests: XCTestCase {
+    override class func setUp() {
+        super.setUp()
+        signal(SIGPIPE, SIG_IGN)
+    }
+
+    func testRepeatedSIGTERMCleansUpBeforeNormalExit() async throws {
+        #if !DEBUG
+        throw XCTSkip("process signal control is available only in debug builds")
+        #else
+        let executable = try ghostboxExecutableURL()
+        let publishedPort = try reserveEphemeralPort()
+        let process = Process()
+        let input = Pipe()
+        let output = Pipe()
+        let errors = Pipe()
+        process.executableURL = executable
+        process.arguments = [
+            "cn:container:forward",
+            "@container/signal-test",
+            "-p",
+            "127.0.0.1:\(publishedPort):1",
+        ]
+        var environment = ProcessInfo.processInfo.environment
+        environment["GHOSTBOX_FORWARD_SIGNAL_TEST_CONTROL"] = "1"
+        process.environment = environment
+        process.standardInput = input
+        process.standardOutput = output
+        process.standardError = errors
+        try process.run()
+        addTeardownBlock {
+            try? input.fileHandleForWriting.write(contentsOf: Data([0, 0]))
+            if process.isRunning { Darwin.kill(process.processIdentifier, SIGKILL) }
+            await Self.waitForExit(process)
+        }
+
+        XCTAssertEqual(try readLine(from: output.fileHandleForReading.fileDescriptor), "READY")
+        XCTAssertEqual(Darwin.kill(process.processIdentifier, SIGTERM), 0)
+        XCTAssertEqual(try readLine(from: output.fileHandleForReading.fileDescriptor), "CLEANUP")
+
+        XCTAssertEqual(Darwin.kill(process.processIdentifier, SIGTERM), 0)
+        try input.fileHandleForWriting.write(contentsOf: Data([0]))
+        XCTAssertEqual(try readLine(from: output.fileHandleForReading.fileDescriptor), "STOPPED")
+
+        let replacement = try makeListener(port: publishedPort)
+        Darwin.close(replacement)
+        try input.fileHandleForWriting.write(contentsOf: Data([0]))
+        await Self.waitForExit(process)
+
+        guard !process.isRunning else {
+            return XCTFail("ghostbox did not exit after forwarding cleanup")
+        }
+        XCTAssertEqual(process.terminationReason, .exit)
+        XCTAssertEqual(process.terminationStatus, 128 + SIGTERM)
+        XCTAssertEqual(errors.fileHandleForReading.readDataToEndOfFile(), Data())
+        #endif
+    }
+
+    private func ghostboxExecutableURL() throws -> URL {
+        if let override = ProcessInfo.processInfo.environment["GHOSTBOX_TEST_EXECUTABLE"] {
+            let url = URL(fileURLWithPath: override)
+            guard FileManager.default.isExecutableFile(atPath: url.path) else {
+                throw POSIXError(.ENOENT)
+            }
+            return url
+        }
+
+        let url = Bundle(for: Self.self).bundleURL
+            .deletingLastPathComponent()
+            .appendingPathComponent("ghostbox")
+        guard FileManager.default.isExecutableFile(atPath: url.path) else {
+            throw POSIXError(.ENOENT)
+        }
+        return url
+    }
+
+    private func readLine(from fd: Int32) throws -> String {
+        var data = Data()
+        while data.count < 64 {
+            var descriptor = pollfd(fd: fd, events: Int16(POLLIN | POLLHUP), revents: 0)
+            guard Darwin.poll(&descriptor, 1, 3_000) > 0 else {
+                throw POSIXError(.ETIMEDOUT)
+            }
+            var byte = UInt8(0)
+            let count = Darwin.read(fd, &byte, 1)
+            if count == 1 {
+                if byte == UInt8(ascii: "\n") { return String(decoding: data, as: UTF8.self) }
+                data.append(byte)
+            } else if count == 0 {
+                throw POSIXError(.ECONNRESET)
+            } else if errno != EINTR {
+                throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+            }
+        }
+        throw POSIXError(.EMSGSIZE)
+    }
+
+    private func reserveEphemeralPort() throws -> UInt16 {
+        let fd = try makeListener(port: 0)
+        defer { Darwin.close(fd) }
+        var address = sockaddr_in()
+        var length = socklen_t(MemoryLayout.size)
+        let result = withUnsafeMutablePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.getsockname(fd, $0, &length)
+            }
+        }
+        guard result == 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+        return UInt16(bigEndian: address.sin_port)
+    }
+
+    private func makeListener(port: UInt16) throws -> Int32 {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+        var address = sockaddr_in()
+        address.sin_len = UInt8(MemoryLayout.size)
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = port.bigEndian
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let bindResult = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.bind(fd, $0, socklen_t(MemoryLayout.size))
+            }
+        }
+        guard bindResult == 0, Darwin.listen(fd, 16) == 0 else {
+            let code = errno
+            Darwin.close(fd)
+            throw POSIXError(POSIXErrorCode(rawValue: code) ?? .EIO)
+        }
+        return fd
+    }
+
+    private static func waitForExit(_ process: Process) async {
+        for _ in 0..<300 where process.isRunning {
+            try? await Task.sleep(for: .milliseconds(10))
+        }
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/LineReaderTests.swift b/macOS/GhostTools/Tests/GhostboxTests/LineReaderTests.swift
new file mode 100644
index 0000000..b137846
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/LineReaderTests.swift
@@ -0,0 +1,174 @@
+@testable import ghostbox
+import XCTest
+
+final class LineReaderTests: XCTestCase {
+
+    private func makeSocketPair() throws -> (Int32, Int32) {
+        var fds = [Int32](repeating: -1, count: 2)
+        let rc = socketpair(AF_UNIX, SOCK_STREAM, 0, &fds)
+        XCTAssertEqual(rc, 0, "socketpair failed: errno=\(errno)")
+        guard rc == 0 else {
+            throw LineReaderError.ioError(errno: errno, op: "socketpair")
+        }
+        return (fds[0], fds[1])
+    }
+
+    func testReadSingleLine() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+
+        _ = writeAll(fd: fdA, Data("hello\n".utf8))
+        let reader = LineReader(fd: fdB)
+        let line = try reader.readLine()
+        XCTAssertEqual(line, Data("hello".utf8))
+    }
+
+    func testReadMultipleLines() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+
+        _ = writeAll(fd: fdA, Data("line1\nline2\nline3\n".utf8))
+        let reader = LineReader(fd: fdB)
+
+        XCTAssertEqual(try reader.readLine(), Data("line1".utf8))
+        XCTAssertEqual(try reader.readLine(), Data("line2".utf8))
+        XCTAssertEqual(try reader.readLine(), Data("line3".utf8))
+    }
+
+    func testReportsBufferedCompleteLine() throws {
+        let (writeFD, readFD) = try makeSocketPair()
+        defer {
+            Darwin.close(readFD)
+            Darwin.close(writeFD)
+        }
+        XCTAssertTrue(writeAll(fd: writeFD, Data("first\nsecond\n".utf8)))
+        let reader = LineReader(fd: readFD)
+        XCTAssertEqual(try reader.readLine(), Data("first".utf8))
+        XCTAssertTrue(reader.hasBufferedLine)
+        XCTAssertEqual(try reader.readLine(), Data("second".utf8))
+        XCTAssertFalse(reader.hasBufferedLine)
+    }
+
+    func testReadLineAcrossMultipleReads() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+
+        let reader = LineReader(fd: fdB)
+
+        _ = writeAll(fd: fdA, Data("partial".utf8))
+        // Give the kernel time to deliver
+        usleep(10_000)
+
+        // Write the rest with newline
+        _ = writeAll(fd: fdA, Data("-line\n".utf8))
+
+        let line = try reader.readLine()
+        XCTAssertEqual(line, Data("partial-line".utf8))
+    }
+
+    func testReadLineTrailingDataWithoutNewline() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+
+        _ = writeAll(fd: fdA, Data("first\ntrailing".utf8))
+        let reader = LineReader(fd: fdB)
+
+        XCTAssertEqual(try reader.readLine(), Data("first".utf8))
+
+        // Close write end → EOF on read end
+        Darwin.close(fdA)
+
+        let line = try reader.readLine()
+        XCTAssertEqual(line, Data("trailing".utf8))
+
+        // Should now get nil
+        let next = try reader.readLine()
+        XCTAssertNil(next)
+    }
+
+    func testReturnsNilOnCleanEOF() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        Darwin.close(fdA)
+
+        let reader = LineReader(fd: fdB)
+        let line = try reader.readLine()
+        XCTAssertNil(line)
+
+        Darwin.close(fdB)
+    }
+
+    func testThrowsOnLineTooLong() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+
+        // Write a long line without newline
+        let big = Data((0..<100).map { _ in UInt8(0x61) }) // 100 'a's
+        _ = writeAll(fd: fdA, big)
+
+        let reader = LineReader(fd: fdB, maxLineBytes: 10)
+
+        do {
+            _ = try reader.readLine()
+            XCTFail("Expected lineTooLong error")
+        } catch LineReaderError.lineTooLong(let max) {
+            XCTAssertEqual(max, 10)
+        } catch {
+            XCTFail("Expected lineTooLong, got \(error)")
+        }
+    }
+
+    func testAcceptsExactLimitFollowedByNewline() throws {
+        let (writeFD, readFD) = try makeSocketPair()
+        defer {
+            Darwin.close(writeFD)
+            Darwin.close(readFD)
+        }
+        XCTAssertTrue(writeAll(fd: writeFD, Data("0123456789\n".utf8)))
+        XCTAssertEqual(try LineReader(fd: readFD, maxLineBytes: 10).readLine(), Data("0123456789".utf8))
+    }
+
+    func testRejectsOverLimitLineWhenNewlineIsAlreadyBuffered() throws {
+        let (writeFD, readFD) = try makeSocketPair()
+        defer {
+            Darwin.close(writeFD)
+            Darwin.close(readFD)
+        }
+        XCTAssertTrue(writeAll(fd: writeFD, Data("01234567890\n".utf8)))
+        XCTAssertThrowsError(try LineReader(fd: readFD, maxLineBytes: 10).readLine()) { error in
+            guard case LineReaderError.lineTooLong(let max) = error else {
+                return XCTFail("Expected lineTooLong, got \(error)")
+            }
+            XCTAssertEqual(max, 10)
+        }
+    }
+
+    func testEmptyLine() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+
+        _ = writeAll(fd: fdA, Data("\n\n\n".utf8))
+        let reader = LineReader(fd: fdB)
+
+        XCTAssertEqual(try reader.readLine(), Data())
+        XCTAssertEqual(try reader.readLine(), Data())
+        XCTAssertEqual(try reader.readLine(), Data())
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/PortForwarderFableAdversarialTests.swift b/macOS/GhostTools/Tests/GhostboxTests/PortForwarderFableAdversarialTests.swift
new file mode 100644
index 0000000..15a2546
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/PortForwarderFableAdversarialTests.swift
@@ -0,0 +1,224 @@
+@testable import ghostbox
+import Darwin
+import Foundation
+import XCTest
+
+/// Adversarial probe for NetworkRelay's post-pump lifecycle: once one pump has
+/// completed, terminal state updates on the drained connection are the relay's
+/// only remaining death notice, and NetworkRelay.connectionStateChanged ignores
+/// them (`.failed`/`.waiting` are honored only while `!pumpsStarted`).
+final class PortForwarderFableAdversarialTests: XCTestCase {
+    /// The ghostbox CLI ignores SIGPIPE as its first act (GhostboxCLI.main); the
+    /// xctest host does not, and this probe writes into sockets the forwarder
+    /// may reset mid-transfer, which would otherwise kill the process.
+    override class func setUp() {
+        super.setUp()
+        signal(SIGPIPE, SIG_IGN)
+    }
+
+    /// After the client half-closes (SHUT_WR), the client→target pump delivers
+    /// isComplete, forwards the FIN, and finishes — leaving no outstanding
+    /// operation on the client connection. If the client then aborts (RST) while
+    /// the target stays open and silent — a curl/browser cancellation against a
+    /// long-poll or SSE backend — the only signal the relay gets is the client
+    /// NWConnection's terminal state update, which connectionStateChanged drops
+    /// because pumpsStarted is true. The relay and its container-side connection
+    /// then leak until the target volunteers data or the forwarder stops.
+    ///
+    /// Oracle: the relay's target NWConnection is the only socket in this
+    /// process whose *peer* is the target port (the test's client socket peers
+    /// with the published port; the target-side accepted socket peers with an
+    /// ephemeral port). A correct relay tears down after the client dies,
+    /// releasing that fd; the leak keeps it open indefinitely. Target-side
+    /// reads cannot distinguish these outcomes (they return EOF either way once
+    /// the forwarded FIN arrived), so the fd is the observable.
+    func testClientAbortAfterHalfCloseReleasesTargetConnection() async throws {
+        let (targetListener, targetPort) = try makeListener()
+        defer { Darwin.close(targetListener) }
+        let publishedPort = try reserveEphemeralPort()
+        let forwarder = try await PublishedPortForwarder(PublishedPort(
+            hostAddress: "127.0.0.1", hostPort: publishedPort, containerPort: targetPort
+        ))
+        addTeardownBlock { await forwarder.stop() }
+        forwarder.start(targetAddress: "127.0.0.1")
+
+        // Target: read the request and the forwarded FIN, then hold the
+        // connection open and silent (long-poll analogue) until released.
+        let handshake = expectation(description: "target saw request and forwarded FIN")
+        let targetExited = expectation(description: "target thread exited")
+        let release = DispatchSemaphore(value: 0)
+        let handshakeFailure = LockedBox(nil)
+        DispatchQueue.global(qos: .userInitiated).async {
+            defer { targetExited.fulfill() }
+            let connection = Darwin.accept(targetListener, nil, nil)
+            guard connection >= 0 else {
+                handshakeFailure.mutate { $0 = "target accept failed: errno \(errno)" }
+                handshake.fulfill()
+                return
+            }
+            defer { Darwin.close(connection) }
+            var timeout = timeval(tv_sec: 4, tv_usec: 0)
+            _ = setsockopt(connection, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout.size(ofValue: timeout)))
+            var buffer = [UInt8](repeating: 0, count: 16)
+            let requestCount = Darwin.read(connection, &buffer, 7)
+            let eofCount = requestCount == 7 ? Darwin.read(connection, &buffer, 1) : -1
+            if requestCount != 7 || eofCount != 0 {
+                handshakeFailure.mutate { $0 = "handshake failed: request \(requestCount), eof \(eofCount), errno \(errno)" }
+            }
+            handshake.fulfill()
+            release.wait()
+        }
+        defer { release.signal() }
+
+        let client = try connectClient(port: publishedPort)
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        XCTAssertEqual(Darwin.shutdown(client, SHUT_WR), 0)
+        await fulfillment(of: [handshake], timeout: 4)
+        if let failure = handshakeFailure.value {
+            Darwin.close(client)
+            return XCTFail(failure)
+        }
+
+        // Oracle precondition: with the relay established, its target-side
+        // socket must be visible. If Network.framework ever stops exposing
+        // per-connection fds this fails loudly instead of passing vacuously.
+        let relayVisible = try await poll(seconds: 2) { [self] in
+            !socketsPeered(toPort: targetPort).isEmpty
+        }
+        guard relayVisible else {
+            Darwin.close(client)
+            return XCTFail("oracle precondition failed: relay's target connection fd is not observable")
+        }
+
+        // Abort. The client→target pump already finished, so the client
+        // connection has no outstanding receive: the terminal state update is
+        // the only remaining death notice.
+        var abort = linger(l_onoff: 1, l_linger: 0)
+        _ = setsockopt(client, SOL_SOCKET, SO_LINGER, &abort, socklen_t(MemoryLayout.size(ofValue: abort)))
+        Darwin.close(client)
+
+        let released = try await poll(seconds: 3) { [self] in
+            socketsPeered(toPort: targetPort).isEmpty
+        }
+        XCTAssertTrue(
+            released,
+            "relay ignored the client's terminal failure after half-close: the container-side "
+                + "connection (peer port \(targetPort)) is still held 3s after the client aborted. "
+                + "NetworkRelay.connectionStateChanged only honors .failed/.waiting while "
+                + "!pumpsStarted, so a dead client leaks the relay — and pins the container-side "
+                + "server's connection — until the silent target sends or the forwarder stops."
+        )
+
+        release.signal()
+        await fulfillment(of: [targetExited], timeout: 2)
+    }
+
+    // MARK: - Helpers
+
+    /// All fds in this process holding an IPv4 socket whose *peer* is `port`.
+    private func socketsPeered(toPort port: UInt16) -> [Int32] {
+        var matches: [Int32] = []
+        for fd in 0...size)
+            let result = withUnsafeMutablePointer(to: &address) { pointer in
+                pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    Darwin.getpeername(fd, $0, &length)
+                }
+            }
+            guard result == 0, address.ss_family == sa_family_t(AF_INET) else { continue }
+            let peerPort = withUnsafePointer(to: &address) { pointer in
+                pointer.withMemoryRebound(to: sockaddr_in.self, capacity: 1) {
+                    UInt16(bigEndian: $0.pointee.sin_port)
+                }
+            }
+            if peerPort == port { matches.append(fd) }
+        }
+        return matches
+    }
+
+    private func poll(seconds: Double, _ condition: @escaping () -> Bool) async throws -> Bool {
+        var elapsed = 0.0
+        while elapsed < seconds {
+            if condition() { return true }
+            try await Task.sleep(for: .milliseconds(50))
+            elapsed += 0.05
+        }
+        return condition()
+    }
+
+    private func reserveEphemeralPort() throws -> UInt16 {
+        let (fd, port) = try makeListener()
+        Darwin.close(fd)
+        return port
+    }
+
+    private func makeListener() throws -> (Int32, UInt16) {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw PortForwardError.socket(operation: "socket", code: errno) }
+        var address = sockaddr_in()
+        address.sin_len = UInt8(MemoryLayout.size)
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = 0
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let bindResult = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.bind(fd, $0, socklen_t(MemoryLayout.size))
+            }
+        }
+        guard bindResult == 0, Darwin.listen(fd, 16) == 0 else {
+            let code = errno
+            Darwin.close(fd)
+            throw PortForwardError.socket(operation: "bind/listen", code: code)
+        }
+        var bound = sockaddr_in()
+        var length = socklen_t(MemoryLayout.size)
+        let lookup = withUnsafeMutablePointer(to: &bound) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.getsockname(fd, $0, &length)
+            }
+        }
+        guard lookup == 0 else {
+            let code = errno
+            Darwin.close(fd)
+            throw PortForwardError.socket(operation: "getsockname", code: code)
+        }
+        return (fd, UInt16(bigEndian: bound.sin_port))
+    }
+
+    private func connectClient(port: UInt16) throws -> Int32 {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw PortForwardError.socket(operation: "socket", code: errno) }
+        var timeout = timeval(tv_sec: 3, tv_usec: 0)
+        _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout.size(ofValue: timeout)))
+        var address = sockaddr_in()
+        address.sin_len = UInt8(MemoryLayout.size)
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = port.bigEndian
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let result = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.connect(fd, $0, socklen_t(MemoryLayout.size))
+            }
+        }
+        guard result == 0 else {
+            let code = errno
+            Darwin.close(fd)
+            throw PortForwardError.socket(operation: "connect", code: code)
+        }
+        return fd
+    }
+}
+
+private final class LockedBox: @unchecked Sendable {
+    private let lock = NSLock()
+    private var stored: Value
+
+    init(_ value: Value) { stored = value }
+
+    var value: Value { lock.withLock { stored } }
+
+    func mutate(_ transform: (inout Value) -> Void) {
+        lock.withLock { transform(&stored) }
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/PortForwarderNodeScenarioTests.swift b/macOS/GhostTools/Tests/GhostboxTests/PortForwarderNodeScenarioTests.swift
new file mode 100644
index 0000000..83f67d7
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/PortForwarderNodeScenarioTests.swift
@@ -0,0 +1,618 @@
+@testable import ghostbox
+import Darwin
+import Foundation
+import XCTest
+
+/// Regression tests for the field-reported ghostbox port-forwarding failures against
+/// Node.js servers (timeouts with zero bytes received, an orphaned forwarder holding
+/// the port, and pass-only-after-restart behavior). One test per diagnostic scenario:
+///
+///  1. Node raw close        → testNodeRawClose_ColdThenWarmSequentialConnectionsAllForwarded
+///  2. Node raw keep-alive   → testNodeRawKeepAlive_WarmSecondConnectionReceivesDataWithoutEOF
+///  3. Node HTTP close       → testNodeHTTPClose_ConnectAfterForwarderStopIsRefusedNotAcceptedWithZeroBytes
+///  4. Node HTTP keep-alive  → testNodeHTTPKeepAlive_SecondRequestOnReusedConnectionReceivesResponse
+///  5. Node delayed response → testNodeDelayed_ResponsesArriveWhileForwarderAcceptsConcurrentConnection
+///  6. Node 1 MiB response   → testNodeOneMiB_FullDeliveryUnderSlowClientReadBackpressure
+///  7. Node mounted source   → testNodeMountedSource_ServerScriptExecutedFromTemporaryDirectoryPath
+///  8. Node server-first     → testNodeServerFirst_ReplacementForwarderOnSamePortAfterStopDeliversBanner
+///  9. Node echo             → testNodeEcho_InterleavedRoundTripsOnLongLivedConnection
+/// 10. Node half-close       → testNodeHalfClose_ForwarderAcceptsNextConnectionAfterHalfClosedRelay
+/// 11. Keep-alive pool       → testNodeEcho_KeepAliveConnectionPoolBeyondThirtyTwoStillForwarded
+///
+/// Root-cause hypothesis these tests target: on macOS, shutdown(2) on a *listening*
+/// socket fails with ENOTCONN and does NOT wake a blocked accept(2) (verified
+/// empirically on this host; Linux differs). The former forwarder relied on exactly
+/// that shutdown once `start()` had run, so a stopped forwarder kept the
+/// host port bound: the next client connect() still succeeds and is then closed with
+/// zero bytes transferred, and a replacement forwarder cannot bind the port
+/// (EADDRINUSE even with SO_REUSEADDR, verified empirically). That reproduces the
+/// field pattern — stale/orphaned listener, "timeout, zero bytes", recovery only
+/// after the stale process was killed. Scenarios 3 and 8 assert the correct
+/// lifecycle behavior and are expected to FAIL on the defective implementation.
+/// The other scenarios pin down data-path dimensions (warm reuse, in-connection
+/// reuse, delayed output, backpressure, half-close, server-first ordering) that the
+/// field diagnostic could not separate from the lifecycle defect.
+///
+/// Review note on the pre-existing Node tests in PortForwarderTests.swift: they
+/// exercise single-connection happy paths through a freshly created forwarder, and
+/// their Node fixture calls `server.close()` as soon as the first socket closes, so
+/// by construction they cannot observe second-connection (warm) behavior, forwarder
+/// stop/restart, or stale-listener effects — the dimensions the diagnostic
+/// implicates. They are preserved unchanged; the fixture below serves an unlimited
+/// number of connections instead.
+final class PortForwarderNodeScenarioTests: XCTestCase {
+
+    // MARK: - Scenario 1: raw close
+
+    /// Field: "Node raw close: Timeout, HTTP 000". A single forwarder must keep
+    /// forwarding across repeated sequential connections — the cold (first) and
+    /// every warm (subsequent) connection must behave identically. Catches an
+    /// accept loop or relay-accounting failure after the first relay completes.
+    func testNodeRawClose_ColdThenWarmSequentialConnectionsAllForwarded() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "raw-close")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        for attempt in 1...4 {
+            let client = try connectClient(port: publishedPort)
+            defer { Darwin.close(client) }
+            XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)), "attempt \(attempt)")
+            XCTAssertEqual(
+                readToEOF(fd: client), Array("raw-ok".utf8),
+                "attempt \(attempt): connection \(attempt == 1 ? "cold" : "warm") received wrong or no data"
+            )
+        }
+    }
+
+    // MARK: - Scenario 2: raw keep-alive
+
+    /// Field: "Node raw keep-alive: Timeout, HTTP 000, but one cold run passed in
+    /// 5.139ms" — i.e. the first connection after a fresh start could pass while
+    /// later ones failed. The server writes its reply but never closes, so bytes
+    /// must be relayed as they arrive (no waiting for EOF), on the cold AND the
+    /// warm connection.
+    func testNodeRawKeepAlive_WarmSecondConnectionReceivesDataWithoutEOF() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "raw-keep-alive")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let cold = try connectClient(port: publishedPort)
+        XCTAssertTrue(writeBytes(fd: cold, Array("request".utf8)))
+        XCTAssertEqual(readExactly(fd: cold, count: 6), Array("raw-ok".utf8), "cold connection")
+        Darwin.close(cold)
+
+        let warm = try connectClient(port: publishedPort)
+        defer { Darwin.close(warm) }
+        XCTAssertTrue(writeBytes(fd: warm, Array("request".utf8)))
+        XCTAssertEqual(
+            readExactly(fd: warm, count: 6), Array("raw-ok".utf8),
+            "warm connection after a completed keep-alive relay received no data (field: only the cold run passed)"
+        )
+    }
+
+    // MARK: - Scenario 3: HTTP close
+
+    /// Field: "Node HTTP close: Timeout, zero bytes" together with "an orphaned
+    /// forwarding process was found and removed". After `stop()`, the published
+    /// port must actually be released: a new client connect must be REFUSED.
+    /// On the defective implementation, macOS shutdown(2) on the listening socket
+    /// is a silent ENOTCONN no-op, the listener stays bound, the client's connect
+    /// succeeds, and it then reads zero bytes — the exact field signature.
+    func testNodeHTTPClose_ConnectAfterForwarderStopIsRefusedNotAcceptedWithZeroBytes() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "http-close")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        defer { drainStaleListener(port: publishedPort) }
+
+        // Warm exchange first: forwarding works while the forwarder is running.
+        let client = try connectClient(port: publishedPort)
+        XCTAssertTrue(writeBytes(fd: client, Array(Self.httpRequest.utf8)))
+        XCTAssertEqual(readToEOF(fd: client), Array(Self.httpCloseResponse.utf8), "pre-stop request")
+        Darwin.close(client)
+
+        await forwarder.stop()
+
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        XCTAssertGreaterThanOrEqual(fd, 0)
+        defer { Darwin.close(fd) }
+        var timeout = timeval(tv_sec: 3, tv_usec: 0)
+        _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout.size(ofValue: timeout)))
+        var address = try loopbackAddress(port: publishedPort)
+        let result = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.connect(fd, $0, socklen_t(MemoryLayout.size))
+            }
+        }
+        if result == 0 {
+            var byte = UInt8(0)
+            let readCount = Darwin.read(fd, &byte, 1)
+            XCTFail(
+                "connect() to a stopped forwarder's port succeeded — the listener is still bound "
+                    + "(stale listener; shutdown(2) on a listening socket is a no-op on macOS). "
+                    + "Subsequent read returned \(readCount): the field 'timeout, zero bytes' failure."
+            )
+        } else {
+            XCTAssertEqual(errno, ECONNREFUSED, "expected connection refused after stop(), got errno \(errno)")
+        }
+    }
+
+    // MARK: - Scenario 4: HTTP keep-alive
+
+    /// Field: "Node HTTP keep-alive: Timeout, zero bytes". curl reuses one TCP
+    /// connection for keep-alive; the relay must keep both pumps alive after the
+    /// first response and deliver a second response on the SAME connection.
+    func testNodeHTTPKeepAlive_SecondRequestOnReusedConnectionReceivesResponse() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "http-keep-alive")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connectClient(port: publishedPort)
+        defer { Darwin.close(client) }
+        for request in 1...2 {
+            XCTAssertTrue(writeBytes(fd: client, Array(Self.httpRequest.utf8)), "request \(request)")
+            XCTAssertEqual(
+                readExactly(fd: client, count: Self.httpKeepAliveResponse.utf8.count),
+                Array(Self.httpKeepAliveResponse.utf8),
+                "request \(request) on the reused keep-alive connection got no/short response"
+            )
+        }
+    }
+
+    // MARK: - Scenario 5: delayed response
+
+    /// Field: "Node delayed response: Timeout, zero bytes". The reply arrives after
+    /// a quiet period. While one relay is idle waiting for the delayed bytes, the
+    /// forwarder must still accept and serve a second connection (the accept loop
+    /// must not be serialized behind an in-flight relay), and both delayed replies
+    /// must be delivered.
+    func testNodeDelayed_ResponsesArriveWhileForwarderAcceptsConcurrentConnection() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "delayed")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let first = try connectClient(port: publishedPort)
+        defer { Darwin.close(first) }
+        XCTAssertTrue(writeBytes(fd: first, Array("request".utf8)))
+
+        // Second connection is opened while the first is still awaiting its reply.
+        let second = try connectClient(port: publishedPort)
+        defer { Darwin.close(second) }
+        XCTAssertTrue(writeBytes(fd: second, Array("request".utf8)))
+
+        XCTAssertEqual(readToEOF(fd: second), Array("delayed".utf8), "second (concurrent) connection")
+        XCTAssertEqual(readToEOF(fd: first), Array("delayed".utf8), "first connection's delayed reply")
+    }
+
+    // MARK: - Scenario 6: 1 MiB response
+
+    /// Field: "Node 1 MiB response: Timeout, zero bytes". Node writes the full
+    /// 1 MiB immediately; the client is given a tiny receive buffer so the relay's
+    /// blocking writes experience sustained backpressure. Every byte must arrive
+    /// intact and the relay must not stall or truncate mid-transfer.
+    func testNodeOneMiB_FullDeliveryUnderSlowClientReadBackpressure() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "large")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connectClient(port: publishedPort) { fd in
+            var small: Int32 = 8 * 1024
+            _ = setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &small, socklen_t(MemoryLayout.size(ofValue: small)))
+        }
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+
+        // Give the server/relay a head start so the small receive window fills and
+        // the relay's write path actually blocks before we begin draining.
+        usleep(300_000)
+        let expected = 1024 * 1024
+        var received = 0
+        var mismatched = false
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        while true {
+            let count = Darwin.read(client, &buffer, buffer.count)
+            if count > 0 {
+                if !mismatched, buffer[.. {
+      socket.on("error", () => {});
+      if (mode === "server-first") {
+        socket.write("READY\n");
+        socket.once("data", () => socket.end("ACK"));
+        socket.on("end", () => socket.end());
+      } else if (mode === "raw-close") {
+        socket.once("data", () => socket.end("raw-ok"));
+      } else if (mode === "raw-keep-alive") {
+        socket.once("data", () => socket.write("raw-ok"));
+        socket.on("end", () => socket.end());
+      } else if (mode === "echo") {
+        socket.on("data", data => socket.write(data));
+        socket.on("end", () => socket.end());
+      } else if (mode === "half-close") {
+        socket.on("data", () => {});
+        socket.on("end", () => setTimeout(() => socket.end("after-eof"), 100));
+      } else if (mode === "delayed") {
+        socket.once("data", () => setTimeout(() => socket.end("delayed"), 400));
+      } else if (mode === "large") {
+        socket.once("data", () => socket.end(Buffer.alloc(1024 * 1024, 0x61)));
+      } else if (mode === "http-keep-alive") {
+        let pending = Buffer.alloc(0);
+        socket.on("data", data => {
+          pending = Buffer.concat([pending, data]);
+          let index;
+          while ((index = pending.indexOf("\r\n\r\n")) !== -1) {
+            pending = pending.subarray(index + 4);
+            socket.write("HTTP/1.1 200 OK\r\nContent-Length: 12\r\nConnection: keep-alive\r\n\r\nnode-http-ok");
+          }
+        });
+        socket.on("end", () => socket.end());
+      } else if (mode === "http-close") {
+        let pending = Buffer.alloc(0);
+        socket.on("data", data => {
+          pending = Buffer.concat([pending, data]);
+          if (pending.indexOf("\r\n\r\n") !== -1) {
+            socket.end("HTTP/1.1 200 OK\r\nContent-Length: 12\r\nConnection: close\r\n\r\nnode-http-ok");
+          }
+        });
+      }
+    });
+    server.listen(0, "127.0.0.1", () => console.log(server.address().port));
+    """#
+
+    private func launchNodeServer(mode: String, scriptFile: URL? = nil) throws -> (Process, UInt16) {
+        let process = Process()
+        let output = Pipe()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+        if let scriptFile {
+            process.arguments = ["node", scriptFile.path, mode]
+            process.currentDirectoryURL = FileManager.default.temporaryDirectory
+        } else {
+            process.arguments = ["node", "-e", Self.nodeServerScript, mode]
+        }
+        process.standardOutput = output
+        process.standardError = Pipe()
+        try process.run()
+
+        var portLine = Data()
+        while portLine.count < 16 {
+            let byte = output.fileHandleForReading.readData(ofLength: 1)
+            guard !byte.isEmpty else { break }
+            if byte.first == UInt8(ascii: "\n") { break }
+            portLine.append(byte)
+        }
+        guard let port = UInt16(String(decoding: portLine, as: UTF8.self)) else {
+            process.waitUntilExit()
+            throw XCTSkip("Node.js is unavailable or failed to start the test server")
+        }
+        return (process, port)
+    }
+
+    private func stopNodeAfterTest(_ process: Process) {
+        addTeardownBlock { await Self.stopNodeServer(process) }
+    }
+
+    private static func stopNodeServer(_ process: Process) async {
+        guard process.isRunning else { return }
+        process.terminate()
+        for _ in 0..<100 where process.isRunning {
+            try? await Task.sleep(for: .milliseconds(10))
+        }
+        if process.isRunning { Darwin.kill(process.processIdentifier, SIGKILL) }
+        while process.isRunning {
+            try? await Task.sleep(for: .milliseconds(10))
+        }
+    }
+
+    // MARK: - Forwarder helpers
+
+    private func startForwarder(targetPort: UInt16) async throws -> (PublishedPortForwarder, UInt16) {
+        let publishedPort = try reserveEphemeralPort()
+        let forwarder = try await PublishedPortForwarder(PublishedPort(
+            hostAddress: "127.0.0.1",
+            hostPort: publishedPort,
+            containerPort: targetPort
+        ))
+        forwarder.start(targetAddress: "127.0.0.1")
+        return (forwarder, publishedPort)
+    }
+
+    private func stopAfterTest(_ forwarder: PublishedPortForwarder) {
+        addTeardownBlock { await forwarder.stop() }
+    }
+
+    /// On the defective implementation a stopped forwarder's accept loop stays
+    /// blocked and its port stays bound until one more connection is sacrificed.
+    /// Poke the port once so a defective run does not leak blocked threads and
+    /// bound ports into later tests. On a correct implementation the connect is
+    /// simply refused and this is a no-op.
+    private func drainStaleListener(port: UInt16) {
+        guard let fd = try? connectClient(port: port, recvTimeoutSeconds: 1) else { return }
+        Darwin.close(fd)
+    }
+
+    private func reserveEphemeralPort() throws -> UInt16 {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw PortForwardError.socket(operation: "socket", code: errno) }
+        defer { Darwin.close(fd) }
+        var address = try loopbackAddress(port: 0)
+        let bindResult = withUnsafePointer(to: &address) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.bind(fd, $0, socklen_t(MemoryLayout.size))
+            }
+        }
+        guard bindResult == 0 else { throw PortForwardError.socket(operation: "bind", code: errno) }
+        var bound = sockaddr_in()
+        var length = socklen_t(MemoryLayout.size)
+        let lookup = withUnsafeMutablePointer(to: &bound) { pointer in
+            pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.getsockname(fd, $0, &length)
+            }
+        }
+        guard lookup == 0 else { throw PortForwardError.socket(operation: "getsockname", code: errno) }
+        return UInt16(bigEndian: bound.sin_port)
+    }
+
+    // MARK: - Socket helpers
+
+    private func loopbackAddress(port: UInt16) throws -> sockaddr_in {
+        var address = sockaddr_in()
+        address.sin_len = UInt8(MemoryLayout.size)
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = port.bigEndian
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        return address
+    }
+
+    private func connectClient(
+        port: UInt16,
+        recvTimeoutSeconds: Int = 3,
+        configure: (Int32) -> Void = { _ in }
+    ) throws -> Int32 {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw PortForwardError.socket(operation: "socket", code: errno) }
+        do {
+            var timeout = timeval(tv_sec: recvTimeoutSeconds, tv_usec: 0)
+            _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout.size(ofValue: timeout)))
+            configure(fd)
+            var address = try loopbackAddress(port: port)
+            let result = withUnsafePointer(to: &address) { pointer in
+                pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    Darwin.connect(fd, $0, socklen_t(MemoryLayout.size))
+                }
+            }
+            guard result == 0 else { throw PortForwardError.socket(operation: "connect", code: errno) }
+            return fd
+        } catch {
+            Darwin.close(fd)
+            throw error
+        }
+    }
+
+    private func readExactly(fd: Int32, count: Int) -> [UInt8]? {
+        var result = [UInt8]()
+        result.reserveCapacity(count)
+        var buffer = [UInt8](repeating: 0, count: min(32 * 1024, count))
+        while result.count < count {
+            let readCount = Darwin.read(fd, &buffer, min(buffer.count, count - result.count))
+            if readCount > 0 {
+                result.append(contentsOf: buffer[.. [UInt8] {
+        var result = [UInt8]()
+        var buffer = [UInt8](repeating: 0, count: 32 * 1024)
+        while true {
+            let readCount = Darwin.read(fd, &buffer, buffer.count)
+            if readCount > 0 {
+                result.append(contentsOf: buffer[..= 0 else { served.fulfill(); return }
+            defer { Darwin.close(connection) }
+            var request = [UInt8](repeating: 0, count: 4)
+            if Darwin.read(connection, &request, request.count) == 4,
+               Data(request) == Data("ping".utf8) {
+                _ = writeBytes(fd: connection, Array("pong".utf8))
+            }
+            served.fulfill()
+        }
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("ping".utf8)))
+        var response = [UInt8](repeating: 0, count: 4)
+        XCTAssertEqual(Darwin.read(client, &response, response.count), 4)
+        XCTAssertEqual(Data(response), Data("pong".utf8))
+        await fulfillment(of: [served], timeout: 2)
+    }
+
+    func testPropagatesClientHalfCloseWithoutDroppingResponse() async throws {
+        let (targetListener, targetPort) = try makeListener(port: 0)
+        defer { Darwin.close(targetListener) }
+
+        let (reservation, publishedPort) = try makeListener(port: 0)
+        Darwin.close(reservation)
+        let forwarder = try await PublishedPortForwarder(PublishedPort(
+            hostAddress: "127.0.0.1",
+            hostPort: publishedPort,
+            containerPort: targetPort
+        ))
+        stopAfterTest(forwarder)
+        forwarder.start(targetAddress: "127.0.0.1")
+
+        let served = expectation(description: "target observed EOF and replied")
+        DispatchQueue.global(qos: .userInitiated).async {
+            let connection = Darwin.accept(targetListener, nil, nil)
+            guard connection >= 0 else { served.fulfill(); return }
+            defer { Darwin.close(connection) }
+            var request = [UInt8](repeating: 0, count: 4)
+            var trailing = UInt8(0)
+            if Darwin.read(connection, &request, request.count) == 4,
+               Data(request) == Data("ping".utf8),
+               Darwin.read(connection, &trailing, 1) == 0 {
+                _ = writeBytes(fd: connection, Array("pong".utf8))
+            }
+            served.fulfill()
+        }
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("ping".utf8)))
+        XCTAssertEqual(Darwin.shutdown(client, SHUT_WR), 0)
+        var response = [UInt8](repeating: 0, count: 4)
+        XCTAssertEqual(Darwin.read(client, &response, response.count), 4)
+        XCTAssertEqual(Data(response), Data("pong".utf8))
+        await fulfillment(of: [served], timeout: 2)
+    }
+
+    func testStopClosesActiveRelay() async throws {
+        let (targetListener, targetPort) = try makeListener(port: 0)
+        defer { Darwin.close(targetListener) }
+
+        let (reservation, publishedPort) = try makeListener(port: 0)
+        Darwin.close(reservation)
+        let forwarder = try await PublishedPortForwarder(PublishedPort(
+            hostAddress: "127.0.0.1",
+            hostPort: publishedPort,
+            containerPort: targetPort
+        ))
+        forwarder.start(targetAddress: "127.0.0.1")
+
+        let accepted = expectation(description: "target accepted relay")
+        let closed = expectation(description: "target observed relay shutdown")
+        DispatchQueue.global(qos: .userInitiated).async {
+            let connection = Darwin.accept(targetListener, nil, nil)
+            guard connection >= 0 else {
+                accepted.fulfill()
+                closed.fulfill()
+                return
+            }
+            accepted.fulfill()
+            var byte = UInt8(0)
+            _ = Darwin.read(connection, &byte, 1)
+            Darwin.close(connection)
+            closed.fulfill()
+        }
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        await fulfillment(of: [accepted], timeout: 2)
+        await forwarder.stop()
+        var byte = UInt8(0)
+        XCTAssertEqual(Darwin.read(client, &byte, 1), 0)
+        await fulfillment(of: [closed], timeout: 2)
+    }
+
+    func testTargetResetClosesIdleClient() async throws {
+        let (targetListener, targetPort) = try makeListener(port: 0)
+        defer { Darwin.close(targetListener) }
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let targetReset = expectation(description: "target reset established relay")
+        DispatchQueue.global(qos: .userInitiated).async {
+            let connection = Darwin.accept(targetListener, nil, nil)
+            guard connection >= 0 else { targetReset.fulfill(); return }
+            var reset = linger(l_onoff: 1, l_linger: 0)
+            _ = setsockopt(
+                connection,
+                SOL_SOCKET,
+                SO_LINGER,
+                &reset,
+                socklen_t(MemoryLayout.size(ofValue: reset))
+            )
+            Darwin.close(connection)
+            targetReset.fulfill()
+        }
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        await fulfillment(of: [targetReset], timeout: 2)
+
+        var byte = UInt8(0)
+        let count = Darwin.read(client, &byte, 1)
+        XCTAssertTrue(count == 0 || (count < 0 && errno == ECONNRESET), "idle client was not closed after target reset")
+    }
+
+    func testForwardsNodeRawCloseResponse() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "raw-close")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        XCTAssertEqual(readToEOF(fd: client), Array("raw-ok".utf8))
+    }
+
+    func testForwardsNodeRawKeepAliveResponseWithoutWaitingForEOF() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "raw-keep-alive")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        XCTAssertEqual(Self.readExactly(fd: client, count: 6), Array("raw-ok".utf8))
+    }
+
+    func testForwardsNodeHTTPResponsesForCloseAndKeepAlive() async throws {
+        for mode in ["http-close", "http-keep-alive"] {
+            let (node, targetPort) = try launchNodeServer(mode: mode)
+            let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+            let client = try connect(port: publishedPort)
+            let request = "GET / HTTP/1.1\r\nHost: localhost\r\nConnection: \(mode == "http-close" ? "close" : "keep-alive")\r\n\r\n"
+
+            XCTAssertTrue(writeBytes(fd: client, Array(request.utf8)), mode)
+            let response = readUntil(fd: client, contains: Array("node-http".utf8))
+            XCTAssertNotNil(response, mode)
+            if let response {
+                XCTAssertTrue(String(decoding: response, as: UTF8.self).hasPrefix("HTTP/1.1 200 OK\r\n"), mode)
+            }
+
+            Darwin.close(client)
+            await forwarder.stop()
+            await Self.stopNodeServer(node)
+        }
+    }
+
+    func testForwardsDelayedNodeResponse() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "delayed")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        XCTAssertEqual(Self.readExactly(fd: client, count: 7), Array("delayed".utf8))
+    }
+
+    func testForwardsOneMiBNodeResponse() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "large")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        let response = Self.readExactly(fd: client, count: 1024 * 1024)
+        XCTAssertEqual(response?.count, 1024 * 1024)
+        XCTAssertTrue(response?.allSatisfy { $0 == 0x61 } == true)
+    }
+
+    func testForwardsNodeServerFirstProtocol() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "server-first")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertEqual(Self.readExactly(fd: client, count: 6), Array("READY\n".utf8))
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        XCTAssertEqual(Self.readExactly(fd: client, count: 3), Array("ACK".utf8))
+    }
+
+    func testForwardsNodeEchoWhileConnectionRemainsOpen() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "echo")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        let payload = (0..<(256 * 1024)).map { UInt8(truncatingIfNeeded: $0) }
+        XCTAssertTrue(writeBytes(fd: client, payload))
+        XCTAssertEqual(Self.readExactly(fd: client, count: payload.count), payload)
+    }
+
+    func testForwardsConcurrentBidirectionalTraffic() async throws {
+        let (targetListener, targetPort) = try makeListener(port: 0)
+        defer { Darwin.close(targetListener) }
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+        let clientPayload = (0..<(1024 * 1024)).map { UInt8(truncatingIfNeeded: $0) }
+        let targetPayload = (0..<(1024 * 1024)).map { UInt8(truncatingIfNeeded: $0 &* 31) }
+
+        let targetFinished = expectation(description: "target completed simultaneous transfer")
+        DispatchQueue.global(qos: .userInitiated).async {
+            let connection = Darwin.accept(targetListener, nil, nil)
+            guard connection >= 0 else { targetFinished.fulfill(); return }
+            defer { Darwin.close(connection) }
+            DispatchQueue.global(qos: .userInitiated).async {
+                _ = writeBytes(fd: connection, targetPayload)
+                _ = Darwin.shutdown(connection, SHUT_WR)
+            }
+            let received = Self.readExactly(fd: connection, count: clientPayload.count)
+            XCTAssertEqual(received, clientPayload)
+            targetFinished.fulfill()
+        }
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        let clientWrite = expectation(description: "client completed simultaneous write")
+        DispatchQueue.global(qos: .userInitiated).async {
+            XCTAssertTrue(writeBytes(fd: client, clientPayload))
+            _ = Darwin.shutdown(client, SHUT_WR)
+            clientWrite.fulfill()
+        }
+        XCTAssertEqual(Self.readExactly(fd: client, count: targetPayload.count), targetPayload)
+        await fulfillment(of: [clientWrite, targetFinished], timeout: 5)
+    }
+
+    func testForwardsNodeResponseAfterClientHalfClose() async throws {
+        let (node, targetPort) = try launchNodeServer(mode: "half-close")
+        stopNodeAfterTest(node)
+        let (forwarder, publishedPort) = try await startForwarder(targetPort: targetPort)
+        stopAfterTest(forwarder)
+
+        let client = try connect(port: publishedPort)
+        defer { Darwin.close(client) }
+        XCTAssertTrue(writeBytes(fd: client, Array("request".utf8)))
+        XCTAssertEqual(Darwin.shutdown(client, SHUT_WR), 0)
+        XCTAssertEqual(readToEOF(fd: client), Array("after-eof".utf8))
+    }
+
+    private func startForwarder(targetPort: UInt16) async throws -> (PublishedPortForwarder, UInt16) {
+        let (reservation, publishedPort) = try makeListener(port: 0)
+        Darwin.close(reservation)
+        let forwarder = try await PublishedPortForwarder(PublishedPort(
+            hostAddress: "127.0.0.1",
+            hostPort: publishedPort,
+            containerPort: targetPort
+        ))
+        forwarder.start(targetAddress: "127.0.0.1")
+        return (forwarder, publishedPort)
+    }
+
+    private func stopAfterTest(_ forwarder: PublishedPortForwarder) {
+        addTeardownBlock { await forwarder.stop() }
+    }
+
+    private func launchNodeServer(mode: String) throws -> (Process, UInt16) {
+        let process = Process()
+        let output = Pipe()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+        process.arguments = ["node", "-e", Self.nodeServerScript, mode]
+        process.standardOutput = output
+        process.standardError = Pipe()
+        try process.run()
+
+        var portLine = Data()
+        while portLine.count < 16 {
+            let byte = output.fileHandleForReading.readData(ofLength: 1)
+            guard !byte.isEmpty else { break }
+            if byte.first == UInt8(ascii: "\n") { break }
+            portLine.append(byte)
+        }
+        guard let port = UInt16(String(decoding: portLine, as: UTF8.self)) else {
+            process.waitUntilExit()
+            throw XCTSkip("Node.js is unavailable or failed to start the test server")
+        }
+        return (process, port)
+    }
+
+    private func stopNodeAfterTest(_ process: Process) {
+        addTeardownBlock { await Self.stopNodeServer(process) }
+    }
+
+    private static func stopNodeServer(_ process: Process) async {
+        guard process.isRunning else { return }
+        process.terminate()
+        for _ in 0..<100 where process.isRunning {
+            try? await Task.sleep(for: .milliseconds(10))
+        }
+        if process.isRunning { Darwin.kill(process.processIdentifier, SIGKILL) }
+        while process.isRunning {
+            try? await Task.sleep(for: .milliseconds(10))
+        }
+    }
+
+    private static func readExactly(fd: Int32, count: Int) -> [UInt8]? {
+        var result = [UInt8]()
+        result.reserveCapacity(count)
+        var buffer = [UInt8](repeating: 0, count: min(32 * 1024, count))
+        while result.count < count {
+            let readCount = Darwin.read(fd, &buffer, min(buffer.count, count - result.count))
+            if readCount > 0 {
+                result.append(contentsOf: buffer[.. [UInt8] {
+        var result = [UInt8]()
+        var buffer = [UInt8](repeating: 0, count: 32 * 1024)
+        while true {
+            let readCount = Darwin.read(fd, &buffer, buffer.count)
+            if readCount > 0 {
+                result.append(contentsOf: buffer[.. [UInt8]? {
+        var result = [UInt8]()
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        while result.count < 1024 * 1024 {
+            let readCount = Darwin.read(fd, &buffer, buffer.count)
+            if readCount > 0 {
+                result.append(contentsOf: buffer[.. {
+      if (mode === "server-first") {
+        socket.write("READY\n");
+        socket.once("data", () => socket.end("ACK"));
+      } else if (mode === "raw-close") {
+        socket.once("data", () => socket.end("raw-ok"));
+      } else if (mode === "raw-keep-alive") {
+        socket.once("data", () => socket.write("raw-ok"));
+      } else if (mode === "echo") {
+        socket.on("data", data => socket.write(data));
+      } else if (mode === "half-close") {
+        socket.on("data", () => {});
+        socket.on("end", () => setTimeout(() => socket.end("after-eof"), 150));
+      } else if (mode === "delayed") {
+        socket.once("data", () => setTimeout(() => socket.end("delayed"), 150));
+      } else if (mode === "large") {
+        socket.once("data", () => socket.end(Buffer.alloc(1024 * 1024, 0x61)));
+      } else {
+        let requestChunks = [];
+        socket.on("data", data => {
+          requestChunks.push(data);
+          if (!Buffer.concat(requestChunks).includes("\r\n\r\n")) return;
+          const keepAlive = mode === "http-keep-alive";
+          const response = "HTTP/1.1 200 OK\r\nContent-Length: 9\r\nConnection: " +
+            (keepAlive ? "keep-alive" : "close") + "\r\n\r\nnode-http";
+          if (keepAlive) socket.write(response); else socket.end(response);
+        });
+      }
+      socket.on("close", () => server.close());
+    });
+    server.listen(0, "127.0.0.1", () => console.log(server.address().port));
+    """#
+
+    private func makeListener(port: UInt16) throws -> (Int32, UInt16) {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw PortForwardError.socket(operation: "socket", code: errno) }
+        do {
+            var address = sockaddr_in()
+            address.sin_len = UInt8(MemoryLayout.size)
+            address.sin_family = sa_family_t(AF_INET)
+            address.sin_port = port.bigEndian
+            address.sin_addr.s_addr = inet_addr("127.0.0.1")
+            let result = withUnsafePointer(to: &address) { pointer in
+                pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    Darwin.bind(fd, $0, socklen_t(MemoryLayout.size))
+                }
+            }
+            guard result == 0, Darwin.listen(fd, 4) == 0 else {
+                throw PortForwardError.socket(operation: "bind/listen", code: errno)
+            }
+            var bound = sockaddr_in()
+            var length = socklen_t(MemoryLayout.size)
+            let lookup = withUnsafeMutablePointer(to: &bound) { pointer in
+                pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    Darwin.getsockname(fd, $0, &length)
+                }
+            }
+            guard lookup == 0 else { throw PortForwardError.socket(operation: "getsockname", code: errno) }
+            return (fd, UInt16(bigEndian: bound.sin_port))
+        } catch {
+            Darwin.close(fd)
+            throw error
+        }
+    }
+
+    private func connect(port: UInt16) throws -> Int32 {
+        let fd = Darwin.socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { throw PortForwardError.socket(operation: "socket", code: errno) }
+        do {
+            var timeout = timeval(tv_sec: 2, tv_usec: 0)
+            _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout.size(ofValue: timeout)))
+            var address = sockaddr_in()
+            address.sin_len = UInt8(MemoryLayout.size)
+            address.sin_family = sa_family_t(AF_INET)
+            address.sin_port = port.bigEndian
+            address.sin_addr.s_addr = inet_addr("127.0.0.1")
+            let result = withUnsafePointer(to: &address) { pointer in
+                pointer.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    Darwin.connect(fd, $0, socklen_t(MemoryLayout.size))
+                }
+            }
+            guard result == 0 else { throw PortForwardError.socket(operation: "connect", code: errno) }
+            return fd
+        } catch {
+            Darwin.close(fd)
+            throw error
+        }
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/ProtocolTests.swift b/macOS/GhostTools/Tests/GhostboxTests/ProtocolTests.swift
new file mode 100644
index 0000000..8e28a7b
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/ProtocolTests.swift
@@ -0,0 +1,174 @@
+@testable import ghostbox
+import XCTest
+
+final class ProtocolTests: XCTestCase {
+    func testIOFramesRoundTrip() throws {
+        let frames: [GhostboxIOFrame] = [
+            .data(Data([0x00, 0x0A, 0xFF]), stream: .input),
+            .data(Data("output".utf8), stream: .output),
+            .data(Data("tty".utf8), stream: .terminal),
+            .eof(.input),
+            .eof(.output),
+            .eof(.terminal),
+            .resize(columns: 132, rows: 43),
+            .error("broken stream"),
+        ]
+        for frame in frames {
+            var line = try frame.encodeLine()
+            XCTAssertEqual(line.removeLast(), 0x0A)
+            XCTAssertEqual(try GhostboxIOFrame.decode(line: line), frame)
+        }
+    }
+
+    func testIOFramesRejectMalformedAndOversizedValues() {
+        let invalid = [
+            GhostboxIOFrame(type: .data, stream: .input, data: Data()),
+            GhostboxIOFrame(type: .eof),
+            GhostboxIOFrame(type: .resize, stream: .terminal, columns: 0, rows: 24),
+            GhostboxIOFrame(type: .error, message: ""),
+            GhostboxIOFrame(type: .data, stream: .input, data: Data(repeating: 0, count: kMaxIOFrameDataBytes + 1)),
+        ]
+        for frame in invalid {
+            XCTAssertThrowsError(try frame.encodeLine())
+        }
+        XCTAssertThrowsError(try GhostboxIOFrame.decode(line: Data("not-json".utf8)))
+    }
+    func testDirectRequestUsesMethodParametersAndCurrentEnvelope() throws {
+        let request = GhostboxDirectRequest(
+            id: "request-1",
+            invocation: .init(
+                method: .dnsCreate,
+                parameters: ["name": .string("dev"), "nameservers": .array([.string("1.1.1.1")])]
+            )
+        )
+        let line = try encodeDirectRequestLine(request)
+        let object = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(line.dropLast())) as? [String: Any])
+        XCTAssertEqual(Set(object.keys), Set(["version", "operation", "id", "method", "parameters"]))
+        XCTAssertEqual(object["version"] as? Int, kProtocolVersion)
+        XCTAssertEqual(object["operation"] as? String, "direct")
+        XCTAssertEqual(object["id"] as? String, "request-1")
+        XCTAssertEqual(object["method"] as? String, "dns.create")
+        XCTAssertEqual((object["parameters"] as? [String: Any])?["name"] as? String, "dev")
+    }
+
+    func testDirectMethodAllowsUnknownRawValues() throws {
+        let method = GhostboxDirectMethod(rawValue: "snapshot.prepare")
+        XCTAssertEqual(try JSONDecoder().decode(GhostboxDirectMethod.self, from: JSONEncoder().encode(method)), method)
+    }
+
+    func testJSONValueRoundTripsEverySupportedShape() throws {
+        let value = GhostboxJSONValue.object([
+            "null": .null,
+            "bool": .boolean(true),
+            "string": .string("value"),
+            "integer": .integer(-42),
+            "unsigned": .unsignedInteger(UInt64.max),
+            "array": .array([.integer(1), .object(["nested": .string("yes")])]),
+        ])
+        let data = try JSONEncoder().encode(value)
+        XCTAssertEqual(try JSONDecoder().decode(GhostboxJSONValue.self, from: data), value)
+        XCTAssertTrue(String(decoding: data, as: UTF8.self).contains(String(UInt64.max)))
+    }
+
+    func testJSONValueRejectsMalformedUnsignedIntegerTags() {
+        let malformed = [
+            #"{"$uint64":18446744073709551615}"#,
+            #"{"$uint64":"18446744073709551616"}"#,
+            #"{"$uint64":"01"}"#,
+            #"{"$uint64":"1","extra":true}"#,
+        ]
+        for json in malformed {
+            XCTAssertThrowsError(try JSONDecoder().decode(GhostboxJSONValue.self, from: Data(json.utf8)), json)
+        }
+    }
+
+    func testDirectResultRoundTripsUInt64MaxWithoutPrecisionLoss() throws {
+        let value = GhostboxDirectValue.unsignedInteger(UInt64.max)
+        XCTAssertEqual(try JSONDecoder().decode(GhostboxDirectValue.self, from: JSONEncoder().encode(value)), value)
+    }
+
+    func testMaximumByteResponseFitsResponseLineLimit() throws {
+        let value = GhostboxDirectValue.bytes(Data(repeating: 0xA5, count: kMaxDirectBytePayloadBytes))
+        let response = GhostboxDirectResponse(
+            version: kProtocolVersion,
+            id: "request-1",
+            result: value,
+            error: nil
+        )
+        let encoded = try JSONEncoder().encode(response)
+        XCTAssertLessThanOrEqual(encoded.count, kMaxDirectResponseLineBytes)
+        XCTAssertEqual(try JSONDecoder().decode(GhostboxDirectResponse.self, from: encoded), response)
+
+        XCTAssertThrowsError(try JSONEncoder().encode(
+            GhostboxDirectValue.bytes(Data(repeating: 0, count: kMaxDirectBytePayloadBytes + 1))
+        ))
+    }
+
+    func testMaximumIOFrameFitsFrameLineLimit() throws {
+        let frame = GhostboxIOFrame.data(Data(repeating: 0x5A, count: kMaxIOFrameDataBytes), stream: .terminal)
+        let line = try frame.encodeLine()
+        XCTAssertLessThanOrEqual(line.count - 1, kMaxIOFrameLineBytes)
+        XCTAssertEqual(try GhostboxIOFrame.decode(line: Data(line.dropLast())), frame)
+    }
+
+    func testDirectResultRejectsMalformedTaggedValues() {
+        let malformed = [
+            #"{"type":"void","value":null}"#,
+            #"{"type":"string"}"#,
+            #"{"type":"unsigned_integer","value":18446744073709551615}"#,
+            #"{"type":"unsigned_integer","value":"01"}"#,
+            #"{"type":"null","extra":true}"#,
+        ]
+        for json in malformed {
+            XCTAssertThrowsError(try JSONDecoder().decode(GhostboxDirectValue.self, from: Data(json.utf8)), json)
+        }
+    }
+
+    func testDirectResponseRequiresMatchingRequestID() throws {
+        let response = GhostboxDirectResponse(
+            version: kProtocolVersion,
+            id: "other-request",
+            result: .reference("@dns/dev"),
+            error: nil
+        )
+        guard case .protocolError = decodeDirectResponse(try JSONEncoder().encode(response), requestID: "request-1") else {
+            return XCTFail("Expected response ID mismatch to fail")
+        }
+    }
+
+    func testDirectResponseDecodesStableError() throws {
+        let response = GhostboxDirectResponse(
+            version: kProtocolVersion,
+            id: "request-1",
+            result: nil,
+            error: .init(code: "not_found", message: "DNS object missing")
+        )
+        XCTAssertEqual(
+            decodeDirectResponse(try JSONEncoder().encode(response), requestID: "request-1"),
+            .error(code: "not_found", message: "DNS object missing")
+        )
+    }
+
+    func testDirectValueRenderingIsJSONCompatibleAndReferencesAreClear() throws {
+        XCTAssertEqual(String(decoding: try renderDirectValue(.reference("@dns/dev")), as: UTF8.self), "@dns/dev\n")
+        XCTAssertEqual(String(decoding: try renderDirectValue(.string("example.test")), as: UTF8.self), "\"example.test\"\n")
+        XCTAssertEqual(String(decoding: try renderDirectValue(.strings(["a", "b"])), as: UTF8.self), "[\"a\",\"b\"]\n")
+        XCTAssertEqual(String(decoding: try renderDirectValue(.object(["items": .array([.integer(1), .boolean(true)])])), as: UTF8.self), "{\"items\":[1,true]}\n")
+        XCTAssertEqual(String(decoding: try renderDirectValue(.unsignedInteger(UInt64.max)), as: UTF8.self), "\(UInt64.max)\n")
+        XCTAssertEqual(try renderDirectValue(.void), Data())
+        XCTAssertEqual(String(decoding: try renderDirectValue(.null), as: UTF8.self), "null\n")
+    }
+
+    func testDirectRequestRejectsPayloadAboveBridgeLimit() {
+        let request = GhostboxDirectRequest(
+            id: "request-large",
+            invocation: .init(
+                method: .dnsCreate,
+                parameters: ["name": .string("large"), "domain": .string(String(repeating: "x", count: 64 * 1024))]
+            )
+        )
+        XCTAssertThrowsError(try encodeDirectRequestLine(request)) { error in
+            XCTAssertEqual(error as? GhostboxDirectProtocolError, .requestTooLarge)
+        }
+    }
+}
diff --git a/macOS/GhostTools/Tests/GhostboxTests/VsockDialTests.swift b/macOS/GhostTools/Tests/GhostboxTests/VsockDialTests.swift
new file mode 100644
index 0000000..9ad5077
--- /dev/null
+++ b/macOS/GhostTools/Tests/GhostboxTests/VsockDialTests.swift
@@ -0,0 +1,69 @@
+@testable import ghostbox
+import XCTest
+
+final class VsockDialTests: XCTestCase {
+
+    /// The Darwin sockaddr_vm layout must be exactly 12 bytes (no padding/zero
+    /// field): svm_len(1) + svm_family(1) + svm_reserved1(2) + svm_port(4) + svm_cid(4).
+    func testSockaddrVmSizeIs12Bytes() {
+        XCTAssertEqual(MemoryLayout.size, 12)
+        XCTAssertEqual(MemoryLayout.stride, 12)
+    }
+
+    func testSockaddrVmFieldsInitialized() {
+        let addr = ghostbox.sockaddr_vm(port: 5004, cid: 2)
+        XCTAssertEqual(addr.svm_len, 12)
+        XCTAssertEqual(addr.svm_family, UInt8(ghostbox.AF_VSOCK))
+        XCTAssertEqual(addr.svm_reserved1, 0)
+        XCTAssertEqual(addr.svm_port, 5004)
+        XCTAssertEqual(addr.svm_cid, 2)
+    }
+
+    // MARK: - writeAll / writeBytes / write helpers return Bool
+
+    private func makeSocketPair() throws -> (Int32, Int32) {
+        var fds = [Int32](repeating: -1, count: 2)
+        let rc = socketpair(AF_UNIX, SOCK_STREAM, 0, &fds)
+        XCTAssertEqual(rc, 0, "socketpair failed: errno=\(errno)")
+        guard rc == 0 else {
+            throw LineReaderError.ioError(errno: errno, op: "socketpair")
+        }
+        return (fds[0], fds[1])
+    }
+
+    func testWriteAllReturnsTrueOnSuccess() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+        XCTAssertTrue(writeAll(fd: fdA, Data("hello".utf8)))
+    }
+
+    func testWriteAllReturnsTrueForEmptyData() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+        XCTAssertTrue(writeAll(fd: fdA, Data()))
+    }
+
+    func testWriteAllReturnsFalseOnClosedFd() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        Darwin.close(fdA)
+        Darwin.close(fdB)
+        // Writing to a closed fd fails.
+        XCTAssertFalse(writeAll(fd: fdA, Data("nope".utf8)))
+    }
+
+    func testWriteBytesReturnsBool() throws {
+        let (fdA, fdB) = try makeSocketPair()
+        defer {
+            Darwin.close(fdA)
+            Darwin.close(fdB)
+        }
+        XCTAssertTrue(writeBytes(fd: fdA, [0x68, 0x69]))
+    }
+
+}
diff --git a/macOS/GhostVM/Services/ContainerBridgeService.swift b/macOS/GhostVM/Services/ContainerBridgeService.swift
new file mode 100644
index 0000000..68775f9
--- /dev/null
+++ b/macOS/GhostVM/Services/ContainerBridgeService.swift
@@ -0,0 +1,628 @@
+import Foundation
+import GhostFileKit
+import Virtualization
+import GhostVMKit
+
+/// Host-side listener for guest-initiated container control connections.
+///
+/// Registered on the VM's VZVirtioSocketDevice. When a guest process connects to
+/// ContainerBridgeConstants.port, the service accepts the connection, reads one
+/// direct API request, submits it to the runtime XPC service, and returns one
+/// direct API response. One request is accepted per connection.
+final class ContainerBridgeService: @unchecked Sendable {
+    static let maxConcurrentConnections = 32
+
+    /// SO_RCVTIMEO/SO_SNDTIMEO applied to accepted sockets: bounds slowloris
+    /// request reads and frame writes blocked on a stalled guest. This is not
+    /// a cap on total container runtime.
+    private static let socketIOTimeoutSeconds = 15
+
+    private let vm: VZVirtualMachine
+    private let vmQueue: DispatchQueue
+    private let vmHash: String
+    private let port: UInt32
+    private let fileSystemBridge: GuestFileSystemBridgeService?
+    private let sharedNetwork: SharedVmnetNetwork
+    private let runtimeClient: ContainerRuntimeXPCClient
+
+    private struct PreparedGuestMount: Sendable {
+        let volume: GuestVolumeMount
+        let guestPath: String
+    }
+
+    private let mountLock = NSLock()
+    private var guestMounts = GuestMountRegistry()
+
+    private let stateLock = NSLock()
+    private var listener: VZVirtioSocketListener?
+    private var listenerDelegate: BridgeListenerDelegate?
+    private var isRunning = false
+    private var activeCount = 0
+    private var connections: [UUID: VZVirtioSocketConnection] = [:]
+    private var writers: [UUID: VSockFrameWriter] = [:]
+    private var tasks: [UUID: Task] = [:]
+
+    /// - Parameters:
+    ///   - vm: The running virtual machine (accessed only on `vmQueue`).
+    ///   - vmQueue: The serial queue the VZVirtualMachine was created with.
+    ///   - vmHash: Stable per-VM identifier used in generated container names.
+    ///   - volumeRootURL: Trusted per-VM storage for persistent container volumes.
+    ///   - port: Vsock port to listen on.
+    init(
+        vm: VZVirtualMachine,
+        vmQueue: DispatchQueue,
+        vmHash: String,
+        sharedNetwork: SharedVmnetNetwork,
+        volumeRootURL: URL,
+        imageRootURL: URL,
+        fileSystemBridge: GuestFileSystemBridgeService? = nil,
+        port: UInt32 = ContainerBridgeConstants.port
+    ) {
+        self.vm = vm
+        self.vmQueue = vmQueue
+        self.vmHash = vmHash
+        self.port = port
+        self.fileSystemBridge = fileSystemBridge
+        self.sharedNetwork = sharedNetwork
+        self.runtimeClient = ContainerRuntimeXPCClient(
+            sharedNetwork: sharedNetwork,
+            volumeRootURL: volumeRootURL,
+            imageRootURL: imageRootURL
+        )
+    }
+
+    /// Registers the vsock listener on vmQueue. Safe to call once per VM run.
+    public func start() {
+        stateLock.lock()
+        guard !isRunning else {
+            stateLock.unlock()
+            return
+        }
+        isRunning = true
+        let delegate = BridgeListenerDelegate { [weak self] connection in
+            self?.accept(connection) ?? false
+        }
+        let listener = VZVirtioSocketListener()
+        listener.delegate = delegate
+        // VZ does not retain the listener and its delegate property is weak,
+        // so the service must retain both for the listener to keep firing.
+        self.listener = listener
+        self.listenerDelegate = delegate
+        stateLock.unlock()
+
+        vmQueue.async {
+            guard let socketDevice = self.vm.socketDevices.first as? VZVirtioSocketDevice else {
+                NSLog("ContainerBridge: no VZVirtioSocketDevice on this VM; listener not registered")
+                return
+            }
+            socketDevice.setSocketListener(listener, forPort: self.port)
+            NSLog("ContainerBridge: listening for guest container requests on vsock port %u (vm=%@)", self.port, self.vmHash)
+        }
+    }
+
+    /// Idempotent: atomically flips to not-running and snapshots all
+    /// per-connection state under one lock, then unwinds in order — cancel
+    /// tasks, shut down frame writers (wakes blocked reads/writes), request
+    /// runner termination. Each connection task closes its VZ connection only
+    /// after its blocking input relay has observed shutdown and returned.
+    public func stop() {
+        stateLock.lock()
+        guard isRunning else {
+            stateLock.unlock()
+            return
+        }
+        isRunning = false
+        let registeredListener = self.listener
+        let registeredDelegate = self.listenerDelegate
+        self.listener = nil
+        self.listenerDelegate = nil
+        let openTasks = Array(tasks.values)
+        let openWriters = Array(writers.values)
+        let openConnections = connections
+        stateLock.unlock()
+
+        vmQueue.async {
+            if let socketDevice = self.vm.socketDevices.first as? VZVirtioSocketDevice {
+                socketDevice.removeSocketListener(forPort: self.port)
+            }
+            // VZ does not retain the listener and its delegate is weak. Keep both
+            // alive until deregistration has completed on the VM queue.
+            withExtendedLifetime((registeredListener, registeredDelegate)) {}
+        }
+        for task in openTasks {
+            task.cancel()
+        }
+        for writer in openWriters {
+            writer.shutdown()
+        }
+        runtimeClient.invalidate()
+        let mounted = mountLock.withLock {
+            guestMounts.removeAll()
+        }
+        for record in mounted.reversed() {
+            record.volume.unmount()
+        }
+        if let fileSystemBridge, !mounted.isEmpty {
+            Task { @MainActor in
+                for record in mounted {
+                    fileSystemBridge.unregisterExport(id: record.volume.exportID)
+                }
+            }
+        }
+        NSLog("ContainerBridge: stopped (cancelled %d task(s), signalled %d connection(s))", openTasks.count, openConnections.count)
+    }
+
+    /// Closes the connection exactly once: the `connections` dictionary entry
+    /// is the ownership token — whichever path (stop or per-connection
+    /// cleanup) removes it under the lock performs the close.
+    private func closeConnectionOnce(id: UUID, connection: VZVirtioSocketConnection) {
+        stateLock.lock()
+        let owned = connections.removeValue(forKey: id) != nil
+        stateLock.unlock()
+        if owned {
+            connection.close()
+        }
+    }
+
+    // MARK: - Accept (called on vmQueue by VZ; must never block)
+
+    private func accept(_ connection: VZVirtioSocketConnection) -> Bool {
+        Self.applySocketTimeouts(fd: connection.fileDescriptor)
+        let writer = VSockFrameWriter(fd: connection.fileDescriptor)
+
+        stateLock.lock()
+        guard isRunning, activeCount < Self.maxConcurrentConnections else {
+            let running = isRunning
+            let count = activeCount
+            stateLock.unlock()
+            NSLog("ContainerBridge: rejecting connection (isRunning=%d, active=%d/%d)", running ? 1 : 0, count, Self.maxConcurrentConnections)
+            return false
+        }
+        activeCount += 1
+        let id = UUID()
+        connections[id] = connection
+        writers[id] = writer
+        // The task handle is registered before the lock is released and
+        // per-connection cleanup also takes stateLock, so an early-finishing
+        // task can never leave a stale entry behind.
+        let task = Task.detached { [self] in
+            await handleConnection(id: id, connection: connection, writer: writer)
+        }
+        tasks[id] = task
+        stateLock.unlock()
+
+        // The task retains `connection` for its whole IO lifetime; dropping it
+        // would close the fd (VZ owns the descriptor).
+        return true
+    }
+
+    /// Bounds request reads and blocked frame writes without capping total
+    /// container runtime. Failure to set an option is logged, never fatal.
+    private static func applySocketTimeouts(fd: Int32) {
+        var timeout = timeval(tv_sec: socketIOTimeoutSeconds, tv_usec: 0)
+        let length = socklen_t(MemoryLayout.size)
+        if setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, length) != 0 {
+            NSLog("ContainerBridge: setsockopt(SO_RCVTIMEO) failed (errno=%d); continuing without a receive timeout", errno)
+        }
+        if setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO, &timeout, length) != 0 {
+            NSLog("ContainerBridge: setsockopt(SO_SNDTIMEO) failed (errno=%d); continuing without a send timeout", errno)
+        }
+    }
+
+    // MARK: - Connection handling
+
+    private func handleConnection(id: UUID, connection: VZVirtioSocketConnection, writer: VSockFrameWriter) async {
+        // ownsFD: false — the VZ connection is the sole fd owner, so the
+        // channel is never closed (that would double-close the descriptor).
+        let channel = BlockingVSockChannel(fd: connection.fileDescriptor, ownsFD: false)
+        defer {
+            // Shut down raw writers BEFORE VZ closes the fd, so a stale write
+            // can never land on a reused descriptor.
+            writer.shutdown()
+            closeConnectionOnce(id: id, connection: connection)
+            stateLock.lock()
+            writers[id] = nil
+            tasks[id] = nil
+            activeCount -= 1
+            stateLock.unlock()
+        }
+
+        var requestID = "unknown"
+        do {
+            let line = try await readRequestLine(channel: channel)
+            requestID = (try? JSONDecoder().decode(GhostboxDirectRequestEnvelope.self, from: line).id) ?? requestID
+            let request = try GhostboxDirectRequest.decode(line: line)
+            requestID = request.id
+            guard request.version == ContainerBridgeConstants.protocolVersion,
+                  request.operation == "direct",
+                  !request.id.isEmpty else {
+                throw ContainerProtocolError.malformedRequest(
+                    "direct operations require protocol version \(ContainerBridgeConstants.protocolVersion) and a nonempty ID"
+                )
+            }
+            guard GuestMountAccessPolicy.allowsGuestInvocation(request.method.rawValue) else {
+                throw ContainerProtocolError.malformedRequest(
+                    "method '\(request.method.rawValue)' cannot access outer-host paths; use mount guest-share"
+                )
+            }
+
+            if Self.isAttachmentMethod(request.method) {
+                Self.clearSocketTimeouts(fd: connection.fileDescriptor)
+                try await runtimeClient.attach(payload: line, descriptor: connection.fileDescriptor)
+                writer.shutdown()
+                return
+            }
+
+            let response: GhostboxDirectResponse
+            if request.method == .mountGuestShare {
+                response = try await createGuestMount(request)
+            } else if request.method == .mountDelete {
+                response = try await invokeRuntime(request)
+                if response.error == nil {
+                    try await releaseGuestMount(parameters: request.parameters)
+                }
+            } else if request.method.rawValue == "mount.source",
+                      let source = guestMountSource(parameters: request.parameters) {
+                response = .success(id: request.id, value: .string(source))
+            } else {
+                response = try await invokeRuntime(request, payload: line)
+            }
+            guard response.version == request.version, response.id == request.id else {
+                throw ContainerProtocolError.malformedRequest("runtime returned a mismatched direct response")
+            }
+            try writer.writeFrameOrThrow(response.encodeLine())
+        } catch {
+            let message = (error as? LocalizedError)?.errorDescription ?? String(describing: error)
+            if let frame = try? GhostboxDirectResponse.failure(
+                id: requestID,
+                code: .invalidArgument,
+                message: message
+            ).encodeLine() {
+                _ = writer.writeFrame(frame)
+            }
+            NSLog("ContainerBridge: direct request failed: %@", message)
+        }
+        writer.shutdown()
+    }
+
+    // MARK: - Guest volume bridge
+
+    /// Adapts the proven `-V` pipeline to a persistent Ghostbox mount object:
+    /// guest path -> private GhostFile share -> outer-host FSKit mount -> Mount.share.
+    private func createGuestMount(_ request: GhostboxDirectRequest) async throws -> GhostboxDirectResponse {
+        let allowed: Set = [
+            "mount", "source", "destination", "readOnly", "cacheTTL", "option", "runtimeOption",
+        ]
+        guard request.parameters.keys.allSatisfy(allowed.contains) else {
+            throw ContainerProtocolError.malformedRequest("mount.guestShare contains an unknown parameter")
+        }
+        let name = try Self.stringParameter("mount", in: request.parameters)
+        guard Self.isReferenceComponent(name) else {
+            throw ContainerProtocolError.malformedRequest("mount name is invalid")
+        }
+        let reference = "@mount/\(name)"
+        let guestPath = try Self.stringParameter("source", in: request.parameters)
+        guard guestPath.hasPrefix("/"), !guestPath.contains("\0"), guestPath.utf8.count <= 4096 else {
+            throw ContainerProtocolError.malformedRequest("guest mount source must be an absolute path of at most 4096 bytes")
+        }
+        let destination = try Self.stringParameter("destination", in: request.parameters)
+        guard Self.isContainerMountPath(destination), destination.utf8.count <= 4096 else {
+            throw ContainerProtocolError.malformedRequest("guest mount destination must be an absolute non-root container path")
+        }
+        let readOnly = try Self.boolParameter("readOnly", in: request.parameters) ?? false
+        let cacheTTL = try Self.unsignedIntegerParameter("cacheTTL", in: request.parameters)
+            ?? GhostFileProtocol.defaultCacheTTLSeconds
+        guard cacheTTL <= GhostFileProtocol.maximumCacheTTLSeconds else {
+            throw ContainerProtocolError.malformedRequest(
+                "guest mount cache TTL must be at most \(GhostFileProtocol.maximumCacheTTLSeconds) seconds"
+            )
+        }
+        var options = try Self.stringArrayParameter("option", in: request.parameters) ?? []
+        let runtimeOptions = try Self.stringArrayParameter("runtimeOption", in: request.parameters) ?? []
+        if readOnly, !options.contains("ro") { options.append("ro") }
+        guard let fileSystemBridge else { throw GuestVolumeMount.MountError.bridgeUnavailable }
+
+        let reserved = mountLock.withLock { guestMounts.reserve(reference) }
+        guard reserved else {
+            throw ContainerProtocolError.malformedRequest("object '\(reference)' already exists")
+        }
+        defer {
+            mountLock.withLock { guestMounts.abandon(reference) }
+        }
+
+        let registered = try await fileSystemBridge.registerExport(
+            guestPath: guestPath,
+            readOnly: readOnly,
+            cacheTTLSeconds: cacheTTL
+        )
+        let volume: GuestVolumeMount
+        do {
+            volume = try GuestVolumeMount.mount(
+                registeredExport: registered,
+                destination: destination,
+                readOnly: readOnly
+            )
+        } catch {
+            await fileSystemBridge.unregisterExport(id: registered.id)
+            throw error
+        }
+
+        let runtimeRequest = GhostboxDirectRequest(
+            id: request.id,
+            method: GhostboxDirectMethod(rawValue: "mount.share"),
+            parameters: [
+                "mount": .string(name),
+                "source": .string(volume.mountPoint.path),
+                "destination": .string(destination),
+                "option": .array(options.map(GhostboxJSONValue.string)),
+                "runtimeOption": .array(runtimeOptions.map(GhostboxJSONValue.string)),
+            ]
+        )
+        let response: GhostboxDirectResponse
+        do {
+            response = try await invokeRuntime(runtimeRequest)
+        } catch {
+            volume.unmount()
+            await fileSystemBridge.unregisterExport(id: registered.id)
+            throw error
+        }
+        guard response.error == nil else {
+            volume.unmount()
+            await fileSystemBridge.unregisterExport(id: registered.id)
+            return response
+        }
+
+        switch registerPreparedGuestMount(
+            PreparedGuestMount(volume: volume, guestPath: guestPath),
+            reference: reference
+        ) {
+        case .registered:
+            return response
+        case .deleted:
+            volume.unmount()
+            await fileSystemBridge.unregisterExport(id: registered.id)
+            return .failure(
+                id: request.id,
+                code: .cancelled,
+                message: "mount '\(reference)' was deleted while creation was in progress"
+            )
+        case .stopped:
+            volume.unmount()
+            await fileSystemBridge.unregisterExport(id: registered.id)
+            throw ContainerProtocolError.connectionClosed
+        }
+    }
+
+    private enum GuestMountRegistration {
+        case registered
+        case deleted
+        case stopped
+    }
+
+    private func registerPreparedGuestMount(
+        _ mount: PreparedGuestMount,
+        reference: String
+    ) -> GuestMountRegistration {
+        stateLock.withLock {
+            guard isRunning else { return .stopped }
+            return mountLock.withLock {
+                switch guestMounts.complete(reference, value: mount) {
+                case .registered: return .registered
+                case .deleted: return .deleted
+                }
+            }
+        }
+    }
+
+    private func releaseGuestMount(parameters: [String: GhostboxJSONValue]) async throws {
+        let reference = try Self.stringParameter("mount", in: parameters)
+        guard reference.hasPrefix("@mount/") else {
+            throw ContainerProtocolError.malformedRequest("mount.delete requires an @mount/NAME reference")
+        }
+        let record = mountLock.withLock { guestMounts.release(reference) }
+        guard let record else { return }
+        record.volume.unmount()
+        if let fileSystemBridge {
+            await fileSystemBridge.unregisterExport(id: record.volume.exportID)
+        }
+    }
+
+    private func guestMountSource(parameters: [String: GhostboxJSONValue]) -> String? {
+        guard case .string(let reference) = parameters["mount"] else { return nil }
+        return mountLock.withLock { guestMounts[reference]?.guestPath }
+    }
+
+    func invokeRuntime(
+        _ request: GhostboxDirectRequest,
+        payload: Data? = nil
+    ) async throws -> GhostboxDirectResponse {
+        let encoded: Data
+        if let payload {
+            encoded = payload
+        } else {
+            encoded = try JSONEncoder().encode(request)
+        }
+        let responsePayload = try await runtimeClient.invoke(payload: encoded)
+        return try JSONDecoder().decode(GhostboxDirectResponse.self, from: responsePayload)
+    }
+
+    private static func stringParameter(
+        _ name: String,
+        in parameters: [String: GhostboxJSONValue]
+    ) throws -> String {
+        guard case .string(let value) = parameters[name] else {
+            throw ContainerProtocolError.malformedRequest("missing or invalid string parameter '\(name)'")
+        }
+        return value
+    }
+
+    private static func boolParameter(
+        _ name: String,
+        in parameters: [String: GhostboxJSONValue]
+    ) throws -> Bool? {
+        guard let raw = parameters[name] else { return nil }
+        guard case .boolean(let value) = raw else {
+            throw ContainerProtocolError.malformedRequest("parameter '\(name)' must be a boolean")
+        }
+        return value
+    }
+
+    private static func unsignedIntegerParameter(
+        _ name: String,
+        in parameters: [String: GhostboxJSONValue]
+    ) throws -> UInt64? {
+        guard let raw = parameters[name] else { return nil }
+        guard case .unsignedInteger(let value) = raw else {
+            throw ContainerProtocolError.malformedRequest("parameter '\(name)' must be an unsigned integer")
+        }
+        return value
+    }
+
+    private static func stringArrayParameter(
+        _ name: String,
+        in parameters: [String: GhostboxJSONValue]
+    ) throws -> [String]? {
+        guard let raw = parameters[name] else { return nil }
+        guard case .array(let values) = raw else {
+            throw ContainerProtocolError.malformedRequest("parameter '\(name)' must be an array")
+        }
+        return try values.map {
+            guard case .string(let value) = $0 else {
+                throw ContainerProtocolError.malformedRequest("parameter '\(name)' must contain strings")
+            }
+            return value
+        }
+    }
+
+    private static func isReferenceComponent(_ value: String) -> Bool {
+        !value.isEmpty && value.utf8.count <= 128 && value.utf8.allSatisfy {
+            (48...57).contains($0) || (65...90).contains($0) || (97...122).contains($0)
+                || $0 == 45 || $0 == 46 || $0 == 95
+        }
+    }
+
+    private static func isContainerMountPath(_ path: String) -> Bool {
+        let components = path.split(separator: "/", omittingEmptySubsequences: true)
+        return path.hasPrefix("/") && path != "/" && !path.contains("\0")
+            && !components.contains(where: { $0 == "." || $0 == ".." })
+    }
+
+    /// Reads a single NDJSON request line, enforcing the size cap.
+    private func readRequestLine(channel: BlockingVSockChannel) async throws -> Data {
+        var buffer = Data()
+        while true {
+            guard let chunk = try await channel.read(maxBytes: 4096) else {
+                throw ContainerProtocolError.emptyRequest
+            }
+            buffer.append(chunk)
+            if let newline = buffer.firstIndex(of: 0x0A) {
+                // The cap applies even when the newline arrives beyond the limit.
+                guard newline - buffer.startIndex <= ContainerBridgeConstants.maxRequestLineBytes else {
+                    throw ContainerProtocolError.requestTooLarge(limit: ContainerBridgeConstants.maxRequestLineBytes)
+                }
+                return Data(buffer[buffer.startIndex.. ContainerBridgeConstants.maxRequestLineBytes {
+                throw ContainerProtocolError.requestTooLarge(limit: ContainerBridgeConstants.maxRequestLineBytes)
+            }
+        }
+    }
+
+    private static func isAttachmentMethod(_ method: GhostboxDirectMethod) -> Bool {
+        [
+            GhostboxDirectMethod.readerStreamAttachProxy,
+            GhostboxDirectMethod.writerAttachProxy,
+            GhostboxDirectMethod.terminalAttachProxy,
+        ].contains(method)
+    }
+
+    private static func clearSocketTimeouts(fd: Int32) {
+        var timeout = timeval(tv_sec: 0, tv_usec: 0)
+        let length = socklen_t(MemoryLayout.size)
+        _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, length)
+        _ = setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO, &timeout, length)
+    }
+
+}
+
+// MARK: - VZ listener delegate adapter
+
+/// VZVirtioSocketListener.delegate is weak and its callback arrives on the VM's
+/// serial queue, so this adapter stays a small non-isolated forwarder.
+private final class BridgeListenerDelegate: NSObject, VZVirtioSocketListenerDelegate {
+    private let onConnection: (VZVirtioSocketConnection) -> Bool
+
+    init(onConnection: @escaping (VZVirtioSocketConnection) -> Bool) {
+        self.onConnection = onConnection
+    }
+
+    func listener(_ listener: VZVirtioSocketListener, shouldAcceptNewConnection connection: VZVirtioSocketConnection, from socketDevice: VZVirtioSocketDevice) -> Bool {
+        onConnection(connection)
+    }
+}
+
+// MARK: - Frame writer
+
+/// Serializes NDJSON frame writes from concurrent stdout/stderr/exit producers
+/// onto one dedicated queue using a blocking Darwin write loop, so frames can
+/// never interleave. Callers are private runner/connection threads — never
+/// vmQueue or the main thread.
+private final class VSockFrameWriter: @unchecked Sendable {
+    private let fd: Int32
+    private let queue = DispatchQueue(label: "org.ghostvm.containerbridge.writer")
+    private let closedLock = NSLock()
+    private var isClosed = false // closedLock-confined
+
+    init(fd: Int32) {
+        self.fd = fd
+    }
+
+    /// Writes one complete frame atomically. Returns false if the fd is dead
+    /// (EPIPE/EBADF etc. — SIGPIPE is ignored by the host apps).
+    @discardableResult
+    func writeFrame(_ data: Data) -> Bool {
+        queue.sync {
+            closedLock.lock()
+            let closed = isClosed
+            closedLock.unlock()
+            if closed { return false }
+
+            var offset = 0
+            while offset < data.count {
+                let written = data.withUnsafeBytes { ptr in
+                    Darwin.write(fd, ptr.baseAddress! + offset, data.count - offset)
+                }
+                if written > 0 {
+                    offset += written
+                    continue
+                }
+                if written < 0, errno == EINTR { continue }
+                closedLock.lock()
+                isClosed = true
+                closedLock.unlock()
+                return false
+            }
+            return true
+        }
+    }
+
+    func writeFrameOrThrow(_ data: Data) throws {
+        guard writeFrame(data) else {
+            throw ContainerProtocolError.connectionClosed
+        }
+    }
+
+    /// Marks the writer closed and shuts the socket down both ways, waking any
+    /// thread blocked in read/write so cleanup can proceed. Never closes the
+    /// fd (VZ owns it) and never touches `queue`, so it cannot deadlock behind
+    /// a blocked write. Safe to call multiple times.
+    func shutdown() {
+        closedLock.lock()
+        isClosed = true
+        closedLock.unlock()
+        // shutdown(2) is idempotent enough for cleanup and must run even if a
+        // prior write marked the writer closed, because the read side may still
+        // be blocked on the same socket.
+        Darwin.shutdown(fd, SHUT_RDWR)
+    }
+}
diff --git a/macOS/GhostVM/Services/ContainerRuntimeXPCClient.swift b/macOS/GhostVM/Services/ContainerRuntimeXPCClient.swift
new file mode 100644
index 0000000..ab1a99b
--- /dev/null
+++ b/macOS/GhostVM/Services/ContainerRuntimeXPCClient.swift
@@ -0,0 +1,360 @@
+import Foundation
+import GhostVMKit
+import XPC
+
+/// One application-scoped connection from GhostVMHelper to the runtime process
+/// that hosts all container VMs for this helper instance.
+final class ContainerRuntimeXPCClient: @unchecked Sendable {
+    private final class InvokeReplyState: @unchecked Sendable {
+        private let lock = NSLock()
+        private var continuation: CheckedContinuation?
+        private var timer: DispatchSourceTimer?
+
+        init(_ continuation: CheckedContinuation) {
+            self.continuation = continuation
+        }
+
+        func install(timer: DispatchSourceTimer) {
+            lock.lock()
+            if continuation == nil {
+                lock.unlock()
+                timer.cancel()
+                return
+            }
+            self.timer = timer
+            lock.unlock()
+        }
+
+        func complete(_ result: Result) {
+            lock.lock()
+            guard let continuation else {
+                lock.unlock()
+                return
+            }
+            self.continuation = nil
+            let timer = self.timer
+            self.timer = nil
+            lock.unlock()
+            timer?.cancel()
+            continuation.resume(with: result)
+        }
+    }
+
+    enum ClientError: Error, LocalizedError {
+        case unavailable(String)
+        case encodingFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .unavailable(let detail):
+                return "Container runtime XPC service is unavailable: \(detail)"
+            case .encodingFailed(let detail):
+                return "Failed to encode container runtime request: \(detail)"
+            }
+        }
+    }
+
+    private struct PendingRun {
+        let onReady: () -> Void
+        let onExit: (Int32) -> Void
+    }
+
+    private let connection: xpc_connection_t
+    private let sharedNetwork: SharedVmnetNetwork
+    private let volumeRootURL: URL
+    private let imageRootURL: URL
+    private let lock = NSLock()
+    private var pendingRuns: [String: PendingRun] = [:]
+    private var invalidated = false
+
+    static func ping() throws {
+        let connection = xpc_connection_create(ContainerRuntimeXPCProtocol.serviceName, nil)
+        xpc_connection_set_event_handler(connection) { _ in }
+        xpc_connection_activate(connection)
+        defer { xpc_connection_cancel(connection) }
+
+        let request = xpc_dictionary_create_empty()
+        xpc_dictionary_set_uint64(request, ContainerRuntimeXPCProtocol.Key.version, ContainerRuntimeXPCProtocol.version)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.operation, ContainerRuntimeXPCProtocol.Operation.ping)
+        let reply = xpc_connection_send_message_with_reply_sync(connection, request)
+        if xpc_get_type(reply) == XPC_TYPE_ERROR {
+            let detail = xpc_dictionary_get_string(reply, XPC_ERROR_KEY_DESCRIPTION)
+                .map { String(cString: $0) } ?? "unknown XPC error"
+            throw ClientError.unavailable(detail)
+        }
+        guard xpc_get_type(reply) == XPC_TYPE_DICTIONARY,
+              xpc_dictionary_get_bool(reply, ContainerRuntimeXPCProtocol.Key.ok) else {
+            throw ClientError.unavailable("invalid ping response")
+        }
+    }
+
+    init(sharedNetwork: SharedVmnetNetwork, volumeRootURL: URL, imageRootURL: URL) {
+        self.sharedNetwork = sharedNetwork
+        self.volumeRootURL = volumeRootURL.standardizedFileURL
+        self.imageRootURL = imageRootURL.standardizedFileURL
+        connection = xpc_connection_create(ContainerRuntimeXPCProtocol.serviceName, nil)
+        xpc_connection_set_event_handler(connection) { [weak self] event in
+            self?.handle(event)
+        }
+        xpc_connection_activate(connection)
+    }
+
+    deinit {
+        invalidate()
+    }
+
+    func startBuild(
+        runIdentifier: String,
+        arguments: [String],
+        network: SharedVmnetEndpointLease,
+        stdoutFD: Int32,
+        stderrFD: Int32,
+        onReady: @escaping () -> Void,
+        onExit: @escaping (Int32) -> Void
+    ) throws {
+        let encodedArguments: Data
+        do {
+            encodedArguments = try JSONEncoder().encode(arguments)
+        } catch {
+            throw ClientError.encodingFailed(error.localizedDescription)
+        }
+
+        lock.lock()
+        guard !invalidated else {
+            lock.unlock()
+            throw ClientError.unavailable("connection is invalidated")
+        }
+        pendingRuns[runIdentifier] = PendingRun(onReady: onReady, onExit: onExit)
+        lock.unlock()
+
+        let request = xpc_dictionary_create_empty()
+        xpc_dictionary_set_uint64(request, ContainerRuntimeXPCProtocol.Key.version, ContainerRuntimeXPCProtocol.version)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.operation, ContainerRuntimeXPCProtocol.Operation.build)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.runIdentifier, runIdentifier)
+        encodedArguments.withUnsafeBytes { bytes in
+            xpc_dictionary_set_data(
+                request,
+                ContainerRuntimeXPCProtocol.Key.arguments,
+                bytes.baseAddress,
+                bytes.count
+            )
+        }
+        xpc_dictionary_set_value(request, ContainerRuntimeXPCProtocol.Key.networkSerialization, network.serialization)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.ipv4Address, network.ipv4Address)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.ipv4Gateway, network.ipv4Gateway)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.macAddress, network.macAddress)
+        xpc_dictionary_set_uint64(request, ContainerRuntimeXPCProtocol.Key.mtu, UInt64(network.mtu))
+        xpc_dictionary_set_fd(request, ContainerRuntimeXPCProtocol.Key.stdout, stdoutFD)
+        xpc_dictionary_set_fd(request, ContainerRuntimeXPCProtocol.Key.stderr, stderrFD)
+        xpc_connection_send_message(connection, request)
+    }
+
+    func invoke(payload: Data, timeoutSeconds: TimeInterval? = nil) async throws -> Data {
+        lock.lock()
+        let isInvalidated = invalidated
+        lock.unlock()
+        guard !isInvalidated else {
+            throw ClientError.unavailable("connection is invalidated")
+        }
+
+        let request = request(operation: ContainerRuntimeXPCProtocol.Operation.invoke)
+        addSharedNetwork(to: request)
+        payload.withUnsafeBytes { bytes in
+            xpc_dictionary_set_data(
+                request,
+                ContainerRuntimeXPCProtocol.Key.payload,
+                bytes.baseAddress,
+                bytes.count
+            )
+        }
+        return try await withCheckedThrowingContinuation { continuation in
+            let state = InvokeReplyState(continuation)
+            if let timeoutSeconds {
+                let timer = DispatchSource.makeTimerSource(queue: .global(qos: .userInitiated))
+                timer.schedule(deadline: .now() + timeoutSeconds)
+                timer.setEventHandler {
+                    state.complete(.failure(ClientError.unavailable("invoke timed out")))
+                }
+                timer.resume()
+                state.install(timer: timer)
+            }
+            xpc_connection_send_message_with_reply(
+                connection,
+                request,
+                .global(qos: .userInitiated)
+            ) { reply in
+                state.complete(Self.decodeInvokeReply(reply))
+            }
+        }
+    }
+
+    func attach(payload: Data, descriptor: Int32) async throws {
+        lock.lock()
+        let isInvalidated = invalidated
+        lock.unlock()
+        guard !isInvalidated else {
+            throw ClientError.unavailable("connection is invalidated")
+        }
+
+        let request = request(operation: ContainerRuntimeXPCProtocol.Operation.attach)
+        addSharedNetwork(to: request)
+        payload.withUnsafeBytes { bytes in
+            xpc_dictionary_set_data(
+                request,
+                ContainerRuntimeXPCProtocol.Key.payload,
+                bytes.baseAddress,
+                bytes.count
+            )
+        }
+        xpc_dictionary_set_fd(request, ContainerRuntimeXPCProtocol.Key.descriptor, descriptor)
+        try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in
+            xpc_connection_send_message_with_reply(
+                connection,
+                request,
+                .global(qos: .userInitiated)
+            ) { reply in
+                if xpc_get_type(reply) == XPC_TYPE_ERROR {
+                    let detail = xpc_dictionary_get_string(reply, XPC_ERROR_KEY_DESCRIPTION)
+                        .map { String(cString: $0) } ?? "unknown XPC error"
+                    continuation.resume(throwing: ClientError.unavailable(detail))
+                } else if let error = xpc_dictionary_get_string(reply, ContainerRuntimeXPCProtocol.Key.error) {
+                    continuation.resume(throwing: ClientError.unavailable(String(cString: error)))
+                } else if xpc_dictionary_get_bool(reply, ContainerRuntimeXPCProtocol.Key.ok) {
+                    continuation.resume()
+                } else {
+                    continuation.resume(throwing: ClientError.unavailable("invalid attachment response"))
+                }
+            }
+        }
+    }
+
+    private static func decodeInvokeReply(_ reply: xpc_object_t) -> Result {
+        if xpc_get_type(reply) == XPC_TYPE_ERROR {
+            let detail = xpc_dictionary_get_string(reply, XPC_ERROR_KEY_DESCRIPTION)
+                .map { String(cString: $0) } ?? "unknown XPC error"
+            return .failure(ClientError.unavailable(detail))
+        }
+        if let error = xpc_dictionary_get_string(reply, ContainerRuntimeXPCProtocol.Key.error) {
+            return .failure(ClientError.unavailable(String(cString: error)))
+        }
+        guard let value = xpc_dictionary_get_value(reply, ContainerRuntimeXPCProtocol.Key.payload),
+              xpc_get_type(value) == XPC_TYPE_DATA,
+              let bytes = xpc_data_get_bytes_ptr(value)
+        else {
+            return .failure(ClientError.unavailable("invalid invoke response"))
+        }
+        return .success(Data(bytes: bytes, count: xpc_data_get_length(value)))
+    }
+
+    private func addSharedNetwork(to request: xpc_object_t) {
+        xpc_dictionary_set_value(
+            request,
+            ContainerRuntimeXPCProtocol.Key.networkSerialization,
+            sharedNetwork.serialization
+        )
+        xpc_dictionary_set_string(
+            request,
+            ContainerRuntimeXPCProtocol.Key.ipv4Subnet,
+            sharedNetwork.ipv4Subnet
+        )
+        xpc_dictionary_set_string(
+            request,
+            ContainerRuntimeXPCProtocol.Key.volumeRoot,
+            volumeRootURL.path
+        )
+        xpc_dictionary_set_string(
+            request,
+            ContainerRuntimeXPCProtocol.Key.imageRoot,
+            imageRootURL.path
+        )
+    }
+
+    func cancel(runIdentifier: String) {
+        let request = request(operation: ContainerRuntimeXPCProtocol.Operation.cancel)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.runIdentifier, runIdentifier)
+        xpc_connection_send_message(connection, request)
+    }
+
+    func resize(runIdentifier: String, columns: UInt16, rows: UInt16) {
+        let request = request(operation: ContainerRuntimeXPCProtocol.Operation.resize)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.runIdentifier, runIdentifier)
+        xpc_dictionary_set_uint64(request, ContainerRuntimeXPCProtocol.Key.columns, UInt64(columns))
+        xpc_dictionary_set_uint64(request, ContainerRuntimeXPCProtocol.Key.rows, UInt64(rows))
+        xpc_connection_send_message(connection, request)
+    }
+
+    func invalidate() {
+        lock.lock()
+        guard !invalidated else {
+            lock.unlock()
+            return
+        }
+        invalidated = true
+        let runs = Array(pendingRuns.values)
+        pendingRuns.removeAll()
+        lock.unlock()
+
+        let request = request(operation: ContainerRuntimeXPCProtocol.Operation.shutdown)
+        xpc_connection_send_message(connection, request)
+        xpc_connection_cancel(connection)
+        for run in runs {
+            run.onExit(143)
+        }
+    }
+
+    private func handle(_ event: xpc_object_t) {
+        if xpc_get_type(event) == XPC_TYPE_ERROR {
+            let detail = xpc_dictionary_get_string(event, XPC_ERROR_KEY_DESCRIPTION)
+                .map { String(cString: $0) } ?? "unknown XPC error"
+            NSLog("ContainerRuntimeXPC: connection event: %@", detail)
+            failPendingRuns(
+                status: 125,
+                invalidating: xpc_equal(event, XPC_ERROR_CONNECTION_INVALID)
+            )
+            return
+        }
+        guard xpc_get_type(event) == XPC_TYPE_DICTIONARY,
+              let operationValue = xpc_dictionary_get_string(event, ContainerRuntimeXPCProtocol.Key.operation),
+              let runValue = xpc_dictionary_get_string(event, ContainerRuntimeXPCProtocol.Key.runIdentifier)
+        else {
+            return
+        }
+
+        let operation = String(cString: operationValue)
+        let runIdentifier = String(cString: runValue)
+        switch operation {
+        case ContainerRuntimeXPCProtocol.Operation.ready:
+            lock.lock()
+            let callback = pendingRuns[runIdentifier]?.onReady
+            lock.unlock()
+            callback?()
+        case ContainerRuntimeXPCProtocol.Operation.exit:
+            lock.lock()
+            let pending = pendingRuns.removeValue(forKey: runIdentifier)
+            lock.unlock()
+            pending?.onExit(Int32(xpc_dictionary_get_int64(event, ContainerRuntimeXPCProtocol.Key.exitCode)))
+        default:
+            break
+        }
+    }
+
+    private func failPendingRuns(status: Int32, invalidating: Bool = false) {
+        lock.lock()
+        if invalidating {
+            invalidated = true
+        }
+        let runs = Array(pendingRuns.values)
+        pendingRuns.removeAll()
+        lock.unlock()
+        for run in runs {
+            run.onExit(status)
+        }
+    }
+
+    private func request(operation: String) -> xpc_object_t {
+        let request = xpc_dictionary_create_empty()
+        xpc_dictionary_set_uint64(request, ContainerRuntimeXPCProtocol.Key.version, ContainerRuntimeXPCProtocol.version)
+        xpc_dictionary_set_string(request, ContainerRuntimeXPCProtocol.Key.operation, operation)
+        return request
+    }
+}
diff --git a/macOS/GhostVM/Services/GhostClient.swift b/macOS/GhostVM/Services/GhostClient.swift
index e79c94a..7f9bed2 100644
--- a/macOS/GhostVM/Services/GhostClient.swift
+++ b/macOS/GhostVM/Services/GhostClient.swift
@@ -4,6 +4,27 @@ import GhostVMKit
 import GhostHTTP
 import os
 
+private struct GuestCreateRequest: Encodable {
+    let path: String
+    let type: GuestFileCreateType
+    let mode: UInt32
+}
+
+private struct GuestSymbolicLinkRequest: Encodable {
+    let path: String
+    let destination: String
+}
+
+private struct GuestSetAttributesRequest: Encodable {
+    let path: String
+    let attributes: GuestFileAttributes
+}
+
+private struct GuestRenameRequest: Encodable {
+    let path: String
+    let destinationPath: String
+}
+
 /// HTTP client for communicating with GhostTools running in the guest VM
 /// Supports both vsock (production) and TCP (development) connections
 @MainActor
@@ -262,6 +283,174 @@ public final class GhostClient: GhostClientProtocol {
         throw GhostClientError.notConnected
     }
 
+    public func fileMetadata(path: String) async throws -> GuestFileMetadata {
+        let response = try await sendGuestFilesystemRequest(path: "/api/v1/fs/metadata", guestPath: path)
+        let statusCode = response.head.status.rawValue
+        guard statusCode == 200 else {
+            throw guestFilesystemError(response)
+        }
+        return try JSONDecoder().decode(GuestFileMetadata.self, from: response.body)
+    }
+
+    public func listDirectoryMetadata(path: String) async throws -> GuestDirectoryMetadata {
+        let response = try await sendGuestFilesystemRequest(path: "/api/v1/fs/list", guestPath: path)
+        let statusCode = response.head.status.rawValue
+        guard statusCode == 200 else {
+            throw guestFilesystemError(response)
+        }
+        return try JSONDecoder().decode(GuestDirectoryMetadata.self, from: response.body)
+    }
+
+    public func readFile(path: String, offset: UInt64, length: Int) async throws -> Data {
+        guard length >= 0, length <= 1024 * 1024 else {
+            throw GhostClientError.connectionFailed("Filesystem read length exceeds 1 MiB")
+        }
+        let encodedPath = Self.encodeQueryValue(path)
+        guard let vm = virtualMachine else {
+            throw GhostClientError.notConnected
+        }
+        let response = try await sendHTTPRequest(
+            vm: vm,
+            method: "GET",
+            path: "/api/v1/fs/read?path=\(encodedPath)&offset=\(offset)&length=\(length)",
+            body: nil
+        )
+        let statusCode = response.head.status.rawValue
+        guard statusCode == 200 else {
+            throw guestFilesystemError(response)
+        }
+        return response.body
+    }
+
+    public func readSymbolicLink(path: String) async throws -> String {
+        let response = try await sendGuestFilesystemRequest(path: "/api/v1/fs/readlink", guestPath: path)
+        let statusCode = response.head.status.rawValue
+        guard statusCode == 200, let target = String(data: response.body, encoding: .utf8) else {
+            throw guestFilesystemError(response)
+        }
+        return target
+    }
+
+    public func createFileSystemItem(
+        path: String,
+        type: GuestFileCreateType,
+        mode: UInt32
+    ) async throws -> GuestFileMetadata {
+        try await sendGuestFilesystemMutation(
+            method: "POST",
+            endpoint: "/api/v1/fs/create",
+            body: JSONEncoder().encode(GuestCreateRequest(path: path, type: type, mode: mode))
+        )
+    }
+
+    public func createSymbolicLink(path: String, destination: String) async throws -> GuestFileMetadata {
+        try await sendGuestFilesystemMutation(
+            method: "POST",
+            endpoint: "/api/v1/fs/symlink",
+            body: JSONEncoder().encode(GuestSymbolicLinkRequest(path: path, destination: destination))
+        )
+    }
+
+    public func writeFile(path: String, offset: UInt64, data: Data) async throws -> GuestFileMetadata {
+        guard offset <= UInt64(Int64.max), data.count <= 1024 * 1024 else {
+            throw POSIXError(.EINVAL)
+        }
+        guard let vm = virtualMachine else { throw GhostClientError.notConnected }
+        let response = try await sendHTTPRequest(
+            vm: vm,
+            method: "PATCH",
+            path: "/api/v1/fs/write?path=\(Self.encodeQueryValue(path))&offset=\(offset)",
+            body: data,
+            contentType: "application/octet-stream"
+        )
+        return try decodeGuestFilesystemMetadata(response)
+    }
+
+    public func setFileAttributes(
+        path: String,
+        attributes: GuestFileAttributes
+    ) async throws -> GuestFileMetadata {
+        try await sendGuestFilesystemMutation(
+            method: "PATCH",
+            endpoint: "/api/v1/fs/attributes",
+            body: JSONEncoder().encode(GuestSetAttributesRequest(path: path, attributes: attributes))
+        )
+    }
+
+    public func removeFileSystemItem(path: String) async throws {
+        guard let vm = virtualMachine else { throw GhostClientError.notConnected }
+        let response = try await sendHTTPRequest(
+            vm: vm,
+            method: "DELETE",
+            path: "/api/v1/fs/remove?path=\(Self.encodeQueryValue(path))",
+            body: nil
+        )
+        guard response.head.status.rawValue == 204 else {
+            throw guestFilesystemError(response)
+        }
+    }
+
+    public func renameFileSystemItem(
+        path: String,
+        destinationPath: String
+    ) async throws -> GuestFileMetadata {
+        try await sendGuestFilesystemMutation(
+            method: "POST",
+            endpoint: "/api/v1/fs/rename",
+            body: JSONEncoder().encode(GuestRenameRequest(path: path, destinationPath: destinationPath))
+        )
+    }
+
+    private func sendGuestFilesystemMutation(
+        method: String,
+        endpoint: String,
+        body: Data
+    ) async throws -> GuestFileMetadata {
+        guard let vm = virtualMachine else { throw GhostClientError.notConnected }
+        let response = try await sendHTTPRequest(
+            vm: vm,
+            method: method,
+            path: endpoint,
+            body: body,
+            contentType: "application/json"
+        )
+        return try decodeGuestFilesystemMetadata(response)
+    }
+
+    private func decodeGuestFilesystemMetadata(_ response: HTTPBufferedResponse) throws -> GuestFileMetadata {
+        guard response.head.status.rawValue == 200 else {
+            throw guestFilesystemError(response)
+        }
+        return try JSONDecoder().decode(GuestFileMetadata.self, from: response.body)
+    }
+
+    private func guestFilesystemError(_ response: HTTPBufferedResponse) -> any Error {
+        if let payload = try? JSONDecoder().decode(GuestFilesystemErrorPayload.self, from: response.body),
+           let rawErrno = payload.errno,
+           let code = POSIXErrorCode(rawValue: rawErrno) {
+            return POSIXError(code)
+        }
+        return GhostClientError.invalidResponse(response.head.status.rawValue)
+    }
+
+    private func sendGuestFilesystemRequest(path endpoint: String, guestPath: String) async throws -> HTTPBufferedResponse {
+        guard let vm = virtualMachine else {
+            throw GhostClientError.notConnected
+        }
+        return try await sendHTTPRequest(
+            vm: vm,
+            method: "GET",
+            path: "\(endpoint)?path=\(Self.encodeQueryValue(guestPath))",
+            body: nil
+        )
+    }
+
+    private static func encodeQueryValue(_ value: String) -> String {
+        var allowed = CharacterSet.alphanumerics
+        allowed.insert(charactersIn: "-._~")
+        return value.addingPercentEncoding(withAllowedCharacters: allowed) ?? value
+    }
+
     /// Create a directory in the guest
     public func mkdir(path: String) async throws {
         let body = try JSONEncoder().encode(["path": path])
diff --git a/macOS/GhostVM/Services/GhostVMFSExtensionAssistantView.swift b/macOS/GhostVM/Services/GhostVMFSExtensionAssistantView.swift
new file mode 100644
index 0000000..1e4e662
--- /dev/null
+++ b/macOS/GhostVM/Services/GhostVMFSExtensionAssistantView.swift
@@ -0,0 +1,163 @@
+import AppKit
+import SwiftUI
+
+struct GhostVMFSExtensionAssistantView: View {
+    @Environment(\.dismiss) private var dismiss
+    @ObservedObject var manager: GhostVMFSExtensionManager
+
+    var body: some View {
+        VStack(spacing: 0) {
+            VStack(spacing: 14) {
+                statusSymbol
+                Text(title)
+                    .font(.title2.weight(.semibold))
+                Text(detail)
+                    .foregroundStyle(.secondary)
+                    .multilineTextAlignment(.center)
+                    .fixedSize(horizontal: false, vertical: true)
+                    .frame(maxWidth: 440)
+            }
+            .padding(.horizontal, 32)
+            .padding(.top, 30)
+            .padding(.bottom, 24)
+
+            Divider()
+
+            VStack(alignment: .leading, spacing: 12) {
+                helperRow(
+                    symbol: "shippingbox.fill",
+                    title: "Embedded with GhostVM",
+                    detail: "GhostVMFS is installed and repaired as part of the GhostVM app."
+                )
+                helperRow(
+                    symbol: "checkmark.shield.fill",
+                    title: "Your approval",
+                    detail: "Install / Repair registers GhostVMFS, then opens the File System Extensions switch."
+                )
+            }
+            .padding(24)
+
+            Divider()
+
+            HStack {
+                if manager.health.requiresAttention {
+                    Button("Later") { dismiss() }
+                }
+                Spacer()
+                Button("Scan Again") {
+                    Task { await manager.refresh() }
+                }
+                .disabled(manager.isWorking || manager.health == .checking)
+
+                primaryAction
+            }
+            .padding(18)
+        }
+        .frame(width: 540)
+        .interactiveDismissDisabled(manager.isWorking)
+    }
+
+    @ViewBuilder
+    private var statusSymbol: some View {
+        if manager.isWorking || manager.health == .checking {
+            ProgressView()
+                .controlSize(.large)
+                .frame(width: 52, height: 52)
+        } else {
+            Image(systemName: symbolName)
+                .font(.system(size: 38, weight: .semibold))
+                .foregroundStyle(manager.health == .ready ? Color.green : Color.orange)
+                .frame(width: 52, height: 52)
+        }
+    }
+
+    @ViewBuilder
+    private var primaryAction: some View {
+        switch manager.health {
+        case .ready:
+            Button("Done") { dismiss() }
+                .buttonStyle(.borderedProminent)
+        case .needsApplicationInstall, .missingEmbeddedExtension:
+            Button("Open Applications") {
+                NSWorkspace.shared.open(URL(fileURLWithPath: "/Applications", isDirectory: true))
+            }
+            .buttonStyle(.borderedProminent)
+        case .notRegistered, .duplicateRegistrations, .disabled:
+            if manager.repairAvailable {
+                Button(manager.isWorking ? "Repairing..." : "Install / Repair Extension") {
+                    Task { await manager.repairRegistration() }
+                }
+                .buttonStyle(.borderedProminent)
+                .disabled(manager.isWorking)
+            } else {
+                Button("Open File System Settings") { manager.openSettings() }
+                    .buttonStyle(.borderedProminent)
+            }
+        case .scanFailed:
+            Button("Open File System Settings") { manager.openSettings() }
+                .buttonStyle(.borderedProminent)
+        case .checking:
+            EmptyView()
+        }
+    }
+
+    private var title: String {
+        if manager.isWorking { return "Repairing GhostVMFS..." }
+        switch manager.health {
+        case .checking: return "Checking GhostVMFS..."
+        case .ready: return "GhostVMFS Is Ready"
+        case .needsApplicationInstall: return "Move GhostVM to Applications"
+        case .missingEmbeddedExtension: return "GhostVMFS Is Missing"
+        case .notRegistered: return "Install GhostVMFS"
+        case .duplicateRegistrations: return "Repair GhostVMFS"
+        case .disabled: return "Enable GhostVMFS"
+        case .scanFailed: return "Unable to Check GhostVMFS"
+        }
+    }
+
+    private var detail: String {
+        if manager.isWorking {
+            return "GhostVM is rebuilding the extension registration used by System Settings."
+        }
+        if let statusDetail = manager.statusDetail { return statusDetail }
+        if let errorMessage = manager.errorMessage { return errorMessage }
+        switch manager.health {
+        case .checking: return "Scanning macOS file system extension registration."
+        case .ready: return "The embedded extension is registered, enabled, and ready for guest directory mounts."
+        case .needsApplicationInstall: return "Drag GhostVM into Applications, then open that installed copy."
+        case .missingEmbeddedExtension: return "Reinstall GhostVM from the disk image to restore its embedded extension."
+        case .notRegistered: return "macOS has not registered the extension bundled with this app."
+        case .duplicateRegistrations: return "More than one copy is registered, so macOS may launch the wrong one."
+        case .disabled: return "Install / Repair refreshes GhostVMFS so you can enable it in System Settings."
+        case .scanFailed(let message): return message
+        }
+    }
+
+    private var symbolName: String {
+        switch manager.health {
+        case .ready: return "checkmark.circle.fill"
+        case .needsApplicationInstall: return "arrow.down.app.fill"
+        case .missingEmbeddedExtension: return "xmark.app.fill"
+        case .notRegistered: return "externaldrive.badge.plus"
+        case .duplicateRegistrations: return "wrench.and.screwdriver.fill"
+        case .disabled: return "externaldrive.fill.badge.exclamationmark"
+        case .scanFailed: return "exclamationmark.triangle.fill"
+        case .checking: return "externaldrive.fill"
+        }
+    }
+
+    private func helperRow(symbol: String, title: String, detail: String) -> some View {
+        HStack(alignment: .top, spacing: 12) {
+            Image(systemName: symbol)
+                .foregroundStyle(.secondary)
+                .frame(width: 22)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(title).fontWeight(.medium)
+                Text(detail)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+        }
+    }
+}
diff --git a/macOS/GhostVM/Services/GhostVMFSExtensionManager.swift b/macOS/GhostVM/Services/GhostVMFSExtensionManager.swift
new file mode 100644
index 0000000..2c848a2
--- /dev/null
+++ b/macOS/GhostVM/Services/GhostVMFSExtensionManager.swift
@@ -0,0 +1,339 @@
+import AppKit
+import Combine
+import Darwin
+import Foundation
+import FSKit
+
+enum GhostVMFSExtensionHealth: Equatable {
+    case checking
+    case ready
+    case needsApplicationInstall
+    case missingEmbeddedExtension
+    case notRegistered
+    case duplicateRegistrations(Int)
+    case disabled
+    case scanFailed(String)
+
+    var requiresAttention: Bool {
+        switch self {
+        case .checking, .ready:
+            return false
+        case .needsApplicationInstall, .missingEmbeddedExtension, .notRegistered,
+             .duplicateRegistrations, .disabled, .scanFailed:
+            return true
+        }
+    }
+}
+
+extension Notification.Name {
+    static let ghostVMFSExtensionNeedsAttention = Notification.Name(
+        "org.ghostvm.ghostvm.fs-needs-attention"
+    )
+}
+
+@MainActor
+final class GhostVMFSExtensionManager: ObservableObject {
+    nonisolated static let extensionBundleIdentifier = "org.ghostvm.ghostvm.fs"
+    nonisolated static let extensionRelativePath = "Contents/Extensions/GhostVMFS.appex"
+
+    @Published private(set) var extensionEnabled: Bool?
+    @Published private(set) var health: GhostVMFSExtensionHealth = .checking
+    @Published private(set) var repairAvailable = false
+    @Published private(set) var statusDetail: String?
+    @Published private(set) var isWorking = false
+    @Published var errorMessage: String?
+
+    func refresh() async {
+        extensionEnabled = nil
+        health = .checking
+
+        let appURL = Self.appURL
+        let extensionURL = Self.expectedExtensionURL
+        guard FileManager.default.fileExists(atPath: extensionURL.path) else {
+            extensionEnabled = false
+            repairAvailable = false
+            health = .missingEmbeddedExtension
+            statusDetail = "This copy of GhostVM does not contain the GhostVMFS module. Reinstall GhostVM from the disk image."
+            return
+        }
+
+        do {
+            let modules = try await FSClient.shared.installedExtensions
+            let identities = modules.filter {
+                $0.bundleIdentifier == Self.extensionBundleIdentifier
+            }
+            let snapshot = await Task.detached(priority: .utility) {
+                Self.registrationSnapshot()
+            }.value
+            let expectedURL = extensionURL.resolvingSymlinksInPath().standardizedFileURL
+            let identity = identities.first {
+                $0.url.resolvingSymlinksInPath().standardizedFileURL == expectedURL
+            } ?? identities.first
+            let hasStaleIdentity = identities.contains {
+                $0.url.resolvingSymlinksInPath().standardizedFileURL != expectedURL
+            } || snapshot.urls.contains {
+                $0.resolvingSymlinksInPath().standardizedFileURL != expectedURL
+            }
+
+            guard let identity else {
+                extensionEnabled = false
+                if Self.isInstalledApplication(appURL) {
+                    health = .notRegistered
+                    repairAvailable = true
+                    statusDetail = "macOS has not registered GhostVMFS as an FSKit module."
+                } else {
+                    health = .needsApplicationInstall
+                    repairAvailable = false
+                    statusDetail = "Move GhostVM to Applications before installing its file system extension."
+                }
+                return
+            }
+
+            let selectedCanonicalIdentity = identity.url
+                .resolvingSymlinksInPath().standardizedFileURL == expectedURL
+            extensionEnabled = identity.isEnabled
+                && snapshot.enabledByFSKit
+                && selectedCanonicalIdentity
+                && !hasStaleIdentity
+            repairAvailable = hasStaleIdentity
+                || !snapshot.enabledByFSKit
+                || (snapshot.enabledByFSKit && !identity.isEnabled)
+
+            if !Self.isInstalledApplication(appURL) {
+                health = .needsApplicationInstall
+                repairAvailable = false
+                statusDetail = "Move GhostVM to Applications before installing its file system extension."
+            } else if hasStaleIdentity {
+                let staleCount = Set(
+                    (identities.map(\.url) + snapshot.urls)
+                        .map { $0.resolvingSymlinksInPath().standardizedFileURL }
+                        .filter { $0 != expectedURL }
+                ).count
+                health = .duplicateRegistrations(staleCount)
+                statusDetail = "Found \(staleCount) stray GhostVMFS registration\(staleCount == 1 ? "" : "s"). macOS may launch the wrong extension."
+            } else if !snapshot.enabledByFSKit {
+                health = .disabled
+                statusDetail = "Turn on GhostVMFS in System Settings under File System Extensions."
+            } else if !identity.isEnabled {
+                health = .disabled
+                statusDetail = "FSKit cached a stale disabled state for GhostVMFS."
+            } else {
+                health = .ready
+                statusDetail = nil
+                errorMessage = nil
+            }
+        } catch {
+            extensionEnabled = false
+            repairAvailable = false
+            health = .scanFailed(error.localizedDescription)
+            statusDetail = "GhostVM could not inspect FSKit extensions."
+            errorMessage = "Unable to inspect FSKit extensions: \(error.localizedDescription)"
+        }
+    }
+
+    func repairRegistration() async {
+        let appURL = Self.appURL
+        guard Self.isInstalledApplication(appURL) else {
+            health = .needsApplicationInstall
+            errorMessage = "Move GhostVM to /Applications before repairing its FSKit registration."
+            return
+        }
+        guard !Self.hasMountedGhostVMVolumes() else {
+            statusDetail = "Stop all containers using guest directory mounts before repairing GhostVMFS."
+            return
+        }
+
+        isWorking = true
+        extensionEnabled = nil
+        defer { isWorking = false }
+
+        do {
+            let extensionURL = Self.expectedExtensionURL
+            try await Task.detached(priority: .userInitiated) {
+                try Self.run(
+                    executable: "/usr/bin/codesign",
+                    arguments: ["--verify", "--deep", "--strict", appURL.path]
+                )
+
+                let snapshot = Self.registrationSnapshot()
+                for staleURL in snapshot.urls where
+                    staleURL.resolvingSymlinksInPath().standardizedFileURL
+                        != extensionURL.resolvingSymlinksInPath().standardizedFileURL {
+                    try? Self.run(executable: "/usr/bin/pluginkit", arguments: ["-r", staleURL.path])
+                    if let staleApp = Self.containingApp(for: staleURL), staleApp != appURL {
+                        try? Self.run(
+                            executable: Self.launchServicesRegisterPath,
+                            arguments: ["-u", staleApp.path]
+                        )
+                    }
+                }
+
+                // Recreate the canonical identity too. System Settings can keep
+                // its switch attached to an obsolete PlugInKit UUID.
+                try? Self.run(executable: "/usr/bin/pluginkit", arguments: ["-r", extensionURL.path])
+                try? Self.run(
+                    executable: Self.launchServicesRegisterPath,
+                    arguments: ["-u", appURL.path]
+                )
+                try Self.run(
+                    executable: Self.launchServicesRegisterPath,
+                    arguments: ["-f", "-R", "-trusted", appURL.path]
+                )
+                try? Self.run(executable: "/usr/bin/killall", arguments: ["fskit_agent"])
+            }.value
+
+            try? await Task.sleep(for: .seconds(1))
+            await refresh()
+            errorMessage = nil
+            if extensionEnabled != true {
+                statusDetail = "Registration repaired. Turn on GhostVMFS in System Settings."
+                openSettings()
+            }
+        } catch {
+            extensionEnabled = false
+            errorMessage = "Unable to repair FSKit registration: \(error.localizedDescription)"
+        }
+    }
+
+    func openSettings() {
+        extensionEnabled = nil
+
+        let client = FSClient.shared as NSObject
+        let selector = NSSelectorFromString("openFileSystemExtensionsSettings")
+        if client.responds(to: selector) {
+            typealias OpenSettings = @convention(c) (AnyObject, Selector) -> Bool
+            let implementation = client.method(for: selector)
+            if unsafeBitCast(implementation, to: OpenSettings.self)(client, selector) {
+                return
+            }
+        }
+
+        guard let url = URL(
+            string: "x-apple.systempreferences:com.apple.ExtensionsPreferences?extensionPointIdentifier=com.apple.fskit.fsmodule"
+        ) else { return }
+        NSWorkspace.shared.open(url)
+    }
+
+    nonisolated static func reportNeedsAttention() {
+        NotificationCenter.default.post(name: .ghostVMFSExtensionNeedsAttention, object: nil)
+    }
+
+    struct RegistrationSnapshot: Sendable {
+        let urls: [URL]
+        let enabledByFSKit: Bool
+    }
+
+    nonisolated static let launchServicesRegisterPath =
+        "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister"
+
+    nonisolated static var appURL: URL {
+        Bundle.main.bundleURL.resolvingSymlinksInPath().standardizedFileURL
+    }
+
+    nonisolated static var expectedExtensionURL: URL {
+        appURL.appendingPathComponent(extensionRelativePath, isDirectory: true)
+    }
+
+    nonisolated static var enabledModulesURL: URL {
+        FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/Group Containers/group.com.apple.fskit.settings/enabledModules.plist")
+    }
+
+    nonisolated static func registrationSnapshot() -> RegistrationSnapshot {
+        let output = (try? runAndCapture(
+            executable: "/usr/bin/pluginkit",
+            arguments: [
+                "-v", "-m", "-A", "-D",
+                "-p", "com.apple.fskit.fsmodule",
+                "-i", extensionBundleIdentifier,
+            ]
+        )) ?? ""
+        let enabledModules = (try? Data(contentsOf: enabledModulesURL)).map {
+            enabledModuleIdentifiers(from: $0)
+        } ?? []
+        return RegistrationSnapshot(
+            urls: registrationURLs(from: output),
+            enabledByFSKit: enabledModules.contains(extensionBundleIdentifier)
+        )
+    }
+
+    nonisolated static func registrationURLs(from output: String) -> [URL] {
+        output.split(separator: "\n").compactMap { line -> URL? in
+            guard line.contains(extensionBundleIdentifier),
+                  let path = line.split(separator: "\t", omittingEmptySubsequences: true).last,
+                  path.hasPrefix("/") else { return nil }
+            return URL(fileURLWithPath: String(path), isDirectory: true)
+        }
+    }
+
+    nonisolated static func enabledModuleIdentifiers(from data: Data) -> Set {
+        let modules = (try? PropertyListSerialization.propertyList(
+            from: data,
+            format: nil
+        )) as? [String]
+        return Set(modules ?? [])
+    }
+
+    nonisolated static func isInstalledApplication(_ url: URL) -> Bool {
+        url.path.hasPrefix("/Applications/")
+    }
+
+    nonisolated private static func containingApp(for url: URL) -> URL? {
+        var candidate = url
+        while candidate.path != "/" {
+            if candidate.pathExtension == "app" { return candidate }
+            candidate.deleteLastPathComponent()
+        }
+        return nil
+    }
+
+    nonisolated private static func hasMountedGhostVMVolumes() -> Bool {
+        var fileSystems: UnsafeMutablePointer?
+        let count = getmntinfo(&fileSystems, MNT_NOWAIT)
+        guard count > 0, let fileSystems else { return false }
+        for index in 0.. String in
+                guard let address = bytes.baseAddress else { return "" }
+                return String(cString: address.assumingMemoryBound(to: CChar.self))
+            }
+            if type == "ghostvm" { return true }
+        }
+        return false
+    }
+
+    nonisolated private static func run(executable: String, arguments: [String]) throws {
+        _ = try runAndCapture(executable: executable, arguments: arguments)
+    }
+
+    nonisolated private static func runAndCapture(
+        executable: String,
+        arguments: [String]
+    ) throws -> String {
+        let process = Process()
+        let output = Pipe()
+        process.executableURL = URL(fileURLWithPath: executable)
+        process.arguments = arguments
+        process.standardOutput = output
+        process.standardError = output
+        try process.run()
+        let data = output.fileHandleForReading.readDataToEndOfFile()
+        process.waitUntilExit()
+        let detail = String(data: data, encoding: .utf8)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard process.terminationStatus == 0 else {
+            throw ExtensionCommandFailure(
+                detail.isEmpty
+                    ? "Command exited with status \(process.terminationStatus)"
+                    : detail
+            )
+        }
+        return detail
+    }
+
+    private struct ExtensionCommandFailure: LocalizedError {
+        let detail: String
+        init(_ detail: String) { self.detail = detail }
+        var errorDescription: String? { detail }
+    }
+}
diff --git a/macOS/GhostVM/Services/GuestFileSystemBridgeService.swift b/macOS/GhostVM/Services/GuestFileSystemBridgeService.swift
new file mode 100644
index 0000000..51bd2c3
--- /dev/null
+++ b/macOS/GhostVM/Services/GuestFileSystemBridgeService.swift
@@ -0,0 +1,124 @@
+import Foundation
+import GhostFileKit
+import GhostVMKit
+
+/// Owns short-lived, loopback-only GhostFile shares used as backing stores for
+/// private container volume mounts.
+@MainActor
+final class GuestFileSystemBridgeService {
+    struct RegisteredExport: Sendable {
+        let id: String
+        let resourceURL: URL
+    }
+
+    private struct Export {
+        let server: GhostFileShareServer
+    }
+
+    private weak var client: (any GhostClientProtocol)?
+    private var exports: [String: Export] = [:]
+    private var isRunning = false
+
+    func start(client: any GhostClientProtocol) throws {
+        guard !isRunning else { return }
+        self.client = client
+        isRunning = true
+    }
+
+    func stop() {
+        for export in exports.values {
+            export.server.stop()
+        }
+        exports.removeAll()
+        client = nil
+        isRunning = false
+    }
+
+    func registerExport(
+        guestPath: String,
+        readOnly: Bool = true,
+        cacheTTLSeconds: UInt64 = GhostFileProtocol.defaultCacheTTLSeconds
+    ) async throws -> RegisteredExport {
+        guard isRunning else { throw BridgeError.notRunning }
+        guard guestPath.hasPrefix("/"), !guestPath.contains("\0") else {
+            throw BridgeError.invalidGuestPath
+        }
+        guard cacheTTLSeconds <= GhostFileProtocol.maximumCacheTTLSeconds else {
+            throw BridgeError.invalidCacheTTL
+        }
+        guard exports.count < 32 else { throw BridgeError.tooManyExports }
+        guard let client else { throw BridgeError.guestUnavailable }
+
+        let id = UUID().uuidString.lowercased()
+        let shareID = UUID()
+        let accessKey = UUID().uuidString.lowercased() + UUID().uuidString.lowercased()
+        let identity = try GhostFileTLSIdentity.make()
+        let server = GhostFileShareServer(
+            provider: GuestPathProvider(client: client, root: guestPath),
+            shareName: "GhostVM Container Volume",
+            accessKey: accessKey,
+            shareID: shareID,
+            readOnly: readOnly,
+            tlsIdentity: identity,
+            visibility: .loopbackOnly,
+            advertisesBonjour: false
+        )
+        try server.start()
+
+        do {
+            let baseURL = try await waitForShareURL(server)
+            guard var components = URLComponents(url: baseURL, resolvingAgainstBaseURL: false) else {
+                throw BridgeError.invalidResourceURL
+            }
+            var queryItems = components.queryItems ?? []
+            queryItems.append(URLQueryItem(name: "access_key", value: accessKey))
+            queryItems.append(URLQueryItem(name: "mount_instance", value: UUID().uuidString.lowercased()))
+            queryItems.append(URLQueryItem(
+                name: GhostFileProtocol.cacheTTLQueryName,
+                value: String(cacheTTLSeconds)
+            ))
+            components.queryItems = queryItems
+            guard let resourceURL = components.url else { throw BridgeError.invalidResourceURL }
+            exports[id] = Export(server: server)
+            return RegisteredExport(id: id, resourceURL: resourceURL)
+        } catch {
+            server.stop()
+            throw error
+        }
+    }
+
+    func unregisterExport(id: String) {
+        exports.removeValue(forKey: id)?.server.stop()
+    }
+
+    private func waitForShareURL(_ server: GhostFileShareServer) async throws -> URL {
+        for _ in 0..<500 {
+            if let url = server.shareURL, server.port != 0 { return url }
+            try await Task.sleep(for: .milliseconds(10))
+        }
+        throw BridgeError.listenerTimeout
+    }
+
+    enum BridgeError: Error, LocalizedError {
+        case notRunning
+        case invalidGuestPath
+        case invalidCacheTTL
+        case tooManyExports
+        case invalidResourceURL
+        case guestUnavailable
+        case listenerTimeout
+
+        var errorDescription: String? {
+            switch self {
+            case .notRunning: return "filesystem bridge is not running"
+            case .invalidGuestPath: return "guest export path must be absolute"
+            case .invalidCacheTTL:
+                return "filesystem cache TTL must be from 0 through \(GhostFileProtocol.maximumCacheTTLSeconds) seconds"
+            case .tooManyExports: return "filesystem export limit reached"
+            case .invalidResourceURL: return "failed to create FSKit resource URL"
+            case .guestUnavailable: return "guest is unavailable"
+            case .listenerTimeout: return "timed out starting the filesystem export"
+            }
+        }
+    }
+}
diff --git a/macOS/GhostVM/Services/GuestMountRegistry.swift b/macOS/GhostVM/Services/GuestMountRegistry.swift
new file mode 100644
index 0000000..d687f93
--- /dev/null
+++ b/macOS/GhostVM/Services/GuestMountRegistry.swift
@@ -0,0 +1,93 @@
+import Foundation
+
+enum GuestMountAccessPolicy {
+    private static let guestMountMethods: Set = [
+        "mount.guestShare",
+        "mount.sharedMount",
+        "mount.delete",
+        "mount.isBlock",
+        "mount.type",
+        "mount.source",
+        "mount.destination",
+        "mount.options",
+        "mount.runtimeOptions",
+    ]
+
+    static func allowsGuestInvocation(_ method: String) -> Bool {
+        !method.hasPrefix("mount.") || guestMountMethods.contains(method)
+    }
+}
+
+enum PrivateGuestMountDirectory {
+    static let rootURL = FileManager.default.temporaryDirectory
+        .appendingPathComponent("GhostVM/container-runtime/mounts", isDirectory: true)
+
+    static func create() throws -> URL {
+        try FileManager.default.createDirectory(
+            at: rootURL,
+            withIntermediateDirectories: true,
+            attributes: [.posixPermissions: 0o700]
+        )
+        try FileManager.default.setAttributes([.posixPermissions: 0o700], ofItemAtPath: rootURL.path)
+
+        let mountPoint = rootURL.appendingPathComponent(UUID().uuidString.lowercased(), isDirectory: true)
+        try FileManager.default.createDirectory(
+            at: mountPoint,
+            withIntermediateDirectories: false,
+            attributes: [.posixPermissions: 0o700]
+        )
+        return mountPoint
+    }
+}
+
+struct GuestMountRegistry {
+    enum Completion: Equatable {
+        case registered
+        case deleted
+    }
+
+    private var mounts: [String: Value] = [:]
+    private var pending: Set = []
+    private var deletedPending: Set = []
+
+    mutating func reserve(_ reference: String) -> Bool {
+        guard mounts[reference] == nil, !pending.contains(reference) else { return false }
+        pending.insert(reference)
+        deletedPending.remove(reference)
+        return true
+    }
+
+    mutating func complete(_ reference: String, value: Value) -> Completion {
+        precondition(pending.remove(reference) != nil)
+        if deletedPending.remove(reference) != nil {
+            return .deleted
+        }
+        mounts[reference] = value
+        return .registered
+    }
+
+    mutating func abandon(_ reference: String) {
+        pending.remove(reference)
+        deletedPending.remove(reference)
+    }
+
+    mutating func release(_ reference: String) -> Value? {
+        if pending.contains(reference) {
+            deletedPending.insert(reference)
+            return nil
+        }
+        return mounts.removeValue(forKey: reference)
+    }
+
+    mutating func removeAll() -> [Value] {
+        let values = Array(mounts.values)
+        mounts.removeAll()
+        pending.removeAll()
+        deletedPending.removeAll()
+        return values
+    }
+
+    subscript(reference: String) -> Value? {
+        mounts[reference]
+    }
+}
diff --git a/macOS/GhostVM/Services/GuestPathProvider.swift b/macOS/GhostVM/Services/GuestPathProvider.swift
new file mode 100644
index 0000000..ce65826
--- /dev/null
+++ b/macOS/GhostVM/Services/GuestPathProvider.swift
@@ -0,0 +1,128 @@
+import Foundation
+import GhostFileKit
+import GhostVMKit
+
+final class GuestPathProvider: GhostFileProvider, @unchecked Sendable {
+    private weak var client: (any GhostClientProtocol)?
+    private let root: String
+
+    init(client: any GhostClientProtocol, root: String) {
+        self.client = client
+        self.root = root
+    }
+
+    func metadata(path: String) async throws -> GhostFileProviderMetadata {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return Self.metadata(try await client.fileMetadata(path: try guestPath(path)))
+    }
+
+    func contentsOfDirectory(path: String) async throws -> [GhostFileProviderMetadata] {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return try await client.listDirectoryMetadata(path: guestPath(path)).entries.map(Self.metadata)
+    }
+
+    func read(path: String, offset: UInt64, length: Int) async throws -> GhostFileProviderRead {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return .data(try await client.readFile(path: guestPath(path), offset: offset, length: length))
+    }
+
+    func readSymbolicLink(path: String) async throws -> String {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return try await client.readSymbolicLink(path: guestPath(path))
+    }
+
+    func create(path: String, type: GhostFileProviderCreateType, mode: UInt32) async throws -> GhostFileProviderMetadata {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        let guestType: GuestFileCreateType = type == .file ? .file : .directory
+        return Self.metadata(try await client.createFileSystemItem(
+            path: guestPath(path),
+            type: guestType,
+            mode: mode
+        ))
+    }
+
+    func createSymbolicLink(path: String, destination: String) async throws -> GhostFileProviderMetadata {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return Self.metadata(try await client.createSymbolicLink(
+            path: guestPath(path),
+            destination: destination
+        ))
+    }
+
+    func write(path: String, offset: UInt64, data: Data) async throws -> GhostFileProviderMetadata {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return Self.metadata(try await client.writeFile(path: guestPath(path), offset: offset, data: data))
+    }
+
+    func setAttributes(path: String, attributes: GhostFileProviderAttributes) async throws -> GhostFileProviderMetadata {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return Self.metadata(try await client.setFileAttributes(
+            path: guestPath(path),
+            attributes: GuestFileAttributes(
+                mode: attributes.mode,
+                size: attributes.size,
+                modifiedSeconds: attributes.modifiedSeconds,
+                modifiedNanoseconds: attributes.modifiedNanoseconds,
+                accessedSeconds: attributes.accessedSeconds,
+                accessedNanoseconds: attributes.accessedNanoseconds
+            )
+        ))
+    }
+
+    func remove(path: String) async throws {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        try await client.removeFileSystemItem(path: guestPath(path))
+    }
+
+    func rename(path: String, destinationPath: String) async throws -> GhostFileProviderMetadata {
+        guard let client else { throw POSIXError(.ENOTCONN) }
+        return Self.metadata(try await client.renameFileSystemItem(
+            path: guestPath(path),
+            destinationPath: guestPath(destinationPath)
+        ))
+    }
+
+    private func guestPath(_ relativePath: String) throws -> String {
+        guard !relativePath.contains("\0"), !relativePath.hasPrefix("/") else {
+            throw POSIXError(.EINVAL)
+        }
+        let components = relativePath.split(separator: "/", omittingEmptySubsequences: true)
+        guard !components.contains(where: { $0 == "." || $0 == ".." }) else {
+            throw POSIXError(.EINVAL)
+        }
+        return components.reduce(root) { ($0 as NSString).appendingPathComponent(String($1)) }
+    }
+
+    private static func metadata(_ value: GuestFileMetadata) -> GhostFileProviderMetadata {
+        let type: GhostFileProviderNodeType
+        switch value.type {
+        case .file: type = .file
+        case .directory: type = .directory
+        case .symbolicLink: type = .symbolicLink
+        case .other: type = .other
+        }
+        let objectID = value.inode ^ (value.device &* 0x9E37_79B9_7F4A_7C15)
+        let etagValue = objectID
+            ^ value.size
+            ^ UInt64(bitPattern: Int64(value.modifiedSeconds))
+            ^ UInt64(bitPattern: Int64(value.modifiedNanoseconds))
+        return GhostFileProviderMetadata(
+            name: value.name,
+            type: type,
+            size: value.size,
+            mode: value.mode,
+            uid: value.uid,
+            gid: value.gid,
+            objectID: max(objectID, 3),
+            modifiedSeconds: Int64(value.modifiedSeconds),
+            modifiedNanoseconds: value.modifiedNanoseconds,
+            accessedSeconds: value.accessedSeconds.map(Int64.init),
+            accessedNanoseconds: value.accessedNanoseconds,
+            changedSeconds: value.changedSeconds.map(Int64.init),
+            changedNanoseconds: value.changedNanoseconds,
+            birthSeconds: value.birthSeconds.map(Int64.init),
+            birthNanoseconds: value.birthNanoseconds,
+            etag: "\"node-\(String(etagValue, radix: 16))\""
+        )
+    }
+}
diff --git a/macOS/GhostVM/Services/GuestVolumeMount.swift b/macOS/GhostVM/Services/GuestVolumeMount.swift
new file mode 100644
index 0000000..f60a615
--- /dev/null
+++ b/macOS/GhostVM/Services/GuestVolumeMount.swift
@@ -0,0 +1,86 @@
+import Foundation
+
+/// Owns one FSKit mount for the lifetime of a container run.
+struct GuestVolumeMount: Sendable {
+    let exportID: String
+    let mountPoint: URL
+    let destination: String
+    let readOnly: Bool
+
+    enum MountError: Error, LocalizedError {
+        case bridgeUnavailable
+        case mountFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .bridgeUnavailable:
+                return "Guest filesystem bridge is unavailable."
+            case .mountFailed(let detail):
+                return "Outer-host FSKit mount failed: \(detail) Nothing needs to be installed in this VM; check GhostVMFS in GhostVM on the outer Mac."
+            }
+        }
+    }
+
+    static func mount(
+        registeredExport: GuestFileSystemBridgeService.RegisteredExport,
+        destination: String,
+        readOnly: Bool
+    ) throws -> Self {
+        let mountPoint = try PrivateGuestMountDirectory.create()
+
+        do {
+            let mountOptions = readOnly ? "rdonly,nobrowse,nodev,nosuid" : "nobrowse,nodev,nosuid"
+            try run(
+                executable: "/sbin/mount",
+                arguments: [
+                    "-F", "-t", "ghostvm",
+                    "-o", mountOptions,
+                    registeredExport.resourceURL.absoluteString,
+                    mountPoint.path,
+                ]
+            )
+        } catch {
+            try? FileManager.default.removeItem(at: mountPoint)
+            throw error
+        }
+
+        return Self(
+            exportID: registeredExport.id,
+            mountPoint: mountPoint,
+            destination: destination,
+            readOnly: readOnly
+        )
+    }
+
+    func unmount() {
+        do {
+            try Self.run(executable: "/sbin/umount", arguments: [mountPoint.path])
+            try? FileManager.default.removeItem(at: mountPoint)
+        } catch {
+            NSLog("GuestVolumeMount: failed to unmount %@: %@", mountPoint.path, error.localizedDescription)
+        }
+    }
+
+    private static func run(executable: String, arguments: [String]) throws {
+        let process = Process()
+        let output = Pipe()
+        process.executableURL = URL(fileURLWithPath: executable)
+        process.arguments = arguments
+        process.standardOutput = output
+        process.standardError = output
+        do {
+            try process.run()
+        } catch {
+            throw MountError.mountFailed(error.localizedDescription)
+        }
+        let data = output.fileHandleForReading.readDataToEndOfFile()
+        process.waitUntilExit()
+        guard process.terminationStatus == 0 else {
+            let detail = String(data: data, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            let message = detail.flatMap { $0.isEmpty ? nil : $0 }
+                ?? "mount exited with status \(process.terminationStatus)"
+            throw MountError.mountFailed(message)
+        }
+    }
+}
diff --git a/macOS/GhostVM/Services/NetworkSettingsView.swift b/macOS/GhostVM/Services/NetworkSettingsView.swift
index a9af8e7..2a67c04 100644
--- a/macOS/GhostVM/Services/NetworkSettingsView.swift
+++ b/macOS/GhostVM/Services/NetworkSettingsView.swift
@@ -1,4 +1,5 @@
 import SwiftUI
+import AppKit
 import GhostVMKit
 import Virtualization
 
@@ -61,3 +62,69 @@ struct NetworkSettingsView: View {
         .sorted { $0.name.localizedCaseInsensitiveCompare($1.name) == .orderedAscending }
     }
 }
+
+@available(macOS 13.0, *)
+struct HostContainerSettingsView: View {
+    @EnvironmentObject private var fileSystemExtensionManager: GhostVMFSExtensionManager
+    @Binding var isEnabled: Bool
+    let networkMode: NetworkMode
+    let accessibilityIdentifier: String
+
+    @State private var showingFileSystemExtensionAssistant = false
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            Toggle("Enable host-backed containers", isOn: Binding(
+                get: { networkMode == .nat && isEnabled },
+                set: { isEnabled = networkMode == .nat && $0 }
+            ))
+            .toggleStyle(.checkbox)
+            .disabled(networkMode != .nat)
+            .accessibilityIdentifier(accessibilityIdentifier)
+
+            if networkMode != .nat {
+                Text("Host-backed containers currently require NAT (Shared) networking.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else if isEnabled {
+                Text("Uses an isolated network shared by this VM and its containers.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+
+                Text(fileSystemExtensionStatus)
+                    .font(.caption)
+                    .foregroundStyle(fileSystemExtensionManager.health.requiresAttention ? Color.orange : Color.secondary)
+
+                if fileSystemExtensionManager.health.requiresAttention {
+                    Button("Set Up / Repair File System Extension...") {
+                        showingFileSystemExtensionAssistant = true
+                    }
+                    .font(.caption)
+                }
+            }
+        }
+        .task(id: isEnabled) {
+            guard isEnabled else { return }
+            await fileSystemExtensionManager.refresh()
+        }
+        .sheet(isPresented: $showingFileSystemExtensionAssistant) {
+            GhostVMFSExtensionAssistantView(manager: fileSystemExtensionManager)
+        }
+        .onChange(of: networkMode) { _, newMode in
+            if newMode != .nat {
+                isEnabled = false
+            }
+        }
+    }
+
+    private var fileSystemExtensionStatus: String {
+        switch fileSystemExtensionManager.health {
+        case .ready:
+            return "File System Extension: Enabled"
+        case .checking:
+            return "File System Extension: Checking..."
+        default:
+            return "File System Extension: Not Enabled"
+        }
+    }
+}
diff --git a/macOS/GhostVM/SwiftUIDemoApp.swift b/macOS/GhostVM/SwiftUIDemoApp.swift
index 5e70068..5e23404 100644
--- a/macOS/GhostVM/SwiftUIDemoApp.swift
+++ b/macOS/GhostVM/SwiftUIDemoApp.swift
@@ -25,8 +25,11 @@ private func formattedBuildDate(from version: String) -> String? {
 @available(macOS 13.0, *)
 struct GhostVMSwiftUIApp: App {
     @NSApplicationDelegateAdaptor(App2AppDelegate.self) private var appDelegate
+    @Environment(\.scenePhase) private var scenePhase
     @StateObject private var store = App2VMStore()
     @StateObject private var restoreStore = App2RestoreImageStore()
+    @StateObject private var fileSystemExtensionManager = GhostVMFSExtensionManager()
+    @State private var showingFileSystemExtensionAssistant = false
 
     init() {
         // IMPORTANT: Ignore SIGPIPE signal
@@ -51,11 +54,36 @@ struct GhostVMSwiftUIApp: App {
             VMListDemoView()
                 .environmentObject(store)
                 .environmentObject(restoreStore)
+                .environmentObject(fileSystemExtensionManager)
                 .onOpenURL { url in
                     NSLog("[GhostVM] onOpenURL: \(url.path)")
                     store.addBundles(from: [url])
                     App2AppDelegate.handleOpenURLs([url], store: store)
                 }
+                .sheet(isPresented: $showingFileSystemExtensionAssistant) {
+                    GhostVMFSExtensionAssistantView(manager: fileSystemExtensionManager)
+                }
+                .task {
+                    guard !ProcessInfo.processInfo.arguments.contains("--ui-testing") else { return }
+                    await fileSystemExtensionManager.refresh()
+                    showingFileSystemExtensionAssistant =
+                        fileSystemExtensionManager.health.requiresAttention
+                }
+                .onChange(of: scenePhase) { _, phase in
+                    guard phase == .active else { return }
+                    Task { await fileSystemExtensionManager.refresh() }
+                }
+                .onReceive(
+                    NotificationCenter.default.publisher(for: .ghostVMFSExtensionNeedsAttention)
+                        .receive(on: RunLoop.main)
+                ) { _ in
+                    Task {
+                        await fileSystemExtensionManager.refresh()
+                        if fileSystemExtensionManager.health.requiresAttention {
+                            showingFileSystemExtensionAssistant = true
+                        }
+                    }
+                }
         }
         .commands {
             DemoAppCommands(
@@ -69,6 +97,7 @@ struct GhostVMSwiftUIApp: App {
         WindowGroup("Settings", id: "settings") {
             SettingsDemoView()
                 .environment(\.sparkleUpdater, appDelegate.updaterController.updater)
+                .environmentObject(fileSystemExtensionManager)
         }
 
         WindowGroup("Restore Images", id: "restoreImages") {
@@ -739,6 +768,7 @@ struct CreateVMDemoView: View {
     @State private var diskImageFormat: DiskImageFormat = .defaultForCurrentHost
     @State private var sharedFolders: [SharedFolderConfig] = []
     @State private var networkConfig: NetworkConfig = NetworkConfig.defaultConfig
+    @State private var hostContainersEnabled = false
     @State private var restoreItems: [RestoreItem] = []
     @State private var selectedRestorePath: String?
     @State private var isCreating: Bool = false
@@ -836,6 +866,14 @@ struct CreateVMDemoView: View {
                 NetworkSettingsView(networkConfig: $networkConfig)
             }
 
+            labeledRow("Containers") {
+                HostContainerSettingsView(
+                    isEnabled: $hostContainersEnabled,
+                    networkMode: networkConfig.mode,
+                    accessibilityIdentifier: "createVM.hostContainersToggle"
+                )
+            }
+
             Spacer(minLength: 8)
 
             HStack {
@@ -1009,6 +1047,7 @@ struct CreateVMDemoView: View {
         opts.restoreImagePath = restorePath
         opts.sharedFolders = validFolders
         opts.networkConfig = networkConfig
+        opts.hostContainersEnabled = hostContainersEnabled && networkConfig.mode == .nat
 
         isCreating = true
 
@@ -1411,6 +1450,7 @@ struct EditVMView: View {
     @State private var sharedFolders: [SharedFolderConfig] = []
     @State private var portForwards: [PortForwardConfig] = []
     @State private var networkConfig: NetworkConfig = NetworkConfig.defaultConfig
+    @State private var hostContainersEnabled = false
     @State private var diskGiB: String = ""
     @State private var customIcon: NSImage?
     @State private var customIconChanged: Bool = false
@@ -1510,6 +1550,14 @@ struct EditVMView: View {
                             NetworkSettingsView(networkConfig: $networkConfig)
                         }
 
+                        labeledRow("Containers") {
+                            HostContainerSettingsView(
+                                isEnabled: $hostContainersEnabled,
+                                networkMode: networkConfig.mode,
+                                accessibilityIdentifier: "editVM.hostContainersToggle"
+                            )
+                        }
+
                         if networkConfig.mode == .nat {
                             labeledRow("Port Forwards") {
                                 PortForwardListView(forwards: $portForwards)
@@ -1804,6 +1852,8 @@ struct EditVMView: View {
 
                     // Load network config
                     self.networkConfig = config.networkConfig ?? NetworkConfig.defaultConfig
+                    self.hostContainersEnabled = config.hostContainersEnabled
+                        && self.networkConfig.mode == .nat
 
                     // Load icon mode
                     self.isDynamicIconMode = config.iconMode == "stack"
@@ -1865,6 +1915,7 @@ struct EditVMView: View {
                     storedConfig.iconMode = nil
                 }
                 storedConfig.networkConfig = networkConfig
+                storedConfig.hostContainersEnabled = hostContainersEnabled && networkConfig.mode == .nat
                 try store.save(storedConfig)
 
                 // Save or remove custom icon
@@ -2578,12 +2629,14 @@ struct VMWindowView: View {
 @available(macOS 13.0, *)
 struct SettingsDemoView: View {
     @Environment(\.sparkleUpdater) private var updater
+    @EnvironmentObject private var fileSystemExtensionManager: GhostVMFSExtensionManager
     @State private var ipswPath: String
     @State private var feedURLString: String
     @State private var verificationMessage: String? = nil
     @State private var verificationWasSuccessful: Bool? = nil
     @State private var isVerifying: Bool = false
     @State private var autoCheckForUpdates: Bool = true
+    @State private var showingFileSystemExtensionAssistant = false
 
     private let labelWidth: CGFloat = 130
 
@@ -2598,6 +2651,23 @@ struct SettingsDemoView: View {
             Text("Choose where GhostVM stores IPSW downloads and configure the IPSW feed.")
                 .fixedSize(horizontal: false, vertical: true)
 
+            labeledRow("File System") {
+                HStack(spacing: 8) {
+                    Image(systemName: fileSystemExtensionManager.health == .ready
+                        ? "checkmark.circle.fill"
+                        : "exclamationmark.triangle.fill")
+                        .foregroundStyle(fileSystemExtensionManager.health == .ready
+                            ? Color.green
+                            : Color.orange)
+                    Text(fileSystemExtensionStatus)
+                        .foregroundStyle(.secondary)
+                    Button(fileSystemExtensionManager.health == .ready ? "Details..." : "Set Up / Repair...") {
+                        showingFileSystemExtensionAssistant = true
+                    }
+                    .accessibilityIdentifier("settings.fileSystemExtensionButton")
+                }
+            }
+
             labeledRow("IPSW Cache") {
                 HStack(spacing: 8) {
                     TextField("Path to IPSW cache", text: $ipswPath)
@@ -2677,6 +2747,20 @@ struct SettingsDemoView: View {
                 autoCheckForUpdates = updater.automaticallyChecksForUpdates
             }
         }
+        .task {
+            await fileSystemExtensionManager.refresh()
+        }
+        .sheet(isPresented: $showingFileSystemExtensionAssistant) {
+            GhostVMFSExtensionAssistantView(manager: fileSystemExtensionManager)
+        }
+    }
+
+    private var fileSystemExtensionStatus: String {
+        switch fileSystemExtensionManager.health {
+        case .checking: return "Checking GhostVMFS..."
+        case .ready: return "GhostVMFS is ready"
+        default: return "GhostVMFS needs attention"
+        }
     }
 
     @ViewBuilder
diff --git a/macOS/GhostVM/VMApp-Info.template.plist b/macOS/GhostVM/VMApp-Info.template.plist
index c3bd3be..1b9f39c 100644
--- a/macOS/GhostVM/VMApp-Info.template.plist
+++ b/macOS/GhostVM/VMApp-Info.template.plist
@@ -34,7 +34,7 @@
 	CFBundlePackageType
 	APPL
 	LSMinimumSystemVersion
-	15.0
+	$(MACOSX_DEPLOYMENT_TARGET)
 	LSMultipleInstancesProhibited
 	
 	NSPrincipalClass
diff --git a/macOS/GhostVMContainerRuntime/BuildKitClient.swift b/macOS/GhostVMContainerRuntime/BuildKitClient.swift
new file mode 100644
index 0000000..c1f20a5
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/BuildKitClient.swift
@@ -0,0 +1,582 @@
+// Parts of this file follow Apple's ContainerBuild 1.2.0 protocol client.
+// Copyright © 2025-2026 Apple Inc. and the container project authors.
+// Licensed under the Apache License, Version 2.0.
+
+import ContainerAPIClient
+import ContainerBuild
+import Containerization
+import ContainerizationArchive
+import ContainerizationOCI
+import Foundation
+import GRPCCore
+import GRPCNIOTransportHTTP2
+import Logging
+import NIO
+import NIOPosix
+
+struct GhostBuildKitConfiguration: Sendable {
+    let buildID: String
+    let imageStore: ImageStore
+    let contentStore: ContentStore
+    let contextDirectory: URL
+    let dockerfile: Data
+    let dockerignore: Data?
+    let buildArguments: [String]
+    let target: String
+    let tags: [String]
+    let noCache: Bool
+    let pull: Bool
+    let output: FileHandle
+}
+
+/// A GhostVM-specific client for Apple's builder shim. ContainerBuild's stock
+/// pipeline resolves images through Apple's container service; GhostVM instead
+/// resolves them directly against the per-VM ImageStore.
+final class GhostBuildKitClient: @unchecked Sendable {
+    private let client: Com_Apple_Container_Build_V1_Builder.Client
+    private let grpcClient: GRPCClient
+    private let group: EventLoopGroup
+    private let clientTask: Task
+    // NIO is initialized from the descriptor, so retain its owning FileHandle
+    // for the entire channel lifetime just as Apple's Builder does.
+    private let builderSocket: FileHandle
+    private let shutdownLock = NSLock()
+    private var hasShutdown = false
+
+    init(socket: FileHandle, group: EventLoopGroup) async throws {
+        try socket.setGhostSocketOption(SO_SNDBUF, bytes: 4 << 20)
+        try socket.setGhostSocketOption(SO_RCVBUF, bytes: 2 << 20)
+        let transport = try await HTTP2ClientTransport.WrappedChannel.wrapping(
+            config: .defaults,
+            serviceConfig: .init()
+        ) { configure in
+            try await withCheckedThrowingContinuation { continuation in
+                ClientBootstrap(group: group)
+                    .channelInitializer { channel in
+                        configure(channel).map { configured in
+                            continuation.resume(returning: configured)
+                        }
+                    }
+                    .withConnectedSocket(socket.fileDescriptor)
+                    .whenFailure { error in continuation.resume(throwing: error) }
+            }
+        }
+        let grpcClient = GRPCClient(transport: transport)
+        self.grpcClient = grpcClient
+        self.client = Com_Apple_Container_Build_V1_Builder.Client(wrapping: grpcClient)
+        self.group = group
+        self.builderSocket = socket
+        self.clientTask = Task { try await grpcClient.runConnections() }
+    }
+
+    func info(timeout: Duration = .seconds(30)) async throws {
+        var options = CallOptions.defaults
+        options.timeout = timeout
+        _ = try await client.info(InfoRequest(), options: options)
+    }
+
+    func build(_ configuration: GhostBuildKitConfiguration) async throws {
+        var continuation: AsyncStream.Continuation?
+        let requests = AsyncStream { continuation = $0 }
+        guard let continuation else { throw GhostBuildKitError.invalidContinuation }
+        defer { continuation.finish() }
+
+        let pipeline = try await GhostBuildPipeline(configuration)
+        do {
+            try await client.performBuild(
+                metadata: try Self.metadata(configuration),
+                options: .defaults,
+                requestProducer: { writer in
+                    for await message in requests { try await writer.write(message) }
+                },
+                onResponse: { response in
+                    try await pipeline.run(sender: continuation, receiver: response.messages)
+                }
+            )
+        } catch { throw error }
+    }
+
+    /// Idempotently tears down the connection task and event-loop resources.
+    /// This is deliberately separate from `build` so failed readiness probes
+    /// receive the same cleanup as completed builds.
+    func shutdown() async {
+        let shouldShutdown = shutdownLock.withLock { () -> Bool in
+            guard !hasShutdown else { return false }
+            hasShutdown = true
+            return true
+        }
+        guard shouldShutdown else { return }
+        grpcClient.beginGracefulShutdown()
+        clientTask.cancel()
+        try? await group.shutdownGracefully()
+        _ = builderSocket
+    }
+
+    private static func metadata(_ configuration: GhostBuildKitConfiguration) throws -> Metadata {
+        var metadata = Metadata()
+        metadata.addString(configuration.buildID, forKey: "build-id")
+        metadata.addString(configuration.contextDirectory.path, forKey: "context")
+        metadata.addString(configuration.dockerfile.base64EncodedString(), forKey: "dockerfile")
+        metadata.addString("plain", forKey: "progress")
+        metadata.addString(configuration.target, forKey: "target")
+        metadata.addString("linux/arm64", forKey: "platforms")
+        metadata.addString("type=oci", forKey: "outputs")
+        if let dockerignore = configuration.dockerignore {
+            metadata.addString(dockerignore.base64EncodedString(), forKey: "dockerignore")
+        }
+        for tag in configuration.tags { metadata.addString(tag, forKey: "tag") }
+        for argument in configuration.buildArguments { metadata.addString(argument, forKey: "build-args") }
+        if configuration.noCache { metadata.addString("", forKey: "no-cache") }
+        return metadata
+    }
+}
+
+private protocol GhostBuildPipelineHandler: Sendable {
+    func accepts(_ packet: ServerStream) -> Bool
+    func handle(_ sender: AsyncStream.Continuation, packet: ServerStream) async throws
+}
+
+private actor GhostBuildPipeline {
+    private let handlers: [any GhostBuildPipelineHandler]
+
+    init(_ configuration: GhostBuildKitConfiguration) async throws {
+        handlers = [
+            try GhostBuildFSSync(configuration.contextDirectory),
+            GhostBuildContentProxy(configuration.contentStore),
+            GhostBuildImageResolver(
+                imageStore: configuration.imageStore,
+                contentStore: configuration.contentStore,
+                pull: configuration.pull
+            ),
+            GhostBuildStdio(output: configuration.output),
+        ]
+    }
+
+    func run(
+        sender: AsyncStream.Continuation,
+        receiver: S
+    ) async throws where S.Element == ServerStream {
+        defer { sender.finish() }
+        for try await packet in receiver {
+            try Task.checkCancellation()
+            if case .buildError(let error)? = packet.packetType {
+                throw GhostBuildKitError.buildFailed(error.message)
+            }
+            if case .commandComplete? = packet.packetType { continue }
+            for handler in handlers where handler.accepts(packet) {
+                try await handler.handle(sender, packet: packet)
+                break
+            }
+        }
+    }
+}
+
+private actor GhostBuildFSSync: GhostBuildPipelineHandler {
+    private let context: URL
+
+    init(_ context: URL) throws {
+        let resolved = context.resolvingSymlinksInPath()
+        var isDirectory: ObjCBool = false
+        guard FileManager.default.fileExists(atPath: resolved.path, isDirectory: &isDirectory), isDirectory.boolValue else {
+            throw GhostBuildKitError.invalidContext(resolved.path)
+        }
+        self.context = resolved
+    }
+
+    nonisolated func accepts(_ packet: ServerStream) -> Bool {
+        packet.ghostBuildTransfer?.metadata["stage"] == "fssync"
+    }
+
+    func handle(_ sender: AsyncStream.Continuation, packet: ServerStream) async throws {
+        guard let transfer = packet.ghostBuildTransfer,
+              let method = transfer.metadata["method"] else {
+            throw GhostBuildKitError.protocolFailure("fssync request is missing metadata")
+        }
+        switch method {
+        case "Read": try read(sender, request: transfer, buildID: packet.buildID)
+        case "Info": try info(sender, request: transfer, buildID: packet.buildID)
+        case "Walk": try await walk(sender, request: transfer, buildID: packet.buildID)
+        default: throw GhostBuildKitError.protocolFailure("unknown fssync method \(method)")
+        }
+    }
+
+    private func read(
+        _ sender: AsyncStream.Continuation,
+        request: BuildTransfer,
+        buildID: String
+    ) throws {
+        let path = try safePath(request.source)
+        let offset = UInt64(request.metadata["offset"] ?? "0") ?? 0
+        let length = Int(request.metadata["length"] ?? "0") ?? 0
+        let content = try LocalContent(path: path)
+        let data = try content.data(offset: offset, length: length) ?? Data()
+        sender.yield(response(
+            buildID: buildID,
+            transfer: try makePathTransfer(path, id: request.id, complete: true, data: data)
+        ))
+    }
+
+    private func info(
+        _ sender: AsyncStream.Continuation,
+        request: BuildTransfer,
+        buildID: String
+    ) throws {
+        let path = try safePath(request.source)
+        sender.yield(response(
+            buildID: buildID,
+            transfer: try makePathTransfer(path, id: request.id, complete: true)
+        ))
+    }
+
+    /// The guest already supplied a bounded tar context. The shim applies
+    /// Dockerignore and COPY follow-path filtering after receiving this stream,
+    /// so sending the complete context is correct (and trades bandwidth for a
+    /// substantially smaller trusted host implementation).
+    private func walk(
+        _ sender: AsyncStream.Continuation,
+        request: BuildTransfer,
+        buildID: String
+    ) async throws {
+        if request.metadata["mode"] != "tar" {
+            let infos = try allContextURLs().map { try GhostFileInfo(url: $0, relativeTo: context) }
+            let transfer = makeTransfer(
+                id: request.id,
+                source: request.source,
+                complete: true,
+                metadata: ["os": "linux", "stage": "fssync", "mode": "json"],
+                data: try JSONEncoder().encode(infos)
+            )
+            sender.yield(response(buildID: buildID, transfer: transfer))
+            return
+        }
+
+        let archive = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostvm-context-\(UUID().uuidString).tar")
+        defer { try? FileManager.default.removeItem(at: archive) }
+        let digest = try Archiver.compress(
+            source: context,
+            destination: archive,
+            writerConfiguration: ArchiveWriterConfiguration(format: .paxRestricted, filter: .none)
+        ) { url in
+            guard let relative = url.ghostRelativePath(to: context) else { return nil }
+            return Archiver.ArchiveEntryInfo(
+                pathOnHost: url,
+                pathInArchive: URL(fileURLWithPath: relative)
+            )
+        }
+        let hash = digest.map { String(format: "%02x", $0) }.joined()
+        sender.yield(response(buildID: buildID, transfer: makeTransfer(
+            id: request.id,
+            source: archive.path,
+            complete: false,
+            metadata: ["os": "linux", "stage": "fssync", "mode": "tar", "hash": hash]
+        )))
+
+        let handle = try FileHandle(forReadingFrom: archive)
+        defer { try? handle.close() }
+        while let data = try handle.read(upToCount: 1024 * 1024), !data.isEmpty {
+            sender.yield(response(buildID: buildID, transfer: makeTransfer(
+                id: request.id,
+                source: archive.path,
+                complete: false,
+                metadata: ["os": "linux", "stage": "fssync", "mode": "tar"],
+                data: data
+            )))
+        }
+        sender.yield(response(buildID: buildID, transfer: makeTransfer(
+            id: request.id,
+            source: archive.path,
+            complete: true,
+            metadata: ["os": "linux", "stage": "fssync", "mode": "tar"],
+            data: Data()
+        )))
+    }
+
+    private func safePath(_ source: String) throws -> URL {
+        let candidate = source.hasPrefix("/")
+            ? URL(fileURLWithPath: source)
+            : context.appendingPathComponent(source)
+        let resolved = candidate.standardizedFileURL.resolvingSymlinksInPath()
+        guard resolved.ghostIsDescendant(of: context) else {
+            throw GhostBuildKitError.protocolFailure("context path escapes build root")
+        }
+        return resolved
+    }
+
+    private func allContextURLs() throws -> [URL] {
+        guard let enumerator = FileManager.default.enumerator(
+            at: context,
+            includingPropertiesForKeys: [.isDirectoryKey],
+            options: [],
+            errorHandler: { _, _ in false }
+        ) else { return [] }
+        return enumerator.compactMap { $0 as? URL }.sorted { $0.path < $1.path }
+    }
+
+    private func makePathTransfer(_ path: URL, id: String, complete: Bool, data: Data = Data()) throws -> BuildTransfer {
+        let attributes = try FileManager.default.attributesOfItem(atPath: path.path)
+        let relative = path.ghostRelativePath(to: context) ?? ""
+        let size = (attributes[.size] as? NSNumber)?.uint64Value ?? 0
+        let mode = (attributes[.posixPermissions] as? NSNumber)?.uint32Value ?? 0
+        let uid = (attributes[.ownerAccountID] as? NSNumber)?.uint32Value ?? 0
+        let gid = (attributes[.groupOwnerAccountID] as? NSNumber)?.uint32Value ?? 0
+        let date = (attributes[.modificationDate] as? Date) ?? Date(timeIntervalSince1970: 0)
+        return makeTransfer(
+            id: id,
+            source: relative,
+            complete: complete,
+            isDirectory: (attributes[.type] as? FileAttributeType) == .typeDirectory,
+            metadata: [
+                "os": "linux", "stage": "fssync", "mode": String(mode),
+                "size": String(size), "modified_at": date.ghostRFC3339,
+                "uid": String(uid), "gid": String(gid),
+            ],
+            data: data
+        )
+    }
+
+    private func response(buildID: String, transfer: BuildTransfer) -> ClientStream {
+        var response = ClientStream()
+        response.buildID = buildID
+        response.buildTransfer = transfer
+        return response
+    }
+}
+
+private struct GhostFileInfo: Codable {
+    let name: String
+    let modTime: String
+    let mode: UInt32
+    let size: UInt64
+    let isDir: Bool
+    let uid: UInt32
+    let gid: UInt32
+    let target: String
+
+    init(url: URL, relativeTo context: URL) throws {
+        let attributes = try FileManager.default.attributesOfItem(atPath: url.path)
+        name = url.ghostRelativePath(to: context) ?? ""
+        modTime = ((attributes[.modificationDate] as? Date) ?? Date(timeIntervalSince1970: 0)).ghostRFC3339
+        mode = (attributes[.posixPermissions] as? NSNumber)?.uint32Value ?? 0
+        size = (attributes[.size] as? NSNumber)?.uint64Value ?? 0
+        isDir = (attributes[.type] as? FileAttributeType) == .typeDirectory
+        uid = 0
+        gid = 0
+        target = (attributes[.type] as? FileAttributeType) == .typeSymbolicLink
+            ? try FileManager.default.destinationOfSymbolicLink(atPath: url.path)
+            : ""
+    }
+}
+
+private struct GhostBuildContentProxy: GhostBuildPipelineHandler {
+    let contentStore: ContentStore
+
+    init(_ contentStore: ContentStore) { self.contentStore = contentStore }
+
+    func accepts(_ packet: ServerStream) -> Bool {
+        packet.ghostImageTransfer?.metadata["stage"] == "content-store"
+    }
+
+    func handle(_ sender: AsyncStream.Continuation, packet: ServerStream) async throws {
+        guard let request = packet.ghostImageTransfer,
+              let method = request.metadata["method"] else {
+            throw GhostBuildKitError.protocolFailure("content-store request is missing metadata")
+        }
+        var transfer = ImageTransfer()
+        transfer.id = request.id
+        transfer.tag = request.tag
+        transfer.direction = .into
+        transfer.complete = true
+        transfer.metadata = ["os": "linux", "stage": "content-store", "method": method]
+        switch method {
+        case "/containerd.services.content.v1.Content/Info":
+            let content = try await contentStore.get(digest: request.tag)
+            if let content { transfer.metadata["size"] = String(try content.size()) }
+        case "/containerd.services.content.v1.Content/ReaderAt":
+            guard let content = try await contentStore.get(digest: request.descriptor.digest) else {
+                throw GhostBuildKitError.protocolFailure("requested image content is missing")
+            }
+            let offset = UInt64(request.metadata["offset"] ?? "0") ?? 0
+            let length = Int(request.metadata["length"] ?? "0") ?? 0
+            if offset == 0 && length == 0 {
+                transfer.metadata["size"] = String(try content.size())
+            } else {
+                transfer.data = try content.data(offset: offset, length: length) ?? Data()
+                transfer.metadata["size"] = String(transfer.data.count)
+            }
+        default:
+            throw GhostBuildKitError.protocolFailure("unsupported content-store method \(method)")
+        }
+        var response = ClientStream()
+        response.buildID = packet.buildID
+        response.imageTransfer = transfer
+        sender.yield(response)
+    }
+}
+
+private struct GhostBuildImageResolver: GhostBuildPipelineHandler {
+    let imageStore: ImageStore
+    let contentStore: ContentStore
+    let pull: Bool
+
+    func accepts(_ packet: ServerStream) -> Bool {
+        packet.ghostImageTransfer?.metadata["stage"] == "resolver"
+    }
+
+    func handle(_ sender: AsyncStream.Continuation, packet: ServerStream) async throws {
+        guard let request = packet.ghostImageTransfer,
+              request.metadata["method"] == "/resolve",
+              let rawReference = request.metadata["ref"],
+              let rawPlatform = request.metadata["platform"] else {
+            throw GhostBuildKitError.protocolFailure("resolver request is missing metadata")
+        }
+        let platform = try Platform(from: rawPlatform)
+        var parsed = try Reference.parse(rawReference)
+        if parsed.domain == nil {
+            parsed = try Reference.parse("registry-1.docker.io/\(rawReference)")
+        }
+        parsed.normalize()
+        let reference = parsed.description
+        let image: Containerization.Image
+        if pull {
+            image = try await imageStore.pull(reference: reference, platform: platform)
+        } else {
+            do {
+                image = try await imageStore.get(reference: reference)
+            } catch {
+                image = try await imageStore.pull(reference: reference, platform: platform)
+            }
+        }
+        let manifest = try await image.manifest(for: platform)
+        guard let config: ContainerizationOCI.Image = try await contentStore.get(digest: manifest.config.digest) else {
+            throw GhostBuildKitError.protocolFailure("base image config is missing")
+        }
+        var transfer = ImageTransfer()
+        transfer.id = request.id
+        transfer.tag = image.descriptor.digest
+        transfer.direction = .into
+        transfer.complete = true
+        transfer.data = try JSONEncoder().encode(config)
+        transfer.metadata = [
+            "os": "linux", "stage": "resolver", "method": "/resolve",
+            "ref": rawReference, "platform": platform.description,
+        ]
+        var response = ClientStream()
+        response.buildID = packet.buildID
+        response.imageTransfer = transfer
+        sender.yield(response)
+    }
+}
+
+private struct GhostBuildStdio: GhostBuildPipelineHandler {
+    let output: FileHandle
+
+    func accepts(_ packet: ServerStream) -> Bool {
+        if case .io? = packet.packetType { return true }
+        return false
+    }
+
+    func handle(_ sender: AsyncStream.Continuation, packet: ServerStream) async throws {
+        guard case .io(let io)? = packet.packetType else { return }
+        try output.write(contentsOf: io.data)
+        var acknowledgement = ClientStream()
+        acknowledgement.buildID = packet.buildID
+        acknowledgement.command = .init()
+        acknowledgement.command.id = packet.buildID
+        acknowledgement.command.command = try GhostTerminalCommand().encoded()
+        sender.yield(acknowledgement)
+    }
+}
+
+private struct GhostTerminalCommand: Codable {
+    let commandType = "terminal"
+    let code = "ack"
+    let rows: UInt16 = 0
+    let cols: UInt16 = 0
+
+    enum CodingKeys: String, CodingKey {
+        case commandType = "command_type"
+        case code, rows, cols
+    }
+
+    func encoded() throws -> String {
+        try JSONEncoder().encode(self).base64EncodedString()
+            .trimmingCharacters(in: CharacterSet(charactersIn: "="))
+    }
+}
+
+private func makeTransfer(
+    id: String,
+    source: String,
+    complete: Bool,
+    isDirectory: Bool = false,
+    metadata: [String: String],
+    data: Data = Data()
+) -> BuildTransfer {
+    var transfer = BuildTransfer()
+    transfer.id = id
+    transfer.source = source
+    transfer.direction = .outof
+    transfer.complete = complete
+    transfer.isDirectory = isDirectory
+    transfer.metadata = metadata
+    transfer.data = data
+    return transfer
+}
+
+private extension ServerStream {
+    var ghostBuildTransfer: BuildTransfer? {
+        if case .buildTransfer(let transfer)? = packetType { return transfer }
+        return nil
+    }
+
+    var ghostImageTransfer: ImageTransfer? {
+        if case .imageTransfer(let transfer)? = packetType { return transfer }
+        return nil
+    }
+}
+
+private extension URL {
+    func ghostIsDescendant(of root: URL) -> Bool {
+        let rootComponents = root.standardizedFileURL.pathComponents
+        let ownComponents = standardizedFileURL.pathComponents
+        return ownComponents.count >= rootComponents.count
+            && zip(rootComponents, ownComponents).allSatisfy(==)
+    }
+
+    func ghostRelativePath(to root: URL) -> String? {
+        guard ghostIsDescendant(of: root) else { return nil }
+        return pathComponents.dropFirst(root.standardizedFileURL.pathComponents.count).joined(separator: "/")
+    }
+}
+
+private extension Date {
+    var ghostRFC3339: String {
+        ISO8601DateFormatter().string(from: self)
+    }
+}
+
+private extension FileHandle {
+    func setGhostSocketOption(_ option: Int32, bytes: Int) throws {
+        var value = Int32(bytes)
+        guard setsockopt(fileDescriptor, SOL_SOCKET, option, &value, socklen_t(MemoryLayout.size)) == 0 else {
+            throw POSIXError(.init(rawValue: errno) ?? .EIO)
+        }
+    }
+}
+
+enum GhostBuildKitError: Error, LocalizedError {
+    case invalidContinuation
+    case invalidContext(String)
+    case protocolFailure(String)
+    case buildFailed(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidContinuation: return "failed to initialize the BuildKit request stream"
+        case .invalidContext(let path): return "invalid build context at \(path)"
+        case .protocolFailure(let detail): return "BuildKit protocol error: \(detail)"
+        case .buildFailed(let message): return message.isEmpty ? "BuildKit build failed" : message
+        }
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/BuildRuntime.swift b/macOS/GhostVMContainerRuntime/BuildRuntime.swift
new file mode 100644
index 0000000..89686b0
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/BuildRuntime.swift
@@ -0,0 +1,409 @@
+import Containerization
+import ContainerizationArchive
+import ContainerizationExtras
+import ContainerizationOCI
+import Foundation
+import GhostVMKit
+import NIOPosix
+import XPC
+import vmnet
+
+struct RuntimeBuildOptions: Sendable {
+    let root: URL
+    let kernel: URL
+    let id: String
+    let contextArchive: URL
+    let dockerfile: Data
+    let tags: [String]
+    let buildArguments: [String]
+    let target: String
+    let noCache: Bool
+    let pull: Bool
+
+    static func parse(_ arguments: [String]) throws -> Self {
+        guard arguments.first == "build" else { throw RuntimeBuildError.usage }
+        var root: String?
+        var kernel: String?
+        var id: String?
+        var context: String?
+        var dockerfile: Data?
+        var tags: [String] = []
+        var buildArguments: [String] = []
+        var target = ""
+        var noCache = false
+        var pull = false
+        var index = 1
+        while index < arguments.count {
+            let flag = arguments[index]
+            if flag == "--no-cache" { noCache = true; index += 1; continue }
+            if flag == "--pull" { pull = true; index += 1; continue }
+            guard index + 1 < arguments.count else { throw RuntimeBuildError.usage }
+            let value = arguments[index + 1]
+            switch flag {
+            case "--root": root = value
+            case "--kernel": kernel = value
+            case "--id": id = value
+            case "--context": context = value
+            case "--dockerfile": dockerfile = Data(base64Encoded: value)
+            case "--tag": tags.append(value)
+            case "--build-arg": buildArguments.append(value)
+            case "--target": target = value
+            default: throw RuntimeBuildError.usage
+            }
+            index += 2
+        }
+        guard let root, let kernel, let id, let context, let dockerfile, !dockerfile.isEmpty else {
+            throw RuntimeBuildError.usage
+        }
+        return Self(
+            root: URL(fileURLWithPath: root, isDirectory: true),
+            kernel: URL(fileURLWithPath: kernel),
+            id: id,
+            contextArchive: URL(fileURLWithPath: context),
+            dockerfile: dockerfile,
+            tags: tags,
+            buildArguments: buildArguments,
+            target: target,
+            noCache: noCache,
+            pull: pull
+        )
+    }
+}
+
+enum RuntimeBuildError: Error, LocalizedError {
+    case usage
+    case kernelNotFound(String)
+    case rejectedArchive(String)
+    case builderUnavailable
+    case missingExport(String)
+    case emptyExport
+
+    var errorDescription: String? {
+        switch self {
+        case .usage:
+            return "invalid container build request"
+        case .kernelNotFound(let path):
+            return "container kernel not found at \(path)"
+        case .rejectedArchive(let paths):
+            return "archive contains unsafe members: \(paths)"
+        case .builderUnavailable:
+            return "BuildKit did not open its vsock service"
+        case .missingExport(let path):
+            return "BuildKit did not create its OCI export at \(path)"
+        case .emptyExport:
+            return "BuildKit produced an empty OCI image export"
+        }
+    }
+}
+
+/// Owns one builder VM, the reconstructed vmnet reference, and the output
+/// descriptors until the OCI export has been imported and tagged.
+final class BuildContext: @unchecked Sendable {
+    let connection: xpc_connection_t
+    let runIdentifier: String
+    private let options: RuntimeBuildOptions
+    private let networkReference: vmnet_network_ref
+    private let ipv4Address: String
+    private let ipv4Gateway: String
+    private let macAddress: String
+    private let mtu: UInt32
+    private let stdoutHandle: FileHandle
+    private let stderrHandle: FileHandle
+    private let onComplete: @Sendable (BuildContext) -> Void
+
+    private let lock = NSLock()
+    private var task: Task?
+    private var activeContainer: LinuxContainer?
+    private var cancelled = false
+    private var completed = false
+    private var networkReleased = false
+
+    init(
+        connection: xpc_connection_t,
+        runIdentifier: String,
+        options: RuntimeBuildOptions,
+        networkReference: vmnet_network_ref,
+        ipv4Address: String,
+        ipv4Gateway: String,
+        macAddress: String,
+        mtu: UInt32,
+        stdoutHandle: FileHandle,
+        stderrHandle: FileHandle,
+        onComplete: @escaping @Sendable (BuildContext) -> Void
+    ) {
+        self.connection = connection
+        self.runIdentifier = runIdentifier
+        self.options = options
+        self.networkReference = networkReference
+        self.ipv4Address = ipv4Address
+        self.ipv4Gateway = ipv4Gateway
+        self.macAddress = macAddress
+        self.mtu = mtu
+        self.stdoutHandle = stdoutHandle
+        self.stderrHandle = stderrHandle
+        self.onComplete = onComplete
+    }
+
+    func start() {
+        let task = Task { [self] in
+            let result = await runBuild()
+            complete(exitCode: result.exitCode, message: result.message)
+        }
+        let shouldCancel = lock.withLock { () -> Bool in
+            self.task = task
+            return cancelled
+        }
+        if shouldCancel { task.cancel() }
+    }
+
+    func cancelTask() {
+        let (task, container) = lock.withLock { () -> (Task?, LinuxContainer?) in
+            cancelled = true
+            return (self.task, activeContainer)
+        }
+        task?.cancel()
+        if let container { Task { try? await container.stop() } }
+    }
+
+    private func runBuild() async -> (exitCode: Int32, message: String?) {
+        do {
+            guard FileManager.default.isReadableFile(atPath: options.kernel.path) else {
+                throw RuntimeBuildError.kernelNotFound(options.kernel.path)
+            }
+            let work = options.root.appendingPathComponent("build-runtime/\(options.id)", isDirectory: true)
+            let context = work.appendingPathComponent("context", isDirectory: true)
+            let exports = work.appendingPathComponent("exports", isDirectory: true)
+            let ociLayout = work.appendingPathComponent("oci", isDirectory: true)
+            try? FileManager.default.removeItem(at: work)
+            try FileManager.default.createDirectory(at: context, withIntermediateDirectories: true)
+            try FileManager.default.createDirectory(at: exports, withIntermediateDirectories: true)
+            defer { try? FileManager.default.removeItem(at: work) }
+
+            let rejectedContext = try ArchiveReader(file: options.contextArchive).extractContents(to: context)
+            guard rejectedContext.isEmpty else {
+                throw RuntimeBuildError.rejectedArchive(rejectedContext.prefix(8).joined(separator: ", "))
+            }
+
+            let contentStore = try LocalContentStore(path: options.root.appendingPathComponent("content", isDirectory: true))
+            let imageStore = try ImageStore(path: options.root, contentStore: contentStore)
+            let builderReference = ContainerRuntimeXPCProtocol.builderImage
+            let builderImage = try await imageStore.get(reference: builderReference, pull: false)
+            let kernel = Kernel(path: options.kernel, platform: .linuxArm)
+            var manager = try await ContainerManager(
+                kernel: kernel,
+                initfsReference: "ghcr.io/apple/containerization/vminit@sha256:a69ff331d77997042afc3c7389969be176dfb657ec9ed46366c0e057ec40a297",
+                imageStore: imageStore,
+                network: nil
+            )
+            let builderID = "buildkit-\(options.id.lowercased())"
+            var container: LinuxContainer?
+            do {
+                let created = try await manager.create(
+                    builderID,
+                    image: builderImage,
+                    rootfsSizeInBytes: 16 * 1024 * 1024 * 1024,
+                    networking: false
+                ) { configuration in
+                    configuration.cpus = 2
+                    configuration.memoryInBytes = 2 * 1024 * 1024 * 1024
+                    configuration.hostname = "buildkit"
+                    configuration.interfaces = [
+                        VmnetNetwork.Interface(
+                            reference: self.networkReference,
+                            ipv4Address: try CIDRv4(self.ipv4Address),
+                            ipv4Gateway: try IPv4Address(self.ipv4Gateway),
+                            macAddress: try MACAddress(self.macAddress),
+                            mtu: self.mtu
+                        )
+                    ]
+                    configuration.dns = DNS(nameservers: [self.ipv4Gateway])
+                    configuration.process.arguments = [
+                        "/usr/local/bin/container-builder-shim", "--debug", "--vsock", "--enable-qemu",
+                    ]
+                    configuration.process.capabilities = .allCapabilities
+                    configuration.process.stdout = FileWriter(self.stderrHandle)
+                    configuration.process.stderr = FileWriter(self.stderrHandle)
+                    configuration.maskedPaths = []
+                    configuration.readonlyPaths = []
+                    configuration.mounts.append(.any(type: "tmpfs", source: "tmpfs", destination: "/run"))
+                    configuration.mounts.append(.share(
+                        source: exports.path,
+                        destination: "/var/lib/container-builder-shim/exports"
+                    ))
+                }
+                container = created
+                try await created.create()
+                try await created.start()
+                lock.withLock { activeContainer = created }
+
+                let client = try await connectBuilder(created)
+                sendReady()
+                let ignore = try? Data(contentsOf: context.appendingPathComponent(".dockerignore"))
+                do {
+                    try await client.build(GhostBuildKitConfiguration(
+                        buildID: options.id,
+                        imageStore: imageStore,
+                        contentStore: contentStore,
+                        contextDirectory: context,
+                        dockerfile: options.dockerfile,
+                        dockerignore: ignore,
+                        buildArguments: options.buildArguments,
+                        target: options.target,
+                        tags: try options.tags.map(Self.normalizedReference),
+                        noCache: options.noCache,
+                        pull: options.pull,
+                        output: stderrHandle
+                    ))
+                    await client.shutdown()
+                } catch {
+                    await client.shutdown()
+                    throw error
+                }
+
+                try await created.stop()
+                try manager.delete(builderID)
+                container = nil
+                lock.withLock { activeContainer = nil }
+
+                let export = exports.appendingPathComponent("\(options.id)/out.tar")
+                guard FileManager.default.fileExists(atPath: export.path) else {
+                    throw RuntimeBuildError.missingExport(export.path)
+                }
+                try FileManager.default.createDirectory(at: ociLayout, withIntermediateDirectories: true)
+                let rejectedExport = try ArchiveReader(file: export).extractContents(to: ociLayout)
+                guard rejectedExport.isEmpty else {
+                    throw RuntimeBuildError.rejectedArchive(rejectedExport.prefix(8).joined(separator: ", "))
+                }
+                let tags = try options.tags.map(Self.normalizedReference)
+                // `ImageStore.load` creates the reference carried by the OCI
+                // annotation and rejects an existing one. Docker tags are
+                // replaceable, but retain their previous descriptions so a
+                // malformed or failed import cannot destroy a runnable image.
+                var previousImages: [Containerization.Image.Description] = []
+                for tag in tags {
+                    if let previous = try? await imageStore.get(reference: tag) {
+                        previousImages.append(previous.description)
+                    }
+                    try? await imageStore.delete(reference: tag)
+                }
+                let image: Containerization.Image
+                do {
+                    let images = try await imageStore.load(from: ociLayout)
+                    guard let loaded = images.first else { throw RuntimeBuildError.emptyExport }
+                    let source = loaded.reference
+                    for tag in tags where tag != source {
+                        _ = try await imageStore.tag(existing: source, new: tag)
+                    }
+                    image = loaded
+                } catch {
+                    for tag in tags { try? await imageStore.delete(reference: tag) }
+                    for description in previousImages {
+                        _ = try? await imageStore.create(description: description)
+                    }
+                    throw error
+                }
+                let digest = image.descriptor.digest
+                try stdoutHandle.write(contentsOf: Data("Successfully built \(digest)\n".utf8))
+                for tag in tags {
+                    try stdoutHandle.write(contentsOf: Data("Successfully tagged \(tag)\n".utf8))
+                }
+                return (0, nil)
+            } catch {
+                if let container { try? await container.stop() }
+                try? manager.delete(builderID)
+                throw error
+            }
+        } catch {
+            if Task.isCancelled || error is CancellationError { return (143, nil) }
+            return (125, (error as? LocalizedError)?.errorDescription ?? String(describing: error))
+        }
+    }
+
+    /// Cold builder startup can take well over 30 seconds while buildkitd
+    /// initializes. Retry the complete dial + gRPC health probe for the same
+    /// five-minute window used by Apple's `container build`, cleaning up every
+    /// failed probe before trying again.
+    private func connectBuilder(_ container: LinuxContainer) async throws -> GhostBuildKitClient {
+        var lastError: Error?
+        let clock = ContinuousClock()
+        let deadline = clock.now.advanced(by: .seconds(300))
+        while clock.now < deadline {
+            try Task.checkCancellation()
+            do {
+                let socket = try await container.dialVsock(port: 8088)
+                let group = MultiThreadedEventLoopGroup(numberOfThreads: 1)
+                do {
+                    let client = try await GhostBuildKitClient(socket: socket, group: group)
+                    do {
+                        try await client.info(timeout: .seconds(5))
+                        return client
+                    } catch {
+                        lastError = error
+                        await client.shutdown()
+                    }
+                } catch {
+                    lastError = error
+                    try? await group.shutdownGracefully()
+                }
+            } catch {
+                lastError = error
+            }
+            try await Task.sleep(for: .milliseconds(250))
+        }
+        if let lastError { throw lastError }
+        throw RuntimeBuildError.builderUnavailable
+    }
+
+    private static func normalizedReference(_ raw: String) throws -> String {
+        let reference = try Reference.parse(raw)
+        reference.normalize()
+        return reference.description
+    }
+
+    private func sendReady() {
+        let event = xpc_dictionary_create_empty()
+        xpc_dictionary_set_string(event, ContainerRuntimeXPCProtocol.Key.operation, ContainerRuntimeXPCProtocol.Operation.ready)
+        xpc_dictionary_set_string(event, ContainerRuntimeXPCProtocol.Key.runIdentifier, runIdentifier)
+        xpc_connection_send_message(connection, event)
+    }
+
+    private func complete(exitCode: Int32, message: String?) {
+        let shouldComplete = lock.withLock { () -> Bool in
+            guard !completed else { return false }
+            completed = true
+            task = nil
+            activeContainer = nil
+            return true
+        }
+        guard shouldComplete else { return }
+        if let message {
+            try? stderrHandle.write(contentsOf: Data("ghostvm-container-runtime: \(message)\n".utf8))
+        }
+        releaseNetworkReference()
+        try? stdoutHandle.close()
+        try? stderrHandle.close()
+        let event = xpc_dictionary_create_empty()
+        xpc_dictionary_set_string(event, ContainerRuntimeXPCProtocol.Key.operation, ContainerRuntimeXPCProtocol.Operation.exit)
+        xpc_dictionary_set_string(event, ContainerRuntimeXPCProtocol.Key.runIdentifier, runIdentifier)
+        xpc_dictionary_set_int64(event, ContainerRuntimeXPCProtocol.Key.exitCode, Int64(exitCode))
+        if let message { xpc_dictionary_set_string(event, ContainerRuntimeXPCProtocol.Key.error, message) }
+        xpc_connection_send_message(connection, event)
+        onComplete(self)
+        xpc_transaction_end()
+    }
+
+    private func releaseNetworkReference() {
+        let release = lock.withLock { () -> Bool in
+            guard !networkReleased else { return false }
+            networkReleased = true
+            return true
+        }
+        if release { SharedVmnetNetwork.releaseVmnetReference(networkReference) }
+    }
+
+    deinit {
+        releaseNetworkReference()
+        try? stdoutHandle.close()
+        try? stderrHandle.close()
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBootCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBootCommands.swift
new file mode 100644
index 0000000..b364751
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBootCommands.swift
@@ -0,0 +1,821 @@
+import Containerization
+import ContainerAPIService
+import ContainerPersistence
+import ContainerPlugin
+import ContainerizationOCI
+import Foundation
+import GhostVMKit
+import Logging
+
+struct GhostboxKernelCommandLineCommands: GhostboxDomainHandler {
+    let resource = "kernelCommandLine"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "kernelCommandLine.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["commandLine", "kernelArgument", "initArgument"]
+            )
+            let commandLine = Kernel.CommandLine(
+                kernelArgs: try decoded.optionalStringArray("kernelArgument") ?? Kernel.CommandLine.kernelDefaults,
+                initArgs: try decoded.optionalStringArray("initArgument") ?? []
+            )
+            let reference = try session.registerMutable(
+                kind: "kernel-command-line",
+                name: try decoded.requiredString("commandLine"),
+                value: commandLine,
+                equivalent: ghostboxCommandLinesEqual
+            )
+            return .reference(reference)
+
+        case "kernelCommandLine.createDebug":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["commandLine", "debug", "panic", "initArgument"]
+            )
+            let commandLine = Kernel.CommandLine(
+                debug: try decoded.requiredBool("debug"),
+                panic: try decoded.requiredInt("panic"),
+                initArgs: try decoded.optionalStringArray("initArgument") ?? []
+            )
+            let reference = try session.registerMutable(
+                kind: "kernel-command-line",
+                name: try decoded.requiredString("commandLine"),
+                value: commandLine,
+                equivalent: ghostboxCommandLinesEqual
+            )
+            return .reference(reference)
+
+        case "kernelCommandLine.addDebug":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelCommandLine"])
+            let reference = try decoded.requiredReference("kernelCommandLine", expectedKind: "kernel-command-line")
+            try session.updateValue(for: reference, expectedKind: "kernel-command-line", as: Kernel.CommandLine.self) {
+                $0.addDebug()
+            }
+            return .void
+
+        case "kernelCommandLine.addPanic":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelCommandLine", "level"])
+            let reference = try decoded.requiredReference("kernelCommandLine", expectedKind: "kernel-command-line")
+            let level = try decoded.requiredInt("level")
+            try session.updateValue(for: reference, expectedKind: "kernel-command-line", as: Kernel.CommandLine.self) {
+                $0.addPanic(level: level)
+            }
+            return .void
+
+        case "kernelCommandLine.setAgentLogLevel":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelCommandLine", "level"])
+            let reference = try decoded.requiredReference("kernelCommandLine", expectedKind: "kernel-command-line")
+            let rawLevel = try decoded.requiredString("level")
+            guard let level = Logger.Level(rawValue: rawLevel.lowercased()) else {
+                throw DirectDispatchError(.invalidArgument, "unknown logger level '\(rawLevel)'")
+            }
+            try session.updateValue(for: reference, expectedKind: "kernel-command-line", as: Kernel.CommandLine.self) {
+                $0.setAgentLogLevel(level: level)
+            }
+            return .void
+
+        case "kernelCommandLine.kernelArguments", "kernelCommandLine.initArguments":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelCommandLine"])
+            let reference = try decoded.requiredReference("kernelCommandLine", expectedKind: "kernel-command-line")
+            let commandLine: Kernel.CommandLine = try session.valueSnapshot(
+                for: reference,
+                expectedKind: "kernel-command-line"
+            )
+            if method.rawValue == "kernelCommandLine.kernelArguments" {
+                return .strings(commandLine.kernelArgs)
+            }
+            return .strings(commandLine.initArgs)
+
+        default:
+            throw ghostboxUnsupportedBootMethod(method)
+        }
+    }
+}
+
+struct GhostboxKernelCommands: GhostboxDomainHandler {
+    let resource = "kernel"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "kernel.installRecommended":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            let configuration = try await ConfigurationLoader.load(configurationFiles: [
+                ConfigurationLoader.configurationFile(.appRoot)
+            ])
+            let service = try ghostboxKernelService()
+            let recommendedName = URL(filePath: configuration.kernel.binaryPath).lastPathComponent
+            if let kernel = try? await service.getDefaultKernel(platform: .linuxArm),
+               kernel.path.lastPathComponent == recommendedName {
+                return try ghostboxRegisterDefaultKernel(kernel, session: session)
+            }
+            try await service.installKernelFrom(
+                tar: configuration.kernel.url,
+                kernelFilePath: configuration.kernel.binaryPath,
+                platform: .linuxArm,
+                progressUpdate: nil,
+                expectedDigest: configuration.kernel.digest,
+                force: true
+            )
+            return try ghostboxRegisterDefaultKernel(
+                try await service.getDefaultKernel(platform: .linuxArm),
+                session: session
+            )
+
+        case "kernel.default":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            let service = try ghostboxKernelService()
+            let kernel = try await service.getDefaultKernel(platform: .linuxArm)
+            return try ghostboxRegisterDefaultKernel(kernel, session: session)
+
+        case "kernel.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["kernel", "path", "platform", "commandLine"]
+            )
+            let commandLine: Kernel.CommandLine
+            if let reference = try decoded.optionalReference("commandLine", expectedKind: "kernel-command-line") {
+                commandLine = try session.valueSnapshot(for: reference, expectedKind: "kernel-command-line")
+            } else {
+                commandLine = Kernel.CommandLine(debug: false, panic: 0)
+            }
+            let kernel = Kernel(
+                path: try ghostboxURL(decoded.requiredString("path"), parameter: "path"),
+                platform: try ghostboxSystemPlatform(parameters, "platform"),
+                commandline: commandLine
+            )
+            let reference = try session.register(
+                kind: "kernel",
+                name: try decoded.requiredString("kernel"),
+                value: kernel,
+                equivalent: ghostboxKernelsEqual
+            )
+            return .reference(reference)
+
+        case "kernel.path", "kernel.platform", "kernel.kernelArguments", "kernel.initArguments":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernel"])
+            let reference = try decoded.requiredReference("kernel", expectedKind: "kernel")
+            let kernel: Kernel = try session.value(for: reference, expectedKind: "kernel")
+            switch method.rawValue {
+            case "kernel.path": return .string(kernel.path.absoluteString)
+            case "kernel.platform": return ghostboxSystemPlatformValue(kernel.platform)
+            case "kernel.kernelArguments": return .strings(kernel.kernelArgs)
+            default: return .strings(kernel.initArgs)
+            }
+
+        default:
+            throw ghostboxUnsupportedBootMethod(method)
+        }
+    }
+}
+
+private func ghostboxKernelService() throws -> KernelService {
+    try KernelService(
+        log: Logger(label: "org.ghostvm.ghostbox.kernel"),
+        appRoot: URL(filePath: ApplicationRoot.pathname)
+    )
+}
+
+private func ghostboxRegisterDefaultKernel(
+    _ kernel: Kernel,
+    session: GhostboxSession
+) throws -> GhostboxDirectValue {
+    .reference(try session.register(
+        kind: "kernel",
+        name: "default",
+        value: kernel,
+        equivalent: ghostboxKernelsEqual
+    ))
+}
+
+struct GhostboxKernelImageCommands: GhostboxDomainHandler {
+    let resource = "kernelImage"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "kernelImage.fromImage":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelImage", "image"])
+            let imageReference = try decoded.requiredReference("image", expectedKind: "image")
+            let image = try ghostboxImageValue(imageReference, session: session)
+            return try ghostboxRegisterKernelImage(
+                KernelImage(image: image),
+                name: decoded.requiredString("kernelImage"),
+                session: session
+            )
+
+        case "kernelImage.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["kernelImage", "reference", "kernel", "label", "imageStore", "contentStore"]
+            )
+            let kernels: [Kernel] = try decoded.requiredReferences("kernel", expectedKind: "kernel").map {
+                try session.value(for: $0, expectedKind: "kernel")
+            }
+            let imageStoreReference = try decoded.requiredReference("imageStore", expectedKind: "image-store")
+            let imageStore: ImageStore = try session.value(for: imageStoreReference, expectedKind: "image-store")
+            let contentStoreReference = try decoded.requiredReference("contentStore", expectedKind: "content-store")
+            let contentStore: any ContentStore = try session.value(
+                for: contentStoreReference,
+                expectedKind: "content-store",
+                as: (any ContentStore).self
+            )
+            let image = try await KernelImage.create(
+                reference: decoded.requiredString("reference"),
+                binaries: kernels,
+                labels: try ghostboxLabels(decoded.optionalStringArray("label") ?? []),
+                imageStore: imageStore,
+                contentStore: contentStore
+            )
+            return try ghostboxRegisterKernelImage(
+                image,
+                name: decoded.requiredString("kernelImage"),
+                session: session
+            )
+
+        case "kernelImage.kernel":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelImage", "platform"])
+            let reference = try decoded.requiredReference("kernelImage", expectedKind: "kernel-image")
+            let image: KernelImage = try session.value(for: reference, expectedKind: "kernel-image")
+            let platform = try ghostboxSystemPlatform(parameters, "platform")
+            let kernel = try await image.kernel(for: platform)
+            let name = ghostboxDerivedName(
+                reference: reference,
+                operation: "kernel",
+                discriminator: "\(platform.os.rawValue)/\(platform.architecture.rawValue)"
+            )
+            let kernelReference = try session.register(
+                kind: "kernel",
+                name: name,
+                value: kernel,
+                equivalent: ghostboxKernelsEqual
+            )
+            return .reference(kernelReference)
+
+        case "kernelImage.name":
+            let decoded = try GhostboxParameters(parameters, allowed: ["kernelImage"])
+            let reference = try decoded.requiredReference("kernelImage", expectedKind: "kernel-image")
+            let image: KernelImage = try session.value(for: reference, expectedKind: "kernel-image")
+            return .string(image.name)
+
+        case "kernelImage.mediaType":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            return .string(KernelImage.mediaType)
+
+        default:
+            throw ghostboxUnsupportedBootMethod(method)
+        }
+    }
+}
+
+struct GhostboxInitImageCommands: GhostboxDomainHandler {
+    let resource = "initImage"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "initImage.fromImage":
+            let decoded = try GhostboxParameters(parameters, allowed: ["initImage", "image"])
+            let imageReference = try decoded.requiredReference("image", expectedKind: "image")
+            let image = try ghostboxImageValue(imageReference, session: session)
+            return try ghostboxRegisterInitImage(
+                InitImage(image: image),
+                name: decoded.requiredString("initImage"),
+                session: session
+            )
+
+        case "initImage.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["initImage", "reference", "rootfs", "platform", "label", "imageStore", "contentStore"]
+            )
+            let imageStoreReference = try decoded.requiredReference("imageStore", expectedKind: "image-store")
+            let imageStore: ImageStore = try session.value(for: imageStoreReference, expectedKind: "image-store")
+            let contentStoreReference = try decoded.requiredReference("contentStore", expectedKind: "content-store")
+            let contentStore: any ContentStore = try session.value(
+                for: contentStoreReference,
+                expectedKind: "content-store",
+                as: (any ContentStore).self
+            )
+            let image = try await InitImage.create(
+                reference: decoded.requiredString("reference"),
+                rootfs: try ghostboxURL(decoded.requiredString("rootfs"), parameter: "rootfs"),
+                platform: try ghostboxOCIPlatform(parameters, "platform"),
+                labels: try ghostboxLabels(decoded.optionalStringArray("label") ?? []),
+                imageStore: imageStore,
+                contentStore: contentStore
+            )
+            return try ghostboxRegisterInitImage(
+                image,
+                name: decoded.requiredString("initImage"),
+                session: session
+            )
+
+        case "initImage.initBlock":
+            let decoded = try GhostboxParameters(parameters, allowed: ["initImage", "at", "platform"])
+            let reference = try decoded.requiredReference("initImage", expectedKind: "init-image")
+            let image: InitImage = try session.value(for: reference, expectedKind: "init-image")
+            let platform = try ghostboxSystemPlatform(parameters, "platform")
+            let destination = try decoded.requiredString("at")
+            let mount = try await image.initBlock(
+                at: try ghostboxURL(destination, parameter: "at"),
+                for: platform
+            )
+            let name = ghostboxDerivedName(
+                reference: reference,
+                operation: "init-block",
+                discriminator: "\(destination)|\(platform.os.rawValue)/\(platform.architecture.rawValue)"
+            )
+            let mountReference = try session.register(
+                kind: "mount",
+                name: name,
+                value: mount,
+                equivalent: ghostboxMountsEqual
+            )
+            return .reference(mountReference)
+
+        case "initImage.name":
+            let decoded = try GhostboxParameters(parameters, allowed: ["initImage"])
+            let reference = try decoded.requiredReference("initImage", expectedKind: "init-image")
+            let image: InitImage = try session.value(for: reference, expectedKind: "init-image")
+            return .string(image.name)
+
+        default:
+            throw ghostboxUnsupportedBootMethod(method)
+        }
+    }
+}
+
+struct GhostboxMountCommands: GhostboxDomainHandler {
+    let resource = "mount"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "mount.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["mount", "type", "source", "destination", "option", "runtimeOptions"]
+            )
+            let mount = Containerization.Mount(
+                type: try decoded.requiredString("type"),
+                source: try decoded.requiredString("source"),
+                destination: try decoded.requiredString("destination"),
+                options: try decoded.requiredStringArray("option"),
+                runtimeOptions: try ghostboxMountRuntimeOptions(parameters, "runtimeOptions")
+            )
+            return try ghostboxRegisterMount(
+                mount,
+                name: decoded.requiredString("mount"),
+                session: session
+            )
+
+        case "mount.block":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["mount", "format", "source", "destination", "option", "runtimeOption"]
+            )
+            return try ghostboxRegisterMount(
+                Containerization.Mount.block(
+                    format: decoded.requiredString("format"),
+                    source: decoded.requiredString("source"),
+                    destination: decoded.requiredString("destination"),
+                    options: try decoded.optionalStringArray("option") ?? [],
+                    runtimeOptions: try decoded.optionalStringArray("runtimeOption") ?? []
+                ),
+                name: decoded.requiredString("mount"),
+                session: session
+            )
+
+        case "mount.share":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["mount", "source", "destination", "option", "runtimeOption"]
+            )
+            return try ghostboxRegisterMount(
+                Containerization.Mount.share(
+                    source: decoded.requiredString("source"),
+                    destination: decoded.requiredString("destination"),
+                    options: try decoded.optionalStringArray("option") ?? [],
+                    runtimeOptions: try decoded.optionalStringArray("runtimeOption") ?? []
+                ),
+                name: decoded.requiredString("mount"),
+                session: session
+            )
+
+        case "mount.any":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["mount", "type", "source", "destination", "option", "runtimeOption"]
+            )
+            return try ghostboxRegisterMount(
+                Containerization.Mount.any(
+                    type: decoded.requiredString("type"),
+                    source: decoded.requiredString("source"),
+                    destination: decoded.requiredString("destination"),
+                    options: try decoded.optionalStringArray("option") ?? [],
+                    runtimeOptions: try decoded.optionalStringArray("runtimeOption") ?? []
+                ),
+                name: decoded.requiredString("mount"),
+                session: session
+            )
+
+        case "mount.sharedMount":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["mount", "name", "destination", "option"]
+            )
+            return try ghostboxRegisterMount(
+                Containerization.Mount.sharedMount(
+                    name: decoded.requiredString("name"),
+                    destination: decoded.requiredString("destination"),
+                    options: try decoded.optionalStringArray("option") ?? []
+                ),
+                name: decoded.requiredString("mount"),
+                session: session
+            )
+
+        case "mount.clone":
+            let decoded = try GhostboxParameters(parameters, allowed: ["mount", "to"])
+            let reference = try decoded.requiredReference("mount", expectedKind: "mount")
+            let mount: Containerization.Mount = try session.value(for: reference, expectedKind: "mount")
+            let destination = try decoded.requiredString("to")
+            let clone = try mount.clone(to: destination)
+            let name = ghostboxDerivedName(
+                reference: reference,
+                operation: "clone",
+                discriminator: destination
+            )
+            return try ghostboxRegisterMount(clone, name: name, session: session)
+
+        case GhostboxDirectMethod.mountDelete.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["mount"])
+            let reference = try decoded.requiredReference("mount", expectedKind: "mount")
+            let mount: Containerization.Mount = try session.value(for: reference, expectedKind: "mount")
+            try await session.unregisterAndCleanup(reference, expectedKind: "mount", matching: mount)
+            return .void
+
+        case "mount.isBlock", "mount.type", "mount.source", "mount.destination", "mount.options", "mount.runtimeOptions":
+            let decoded = try GhostboxParameters(parameters, allowed: ["mount"])
+            let reference = try decoded.requiredReference("mount", expectedKind: "mount")
+            let mount: Containerization.Mount = try session.value(for: reference, expectedKind: "mount")
+            switch method.rawValue {
+            case "mount.isBlock": return .boolean(mount.isBlock)
+            case "mount.type": return .string(mount.type)
+            case "mount.source":
+                if let store = session.contextValue(ghostboxVolumeStoreContextKey, as: GhostboxVolumeStore.self),
+                   let source = await store.redactedSource(for: reference) {
+                    return .string(source)
+                }
+                return .string(mount.source)
+            case "mount.destination": return .string(mount.destination)
+            case "mount.options": return .strings(mount.options)
+            default: return ghostboxMountRuntimeOptionsValue(mount.runtimeOptions)
+            }
+
+        default:
+            throw ghostboxUnsupportedBootMethod(method)
+        }
+    }
+}
+
+struct GhostboxBootLogCommands: GhostboxDomainHandler {
+    let resource = "bootLog"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "bootLog.file" else {
+            throw ghostboxUnsupportedBootMethod(method)
+        }
+        let decoded = try GhostboxParameters(parameters, allowed: ["bootLog", "path", "append"])
+        let bootLog = BootLog.file(
+            path: try ghostboxURL(decoded.requiredString("path"), parameter: "path"),
+            append: try decoded.optionalBool("append") ?? true
+        )
+        let reference = try session.register(
+            kind: "boot-log",
+            name: decoded.requiredString("bootLog"),
+            value: bootLog,
+            equivalent: { _, _ in false }
+        )
+        return .reference(reference)
+    }
+}
+
+enum GhostboxBootCommandHandlers {
+    static let all: [any GhostboxDomainHandler] = [
+        GhostboxKernelCommandLineCommands(),
+        GhostboxKernelCommands(),
+        GhostboxKernelImageCommands(),
+        GhostboxInitImageCommands(),
+        GhostboxMountCommands(),
+        GhostboxBootLogCommands(),
+    ]
+}
+
+private func ghostboxUnsupportedBootMethod(_ method: GhostboxDirectMethod) -> DirectDispatchError {
+    DirectDispatchError(.unsupported, "unsupported direct method '\(method.rawValue)'")
+}
+
+private func ghostboxLabels(_ assignments: [String]) throws -> [String: String] {
+    var result: [String: String] = [:]
+    for assignment in assignments {
+        guard let separator = assignment.firstIndex(of: "="), separator != assignment.startIndex else {
+            throw DirectDispatchError(.invalidArgument, "parameter 'label' values must use key=value")
+        }
+        let key = String(assignment[.. URL {
+    guard !raw.isEmpty, !raw.contains("\0") else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' must be a non-empty URL")
+    }
+    if let url = URL(string: raw), url.scheme != nil {
+        return url
+    }
+    return URL(filePath: raw)
+}
+
+private func ghostboxSystemPlatform(
+    _ parameters: [String: GhostboxJSONValue],
+    _ name: String
+) throws -> SystemPlatform {
+    guard let value = parameters[name] else {
+        throw DirectDispatchError(.invalidArgument, "missing required parameter '\(name)'")
+    }
+    let os: String
+    let architecture: String
+    switch value {
+    case .string(let raw):
+        let components = raw.split(separator: "/", omittingEmptySubsequences: false)
+        guard components.count == 2 else {
+            throw DirectDispatchError(.invalidArgument, "parameter '\(name)' must use os/architecture")
+        }
+        os = String(components[0])
+        architecture = String(components[1])
+    case .object(let object):
+        let unknown = Set(object.keys).subtracting(["os", "architecture"])
+        guard unknown.isEmpty else {
+            throw DirectDispatchError(.invalidArgument, "parameter '\(name)' has unknown field '\(unknown.sorted()[0])'")
+        }
+        guard case .string(let decodedOS)? = object["os"],
+              case .string(let decodedArchitecture)? = object["architecture"] else {
+            throw DirectDispatchError(.invalidArgument, "parameter '\(name)' requires string os and architecture fields")
+        }
+        os = decodedOS
+        architecture = decodedArchitecture
+    default:
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' must be an os/architecture string or object")
+    }
+    guard let decodedOS = SystemPlatform.OS(rawValue: os),
+          let decodedArchitecture = SystemPlatform.Architecture(rawValue: architecture) else {
+        throw DirectDispatchError(.invalidArgument, "unsupported system platform '\(os)/\(architecture)'")
+    }
+    return try JSONDecoder().decode(
+        SystemPlatform.self,
+        from: JSONEncoder().encode([
+            "os": decodedOS.rawValue,
+            "architecture": decodedArchitecture.rawValue,
+        ])
+    )
+}
+
+private func ghostboxOCIPlatform(
+    _ parameters: [String: GhostboxJSONValue],
+    _ name: String
+) throws -> ContainerizationOCI.Platform {
+    guard let value = parameters[name] else {
+        throw DirectDispatchError(.invalidArgument, "missing required parameter '\(name)'")
+    }
+    do {
+        switch value {
+        case .string(let raw) where raw.first == "{":
+            return try JSONDecoder().decode(ContainerizationOCI.Platform.self, from: Data(raw.utf8))
+        case .string(let raw):
+            return try ContainerizationOCI.Platform(from: raw)
+        case .object:
+            return try JSONDecoder().decode(
+                ContainerizationOCI.Platform.self,
+                from: JSONEncoder().encode(value)
+            )
+        default:
+            throw DirectDispatchError(.invalidArgument, "parameter '\(name)' must be a platform string or object")
+        }
+    } catch let error as DirectDispatchError {
+        throw error
+    } catch {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' is not a valid OCI platform: \(error.localizedDescription)")
+    }
+}
+
+private func ghostboxSystemPlatformValue(_ platform: SystemPlatform) -> GhostboxDirectValue {
+    .object([
+        "os": .string(platform.os.rawValue),
+        "architecture": .string(platform.architecture.rawValue),
+    ])
+}
+
+private func ghostboxMountRuntimeOptions(
+    _ parameters: [String: GhostboxJSONValue],
+    _ name: String
+) throws -> Containerization.Mount.RuntimeOptions {
+    guard let value = parameters[name] else {
+        throw DirectDispatchError(.invalidArgument, "missing required parameter '\(name)'")
+    }
+    let object: [String: GhostboxJSONValue]
+    switch value {
+    case .object(let decoded):
+        object = decoded
+    case .string(let raw):
+        do {
+            let decoded = try JSONDecoder().decode(GhostboxJSONValue.self, from: Data(raw.utf8))
+            guard case .object(let decodedObject) = decoded else {
+                throw DirectDispatchError(.invalidArgument, "parameter '\(name)' JSON must be an object")
+            }
+            object = decodedObject
+        } catch let error as DirectDispatchError {
+            throw error
+        } catch {
+            throw DirectDispatchError(.invalidArgument, "parameter '\(name)' is not valid JSON: \(error.localizedDescription)")
+        }
+    default:
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' must be a JSON object")
+    }
+
+    if object.isEmpty {
+        return .any([])
+    }
+    let unknown = Set(object.keys).subtracting(["kind", "options"])
+    guard unknown.isEmpty else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' has unknown field '\(unknown.sorted()[0])'")
+    }
+    guard case .string(let kind)? = object["kind"] else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' requires a string kind field")
+    }
+    let options: [String]
+    if let rawOptions = object["options"] {
+        options = try ghostboxStrings(rawOptions, parameter: "\(name).options")
+    } else {
+        options = []
+    }
+    switch kind {
+    case "virtioblk": return .virtioblk(options)
+    case "virtiofs": return .virtiofs(options)
+    case "shared":
+        guard options.isEmpty else {
+            throw DirectDispatchError(.invalidArgument, "shared runtime options cannot contain options")
+        }
+        return .shared
+    case "any": return .any(options)
+    default: throw DirectDispatchError(.invalidArgument, "unknown mount runtime options kind '\(kind)'")
+    }
+}
+
+private func ghostboxStrings(_ value: GhostboxJSONValue, parameter: String) throws -> [String] {
+    guard case .array(let values) = value else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' must be an array")
+    }
+    return try values.enumerated().map { index, value in
+        guard case .string(let string) = value else {
+            throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' element \(index) must be a string")
+        }
+        return string
+    }
+}
+
+private func ghostboxMountRuntimeOptionsValue(_ options: Containerization.Mount.RuntimeOptions) -> GhostboxDirectValue {
+    let kind: String
+    let values: [String]
+    switch options {
+    case .virtioblk(let options):
+        kind = "virtioblk"
+        values = options
+    case .virtiofs(let options):
+        kind = "virtiofs"
+        values = options
+    case .shared:
+        kind = "shared"
+        values = []
+    case .any(let options):
+        kind = "any"
+        values = options
+    }
+    return .object([
+        "kind": .string(kind),
+        "options": .strings(values),
+    ])
+}
+
+private func ghostboxRegisterKernelImage(
+    _ image: KernelImage,
+    name: String,
+    session: GhostboxSession
+) throws -> GhostboxDirectValue {
+    let reference = try session.register(
+        kind: "kernel-image",
+        name: name,
+        value: image,
+        equivalent: { $0.name == $1.name }
+    )
+    return .reference(reference)
+}
+
+private func ghostboxRegisterInitImage(
+    _ image: InitImage,
+    name: String,
+    session: GhostboxSession
+) throws -> GhostboxDirectValue {
+    let reference = try session.register(
+        kind: "init-image",
+        name: name,
+        value: image,
+        equivalent: { $0.name == $1.name }
+    )
+    return .reference(reference)
+}
+
+private func ghostboxRegisterMount(
+    _ mount: Containerization.Mount,
+    name: String,
+    session: GhostboxSession
+) throws -> GhostboxDirectValue {
+    let reference = try session.register(
+        kind: "mount",
+        name: name,
+        value: mount,
+        equivalent: ghostboxMountsEqual
+    )
+    return .reference(reference)
+}
+
+private func ghostboxCommandLinesEqual(_ lhs: Kernel.CommandLine, _ rhs: Kernel.CommandLine) -> Bool {
+    lhs.kernelArgs == rhs.kernelArgs && lhs.initArgs == rhs.initArgs
+}
+
+private func ghostboxKernelsEqual(_ lhs: Kernel, _ rhs: Kernel) -> Bool {
+    lhs.path == rhs.path
+        && lhs.platform.os == rhs.platform.os
+        && lhs.platform.architecture == rhs.platform.architecture
+        && ghostboxCommandLinesEqual(lhs.commandLine, rhs.commandLine)
+}
+
+private func ghostboxMountsEqual(_ lhs: Containerization.Mount, _ rhs: Containerization.Mount) -> Bool {
+    lhs.type == rhs.type
+        && lhs.source == rhs.source
+        && lhs.destination == rhs.destination
+        && lhs.options == rhs.options
+        && ghostboxMountRuntimeOptionsEqual(lhs.runtimeOptions, rhs.runtimeOptions)
+}
+
+private func ghostboxMountRuntimeOptionsEqual(
+    _ lhs: Containerization.Mount.RuntimeOptions,
+    _ rhs: Containerization.Mount.RuntimeOptions
+) -> Bool {
+    switch (lhs, rhs) {
+    case (.virtioblk(let lhs), .virtioblk(let rhs)): return lhs == rhs
+    case (.virtiofs(let lhs), .virtiofs(let rhs)): return lhs == rhs
+    case (.shared, .shared): return true
+    case (.any(let lhs), .any(let rhs)): return lhs == rhs
+    default: return false
+    }
+}
+
+private func ghostboxDerivedName(reference: String, operation: String, discriminator: String) -> String {
+    let rawName = reference.split(separator: "/", maxSplits: 1).last.map(String.init) ?? "object"
+    let prefix = rawName.prefix(80).map { character -> Character in
+        character.isLetter || character.isNumber || character == "." || character == "_" || character == "-" ? character : "-"
+    }
+    var hash: UInt64 = 14_695_981_039_346_656_037
+    for byte in "\(operation)|\(discriminator)".utf8 {
+        hash ^= UInt64(byte)
+        hash &*= 1_099_511_628_211
+    }
+    return "\(String(prefix))-\(operation)-\(String(hash, radix: 16))"
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBuiltinCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBuiltinCommands.swift
new file mode 100644
index 0000000..437034a
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxBuiltinCommands.swift
@@ -0,0 +1,947 @@
+import Containerization
+import ContainerizationOCI
+import ContainerizationOS
+import Foundation
+import GhostVMKit
+
+struct GhostboxDNSCommands: GhostboxDomainHandler {
+    let resource = "dns"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case GhostboxDirectMethod.dnsCreate.rawValue:
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["name", "nameservers", "domain", "searchDomains", "options"]
+            )
+            let dns = DNS(
+                nameservers: try decoded.optionalStringArray("nameservers") ?? DNS.defaultNameservers,
+                domain: try decoded.optionalString("domain"),
+                searchDomains: try decoded.optionalStringArray("searchDomains") ?? [],
+                options: try decoded.optionalStringArray("options") ?? []
+            )
+            let reference = try session.register(
+                kind: "dns",
+                name: decoded.requiredString("name"),
+                value: dns,
+                equivalent: ghostboxDNSEqual
+            )
+            return .reference(reference)
+
+        case GhostboxDirectMethod.dnsDefaultNameservers.rawValue:
+            _ = try GhostboxParameters(parameters, allowed: [])
+            return .strings(DNS.defaultNameservers)
+
+        case GhostboxDirectMethod.dnsDelete.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["dns"])
+            let reference = try decoded.requiredReference("dns", expectedKind: "dns")
+            let dns: DNS = try session.value(for: reference, expectedKind: "dns")
+            try session.unregister(reference, expectedKind: "dns", matching: dns)
+            return .void
+
+        case GhostboxDirectMethod.dnsValidate.rawValue,
+             GhostboxDirectMethod.dnsResolvConf.rawValue,
+             GhostboxDirectMethod.dnsNameservers.rawValue,
+             GhostboxDirectMethod.dnsDomain.rawValue,
+             GhostboxDirectMethod.dnsSearchDomains.rawValue,
+             GhostboxDirectMethod.dnsOptions.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["reference"])
+            let reference = try decoded.requiredReference("reference", expectedKind: "dns")
+            let dns: DNS = try session.value(for: reference, expectedKind: "dns")
+            switch method.rawValue {
+            case GhostboxDirectMethod.dnsValidate.rawValue:
+                try dns.validate()
+                return .void
+            case GhostboxDirectMethod.dnsResolvConf.rawValue:
+                return .string(dns.resolvConf)
+            case GhostboxDirectMethod.dnsNameservers.rawValue:
+                return .strings(dns.nameservers)
+            case GhostboxDirectMethod.dnsDomain.rawValue:
+                return dns.domain.map(GhostboxDirectValue.string) ?? .null
+            case GhostboxDirectMethod.dnsSearchDomains.rawValue:
+                return .strings(dns.searchDomains)
+            default:
+                return .strings(dns.options)
+            }
+
+        default:
+            throw unsupported(method)
+        }
+    }
+
+    private func unsupported(_ method: GhostboxDirectMethod) -> DirectDispatchError {
+        DirectDispatchError(.unsupported, "unsupported direct method '\(method.rawValue)'")
+    }
+}
+
+func ghostboxDNSEqual(_ lhs: DNS, _ rhs: DNS) -> Bool {
+    guard lhs.nameservers == rhs.nameservers else { return false }
+    guard lhs.domain == rhs.domain else { return false }
+    guard lhs.searchDomains == rhs.searchDomains else { return false }
+    return lhs.options == rhs.options
+}
+
+struct GhostboxProcessConfigCommands: GhostboxDomainHandler {
+    let resource = "processConfig"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "processConfig.defaultPath":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            return .string(LinuxProcessConfiguration.defaultPath)
+        case "processConfig.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: [
+                    "processConfig", "argument", "environment", "workingDirectory", "user", "rlimit",
+                    "noNewPrivileges", "capabilities", "terminal", "stdin", "stdout", "stderr",
+                ]
+            )
+            let rlimitReferences = try decoded.optionalReferences("rlimit", expectedKind: "rlimit") ?? []
+            let rlimits: [LinuxRLimit] = try rlimitReferences.map {
+                let record: GhostboxRLimitRecord = try session.value(for: $0, expectedKind: "rlimit")
+                return record.value
+            }
+            let capabilitiesReference: String
+            let capabilities: Containerization.LinuxCapabilities
+            if let supplied = try decoded.optionalReference("capabilities", expectedKind: "capabilities") {
+                capabilitiesReference = supplied
+                capabilities = try session.value(for: supplied, expectedKind: "capabilities")
+            } else {
+                capabilitiesReference = try registerDefaultCapabilities(session: session)
+                capabilities = .defaultOCICapabilities
+            }
+            let stdinReference = try decoded.optionalReference("stdin", expectedKind: "reader-stream")
+            let stdin: (any ReaderStream)? = try stdinReference.map {
+                try session.value(for: $0, expectedKind: "reader-stream", as: (any ReaderStream).self)
+            }
+            let stdoutReference = try decoded.optionalReference("stdout", expectedKind: "writer")
+            let stdout: (any Writer)? = try stdoutReference.map {
+                try session.value(for: $0, expectedKind: "writer", as: (any Writer).self)
+            }
+            let stderrReference = try decoded.optionalReference("stderr", expectedKind: "writer")
+            let stderr: (any Writer)? = try stderrReference.map {
+                try session.value(for: $0, expectedKind: "writer", as: (any Writer).self)
+            }
+            let user: ContainerizationOCI.User
+            if let object = try decoded.optionalObject("user") {
+                user = try ghostboxDecode(ContainerizationOCI.User.self, from: object, parameter: "user")
+            } else {
+                user = .init()
+            }
+            let configuration = LinuxProcessConfiguration(
+                arguments: try decoded.requiredStringArray("argument"),
+                environmentVariables: try decoded.optionalStringArray("environment")
+                    ?? ["PATH=\(LinuxProcessConfiguration.defaultPath)"],
+                workingDirectory: try decoded.optionalString("workingDirectory") ?? "/",
+                user: user,
+                rlimits: rlimits,
+                noNewPrivileges: try decoded.optionalBool("noNewPrivileges") ?? false,
+                capabilities: capabilities,
+                terminal: try decoded.optionalBool("terminal") ?? false,
+                stdin: stdin,
+                stdout: stdout,
+                stderr: stderr
+            )
+            return try register(
+                configuration,
+                references: GhostboxProcessReferences(
+                    rlimits: rlimitReferences,
+                    capabilities: capabilitiesReference,
+                    stdin: stdinReference,
+                    stdout: stdoutReference,
+                    stderr: stderrReference
+                ),
+                name: decoded.requiredString("processConfig"),
+                session: session
+            )
+        case "processConfig.fromImageConfig":
+            let decoded = try GhostboxParameters(parameters, allowed: ["processConfig", "imageConfig"])
+            let imageConfig = try ghostboxDecode(
+                ImageConfig.self,
+                from: decoded.requiredObject("imageConfig"),
+                parameter: "imageConfig"
+            )
+            let capabilitiesReference = try registerDefaultCapabilities(session: session)
+            return try register(
+                LinuxProcessConfiguration(from: imageConfig),
+                references: GhostboxProcessReferences(
+                    rlimits: [],
+                    capabilities: capabilitiesReference,
+                    stdin: nil,
+                    stdout: nil,
+                    stderr: nil
+                ),
+                name: decoded.requiredString("processConfig"),
+                session: session
+            )
+        case GhostboxDirectMethod.processConfigDelete.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["processConfig"])
+            let reference = try decoded.requiredReference("processConfig", expectedKind: "process-config")
+            let slot: GhostboxMutableSlot = try session.mutableValue(
+                for: reference,
+                expectedKind: "process-config"
+            )
+            try session.unregister(reference, expectedKind: "process-config", matching: slot)
+            return .void
+        case "processConfig.setTerminalIo":
+            let decoded = try GhostboxParameters(parameters, allowed: ["processConfig", "terminal"])
+            let reference = try decoded.requiredReference("processConfig", expectedKind: "process-config")
+            let terminalReference = try decoded.requiredReference("terminal", expectedKind: "terminal")
+            let endpoint: GhostboxProxyTerminal = try session.value(for: terminalReference, expectedKind: "terminal")
+            let terminal = endpoint.child
+            let name = ghostboxReferenceName(terminalReference)
+            let aliases = try session.registerAliases(
+                [(kind: "reader-stream", name: name), (kind: "writer", name: name)],
+                value: terminal,
+                equivalent: ghostboxTerminalEqual
+            )
+            let readerReference = aliases[0]
+            let writerReference = aliases[1]
+            try session.updateValue(for: reference, expectedKind: "process-config", as: GhostboxProcessConfigRecord.self) {
+                $0.configuration.setTerminalIO(terminal: terminal)
+                $0.references.stdin = readerReference
+                $0.references.stdout = writerReference
+            }
+            return .void
+        case "processConfig.arguments", "processConfig.environmentVariables", "processConfig.workingDirectory",
+             "processConfig.user", "processConfig.rlimits", "processConfig.noNewPrivileges",
+             "processConfig.capabilities", "processConfig.terminal", "processConfig.stdin",
+             "processConfig.stdout", "processConfig.stderr":
+            let decoded = try GhostboxParameters(parameters, allowed: ["processConfig"])
+            let reference = try decoded.requiredReference("processConfig", expectedKind: "process-config")
+            let record: GhostboxProcessConfigRecord = try session.valueSnapshot(
+                for: reference,
+                expectedKind: "process-config"
+            )
+            let configuration = record.configuration
+            switch method.rawValue {
+            case "processConfig.arguments": return .strings(configuration.arguments)
+            case "processConfig.environmentVariables": return .strings(configuration.environmentVariables)
+            case "processConfig.workingDirectory": return .string(configuration.workingDirectory)
+            case "processConfig.user": return try ghostboxEncodedValue(configuration.user)
+            case "processConfig.noNewPrivileges": return .boolean(configuration.noNewPrivileges)
+            case "processConfig.terminal": return .boolean(configuration.terminal)
+            default:
+                let references = record.references
+                switch method.rawValue {
+                case "processConfig.rlimits": return .references(references.rlimits)
+                case "processConfig.capabilities": return .reference(references.capabilities)
+                case "processConfig.stdin": return references.stdin.map(GhostboxDirectValue.reference) ?? .null
+                case "processConfig.stdout": return references.stdout.map(GhostboxDirectValue.reference) ?? .null
+                default: return references.stderr.map(GhostboxDirectValue.reference) ?? .null
+                }
+            }
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func register(
+        _ configuration: LinuxProcessConfiguration,
+        references: GhostboxProcessReferences,
+        name: String,
+        session: GhostboxSession
+    ) throws -> GhostboxDirectValue {
+        let reference = try session.registerMutable(
+            kind: "process-config",
+            name: name,
+            value: GhostboxProcessConfigRecord(configuration: configuration, references: references),
+            equivalent: {
+                ghostboxProcessConfigurationEqual($0.configuration, $1.configuration)
+                    && $0.references == $1.references
+            }
+        )
+        return .reference(reference)
+    }
+
+    private func registerDefaultCapabilities(session: GhostboxSession) throws -> String {
+        try session.register(
+            kind: "capabilities",
+            name: "default-oci",
+            value: Containerization.LinuxCapabilities.defaultOCICapabilities,
+            equivalent: ghostboxCapabilitiesEqual
+        )
+    }
+}
+
+struct GhostboxContainerCommands: GhostboxDomainHandler {
+    let resource = "container"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        _ = try GhostboxParameters(parameters, allowed: [])
+        switch method.rawValue {
+        case "container.defaultMounts":
+            let references = try LinuxContainer.defaultMounts().enumerated().map { index, mount in
+                try session.register(
+                    kind: "mount",
+                    name: "container-default-\(index)",
+                    value: mount,
+                    equivalent: ghostboxMountEqual
+                )
+            }
+            return .references(references)
+        case "container.defaultOCIMounts":
+            return .array(LinuxContainer.defaultOCIMounts().map(ghostboxMountValue))
+        case GhostboxDirectMethod.containerDefaultMaskedPaths.rawValue:
+            return .strings(LinuxContainer.defaultMaskedPaths())
+        case GhostboxDirectMethod.containerDefaultReadonlyPaths.rawValue:
+            return .strings(LinuxContainer.defaultReadonlyPaths())
+        case GhostboxDirectMethod.containerDefaultCopyChunkSize.rawValue:
+            return .integer(Int64(LinuxContainer.defaultCopyChunkSize))
+        case GhostboxDirectMethod.containerMaxIDLength.rawValue:
+            return .integer(Int64(LinuxContainer.maxIDLength))
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+private func ghostboxTerminalEqual(_ lhs: Terminal, _ rhs: Terminal) -> Bool {
+    lhs.handle === rhs.handle
+}
+
+private func ghostboxMountValue(_ mount: Containerization.Mount) -> GhostboxDirectValue {
+    .object([
+        "type": .string(mount.type),
+        "source": .string(mount.source),
+        "destination": .string(mount.destination),
+        "options": .strings(mount.options),
+    ])
+}
+
+protocol GhostboxIOAttachable: Sendable {
+    var attachmentStream: GhostboxIOStream { get }
+    func attach(fd: Int32) throws
+    func closeProxy()
+}
+
+struct GhostboxIOCommands: GhostboxDomainHandler {
+    let resource: String
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case GhostboxDirectMethod.readerStreamCreateProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["readerStream"])
+            let name = try decoded.requiredString("readerStream")
+            let endpoint = try GhostboxProxyReaderStream()
+            return .reference(try session.register(
+                kind: "reader-stream", name: name, value: endpoint,
+                equivalent: { $0 === $1 }, cleanupPriority: 100,
+                cancel: { $0.closeProxy() },
+                cleanup: { $0.closeProxy() }
+            ))
+        case GhostboxDirectMethod.writerCreateProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["writer"])
+            let name = try decoded.requiredString("writer")
+            let endpoint = try GhostboxProxyWriter()
+            return .reference(try session.register(
+                kind: "writer", name: name, value: endpoint,
+                equivalent: { $0 === $1 }, cleanupPriority: 100,
+                cancel: { $0.closeProxy() },
+                cleanup: { $0.closeProxy() }
+            ))
+        case GhostboxDirectMethod.terminalCreateProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["terminal", "width", "height"])
+            let name = try decoded.requiredString("terminal")
+            let endpoint = try GhostboxProxyTerminal(
+                width: decoded.requiredInteger("width", as: UInt16.self),
+                height: decoded.requiredInteger("height", as: UInt16.self)
+            )
+            return .reference(try session.register(
+                kind: "terminal", name: name, value: endpoint,
+                equivalent: { $0 === $1 }, cleanupPriority: 100,
+                cancel: { $0.closeProxy() },
+                cleanup: { $0.closeProxy() }
+            ))
+        case GhostboxDirectMethod.readerStreamCloseProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["readerStream"])
+            let reference = try decoded.requiredReference("readerStream", expectedKind: "reader-stream")
+            let endpoint: GhostboxProxyReaderStream = try session.value(
+                for: reference,
+                expectedKind: "reader-stream"
+            )
+            endpoint.closeProxy()
+            try session.unregister(reference, expectedKind: "reader-stream", matching: endpoint)
+            return .void
+        case GhostboxDirectMethod.writerCloseProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["writer"])
+            let reference = try decoded.requiredReference("writer", expectedKind: "writer")
+            let endpoint: GhostboxProxyWriter = try session.value(
+                for: reference, expectedKind: "writer"
+            )
+            endpoint.closeProxy()
+            try session.unregister(reference, expectedKind: "writer", matching: endpoint)
+            return .void
+        case GhostboxDirectMethod.terminalCloseProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["terminal"])
+            let reference = try decoded.requiredReference("terminal", expectedKind: "terminal")
+            let endpoint: GhostboxProxyTerminal = try session.value(
+                for: reference, expectedKind: "terminal"
+            )
+            endpoint.closeProxy()
+            let name = ghostboxReferenceName(reference)
+            try session.unregister(reference, expectedKind: "terminal", matching: endpoint)
+            try session.unregister(
+                GhostboxReference.canonical(kind: "reader-stream", name: name),
+                expectedKind: "reader-stream",
+                matching: endpoint.child
+            )
+            try session.unregister(
+                GhostboxReference.canonical(kind: "writer", name: name),
+                expectedKind: "writer",
+                matching: endpoint.child
+            )
+            return .void
+        case GhostboxDirectMethod.terminalWaitAttachedProxy.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["terminal"])
+            let endpoint: GhostboxProxyTerminal = try session.value(
+                for: decoded.requiredReference("terminal", expectedKind: "terminal"), expectedKind: "terminal"
+            )
+            try await endpoint.waitAttached()
+            return .void
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+func ghostboxIOAttachment(
+    method: GhostboxDirectMethod,
+    parameters: [String: GhostboxJSONValue],
+    session: GhostboxSession
+) throws -> any GhostboxIOAttachable {
+    switch method.rawValue {
+    case GhostboxDirectMethod.readerStreamAttachProxy.rawValue:
+        let decoded = try GhostboxParameters(parameters, allowed: ["readerStream"])
+        return try session.value(
+            for: decoded.requiredReference("readerStream", expectedKind: "reader-stream"),
+            expectedKind: "reader-stream",
+            as: GhostboxProxyReaderStream.self
+        )
+    case GhostboxDirectMethod.writerAttachProxy.rawValue:
+        let decoded = try GhostboxParameters(parameters, allowed: ["writer"])
+        return try session.value(
+            for: decoded.requiredReference("writer", expectedKind: "writer"),
+            expectedKind: "writer",
+            as: GhostboxProxyWriter.self
+        )
+    case GhostboxDirectMethod.terminalAttachProxy.rawValue:
+        let decoded = try GhostboxParameters(parameters, allowed: ["terminal", "resizeTarget"])
+        let endpoint: GhostboxProxyTerminal = try session.value(
+            for: decoded.requiredReference("terminal", expectedKind: "terminal"),
+            expectedKind: "terminal",
+            as: GhostboxProxyTerminal.self
+        )
+        if let target = try decoded.optionalString("resizeTarget") {
+            let relay: GhostboxTerminalResizeRelay
+            if target.hasPrefix("@container/") {
+                let record: GhostboxContainerRecord = try session.value(for: target, expectedKind: "container")
+                relay = GhostboxTerminalResizeRelay(container: record.value)
+            } else if target.hasPrefix("@process/") {
+                let process: LinuxProcess = try session.value(for: target, expectedKind: "process")
+                relay = GhostboxTerminalResizeRelay(process: process)
+            } else {
+                throw DirectDispatchError(.invalidArgument, "resizeTarget must be an @container/NAME or @process/NAME reference")
+            }
+            try endpoint.setResizeHandler { width, height in
+                Task { await relay.resize(width: width, height: height) }
+            }
+            try endpoint.setExitWatcher {
+                await relay.waitUntilExited()
+            }
+        }
+        return endpoint
+    default:
+        throw ghostboxUnsupported(method)
+    }
+}
+
+final class GhostboxProxyReaderStream: ReaderStream, GhostboxIOAttachable, @unchecked Sendable {
+    let attachmentStream = GhostboxIOStream.input
+
+    private let lock = NSLock()
+    private let sourceHandle: FileHandle
+    private var sourceFD: Int32
+    private var producerFD: Int32
+    private var attachedFD: Int32 = -1
+    private var attachmentUsed = false
+    private var producerFinished = false
+    private var cancelled = false
+    private var streamUsed = false
+
+    init() throws {
+        let pair = try ghostboxSocketPair()
+        sourceFD = pair.0
+        producerFD = pair.1
+        sourceHandle = FileHandle(fileDescriptor: pair.0, closeOnDealloc: false)
+    }
+
+    func stream() -> AsyncStream {
+        AsyncStream { continuation in
+            let mayStart = lock.withLock {
+                guard !streamUsed, !cancelled else { return false }
+                streamUsed = true
+                return true
+            }
+            guard mayStart else {
+                continuation.finish()
+                return
+            }
+            sourceHandle.readabilityHandler = { [weak self] handle in
+                let data = handle.availableData
+                if data.isEmpty {
+                    handle.readabilityHandler = nil
+                    continuation.finish()
+                } else {
+                    continuation.yield(data)
+                }
+            }
+            continuation.onTermination = { [weak self] _ in
+                self?.sourceHandle.readabilityHandler = nil
+                self?.closeProxy()
+            }
+        }
+    }
+
+    func attach(fd: Int32) throws {
+        try beginAttachment(fd: fd)
+        defer { lock.withLock { attachedFD = -1 } }
+        let reader = GhostboxRuntimeLineReader(fd: fd)
+        while let line = try reader.readLine() {
+            let frame = try GhostboxIOFrame.decode(line: line)
+            switch frame.type {
+            case .data where frame.stream == .input:
+                guard let data = frame.data, ghostboxWriteAll(fd: producerDescriptor(), data) else {
+                    throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EPIPE)
+                }
+            case .eof where frame.stream == .input:
+                finishInput()
+                _ = ghostboxWriteAll(fd: fd, try GhostboxIOFrame.eof(.input).encodeLine())
+                return
+            default:
+                throw DirectDispatchError(.invalidArgument, "unexpected frame for reader-stream attachment")
+            }
+        }
+        finishInput()
+    }
+
+    func closeProxy() {
+        let descriptor = lock.withLock { () -> Int32 in
+            guard !cancelled else { return -1 }
+            cancelled = true
+            let attached = attachedFD
+            _ = Darwin.shutdown(producerFD, SHUT_WR)
+            return attached
+        }
+        if descriptor >= 0 { _ = Darwin.shutdown(descriptor, SHUT_RD) }
+    }
+
+    deinit {
+        sourceHandle.readabilityHandler = nil
+        Darwin.close(sourceFD)
+        Darwin.close(producerFD)
+    }
+
+    private func beginAttachment(fd: Int32) throws {
+        try lock.withLock {
+            guard !attachmentUsed, !producerFinished, !cancelled else {
+                throw DirectDispatchError(.failedPrecondition, "reader-stream proxy is already attached or closed")
+            }
+            attachmentUsed = true
+            attachedFD = fd
+        }
+    }
+
+    private func producerDescriptor() -> Int32 {
+        lock.withLock { producerFinished || cancelled ? -1 : producerFD }
+    }
+
+    private func finishInput() {
+        lock.withLock {
+            guard !producerFinished, !cancelled else { return }
+            producerFinished = true
+            _ = Darwin.shutdown(producerFD, SHUT_WR)
+        }
+    }
+}
+
+final class GhostboxProxyWriter: Writer, GhostboxIOAttachable, @unchecked Sendable {
+    let attachmentStream = GhostboxIOStream.output
+
+    private let lock = NSLock()
+    private let writeLock = NSLock()
+    private var writerFD: Int32
+    private var consumerFD: Int32
+    private var attachmentUsed = false
+    private var closed = false
+
+    init() throws {
+        let pair = try ghostboxSocketPair()
+        writerFD = pair.0
+        consumerFD = pair.1
+    }
+
+    func write(_ data: Data) throws {
+        guard !data.isEmpty else { return }
+        let descriptor = lock.withLock { closed ? -1 : writerFD }
+        guard descriptor >= 0 else { throw POSIXError(.EPIPE) }
+        try writeLock.withLock {
+            guard ghostboxWriteAll(fd: descriptor, data) else {
+                throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EPIPE)
+            }
+        }
+    }
+
+    func close() throws {
+        closeProxy()
+    }
+
+    func attach(fd: Int32) throws {
+        try lock.withLock {
+            guard !attachmentUsed else {
+                throw DirectDispatchError(.failedPrecondition, "writer proxy is already attached")
+            }
+            attachmentUsed = true
+        }
+        var buffer = [UInt8](repeating: 0, count: GhostboxDirectLimits.ioFrameDataBytes)
+        while true {
+            let count = Darwin.read(consumerFD, &buffer, buffer.count)
+            if count > 0 {
+                let frame = GhostboxIOFrame.data(Data(buffer[0.. Void)?
+    private var exitWatcher: Task?
+
+    init(width: UInt16, height: UInt16) throws {
+        guard width > 0, height > 0 else {
+            throw DirectDispatchError(.invalidArgument, "terminal dimensions must be greater than zero")
+        }
+        let pair = try Terminal.create(initialSize: .init(width: width, height: height))
+        let cancellation = try ghostboxSocketPair()
+        parent = pair.parent
+        child = pair.child
+        cancellationReadFD = cancellation.0
+        cancellationWriteFD = cancellation.1
+        var attributes = termios()
+        guard tcgetattr(child.handle.fileDescriptor, &attributes) == 0 else {
+            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+        }
+        cfmakeraw(&attributes)
+        attributes.c_oflag |= tcflag_t(OPOST)
+        guard tcsetattr(child.handle.fileDescriptor, TCSANOW, &attributes) == 0 else {
+            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+        }
+    }
+
+    func attach(fd: Int32) throws {
+        try lock.withLock {
+            guard !attachmentUsed, !closed else {
+                throw DirectDispatchError(.failedPrecondition, "terminal proxy is already attached or closed")
+            }
+            attachmentUsed = true
+        }
+
+        let inputDone = DispatchGroup()
+        let inputError = GhostboxAttachmentErrorBox()
+        inputDone.enter()
+        DispatchQueue.global(qos: .userInitiated).async { [self] in
+            defer { inputDone.leave() }
+            do {
+                let reader = GhostboxRuntimeLineReader(fd: fd)
+                var receivedEOF = false
+                while let line = try reader.readLine() {
+                    let frame = try GhostboxIOFrame.decode(line: line)
+                    switch frame.type {
+                    case .data where frame.stream == .terminal:
+                        guard let data = frame.data,
+                              ghostboxWriteAll(fd: parent.handle.fileDescriptor, data) else {
+                            throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EPIPE)
+                        }
+                    case .resize where frame.stream == .terminal:
+                        try child.resize(width: frame.columns!, height: frame.rows!)
+                        readiness.markReady()
+                        lock.withLock { resizeHandler }?(frame.columns!, frame.rows!)
+                    case .eof where frame.stream == .terminal:
+                        receivedEOF = true
+                        return
+                    default:
+                        throw DirectDispatchError(.invalidArgument, "unexpected frame for terminal attachment")
+                    }
+                }
+                if !receivedEOF { closeProxy() }
+            } catch {
+                inputError.set(error)
+                closeProxy()
+            }
+        }
+
+        var buffer = [UInt8](repeating: 0, count: GhostboxDirectLimits.ioFrameDataBytes)
+        outputLoop: while true {
+            var descriptors = [
+                pollfd(fd: parent.handle.fileDescriptor, events: Int16(POLLIN | POLLHUP | POLLERR), revents: 0),
+                pollfd(fd: cancellationReadFD, events: Int16(POLLIN | POLLHUP | POLLERR), revents: 0),
+            ]
+            let status = Darwin.poll(&descriptors, nfds_t(descriptors.count), -1)
+            if status < 0, errno == EINTR { continue }
+            if status < 0 || descriptors[1].revents != 0 { break }
+            if descriptors[0].revents == 0 { continue }
+            while true {
+                let count = Darwin.read(parent.handle.fileDescriptor, &buffer, buffer.count)
+                if count > 0 {
+                    let frame = GhostboxIOFrame.data(Data(buffer[0.. (closeImmediately: Bool, watcher: Task?) in
+            guard !closed else { return (false, nil) }
+            closed = true
+            let watcher = exitWatcher
+            exitWatcher = nil
+            return (!attachmentUsed, watcher)
+        }
+        result.watcher?.cancel()
+        readiness.close()
+        if result.closeImmediately {
+            closeTerminalDescriptors()
+        } else {
+            _ = ghostboxWriteAll(fd: cancellationWriteFD, Data([1]))
+        }
+    }
+
+    func waitAttached() async throws {
+        try await readiness.wait()
+    }
+
+    func setResizeHandler(_ handler: @escaping @Sendable (UInt16, UInt16) -> Void) throws {
+        try lock.withLock {
+            guard !attachmentUsed, !closed else {
+                throw DirectDispatchError(.failedPrecondition, "terminal proxy is already attached or closed")
+            }
+            resizeHandler = handler
+        }
+    }
+
+    func setExitWatcher(_ waitUntilExited: @escaping @Sendable () async -> Void) throws {
+        try lock.withLock {
+            guard !attachmentUsed, !closed, exitWatcher == nil else {
+                throw DirectDispatchError(.failedPrecondition, "terminal proxy lifecycle is already attached or closed")
+            }
+            exitWatcher = Task { [weak self] in
+                await waitUntilExited()
+                guard !Task.isCancelled else { return }
+                self?.closeProxy()
+            }
+        }
+    }
+
+    deinit {
+        closeProxy()
+        closeTerminalDescriptors()
+        Darwin.close(cancellationReadFD)
+        Darwin.close(cancellationWriteFD)
+    }
+
+    private func closeTerminalDescriptors() {
+        let shouldClose = lock.withLock {
+            guard !terminalsClosed else { return false }
+            terminalsClosed = true
+            return true
+        }
+        if shouldClose {
+            try? parent.close()
+            try? child.close()
+        }
+    }
+}
+
+private actor GhostboxTerminalResizeRelay {
+    private enum Target: Sendable {
+        case container(LinuxContainer)
+        case process(LinuxProcess)
+    }
+
+    private let target: Target
+
+    init(container: LinuxContainer) {
+        target = .container(container)
+    }
+
+    init(process: LinuxProcess) {
+        target = .process(process)
+    }
+
+    func resize(width: UInt16, height: UInt16) async {
+        let size = Terminal.Size(width: width, height: height)
+        switch target {
+        case .container(let container): try? await container.resize(to: size)
+        case .process(let process): try? await process.resize(to: size)
+        }
+    }
+
+    func waitUntilExited() async {
+        switch target {
+        case .container(let container):
+            while !Task.isCancelled {
+                do {
+                    let statistics = try await container.statistics(categories: .process)
+                    if statistics.process?.current == 0 { return }
+                } catch {
+                    // The attachment may be established before the container starts.
+                }
+                try? await Task.sleep(for: .milliseconds(100))
+            }
+        case .process(let process):
+            while process.pid < 0, !Task.isCancelled {
+                try? await Task.sleep(for: .milliseconds(100))
+            }
+            guard !Task.isCancelled else { return }
+            _ = try? await process.wait()
+        }
+    }
+}
+
+private final class GhostboxAttachmentErrorBox: @unchecked Sendable {
+    private let lock = NSLock()
+    private var stored: Error?
+
+    var value: Error? { lock.withLock { stored } }
+    func set(_ error: Error) { lock.withLock { stored = error } }
+}
+
+private final class GhostboxRuntimeLineReader {
+    private let fd: Int32
+    private var buffer = [UInt8]()
+
+    init(fd: Int32) {
+        self.fd = fd
+        buffer.reserveCapacity(4096)
+    }
+
+    func readLine() throws -> Data? {
+        while true {
+            if let newline = buffer.firstIndex(of: 0x0A) {
+                guard newline <= GhostboxDirectLimits.ioFrameLineBytes else {
+                    throw ContainerProtocolError.requestTooLarge(limit: GhostboxDirectLimits.ioFrameLineBytes)
+                }
+                let line = Data(buffer[.. 0 {
+                buffer.append(contentsOf: chunk[0.. (Int32, Int32) {
+    var descriptors = [Int32](repeating: -1, count: 2)
+    guard socketpair(AF_UNIX, SOCK_STREAM, 0, &descriptors) == 0 else {
+        throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO)
+    }
+    return (descriptors[0], descriptors[1])
+}
+
+@discardableResult
+func ghostboxWriteAll(fd: Int32, _ data: Data) -> Bool {
+    guard fd >= 0 else { return false }
+    var offset = 0
+    return data.withUnsafeBytes { bytes in
+        while offset < bytes.count {
+            let count = Darwin.write(fd, bytes.baseAddress! + offset, bytes.count - offset)
+            if count > 0 {
+                offset += count
+            } else if count < 0, errno == EINTR {
+                continue
+            } else {
+                return false
+            }
+        }
+        return true
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxConfigurationCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxConfigurationCommands.swift
new file mode 100644
index 0000000..dbf799b
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxConfigurationCommands.swift
@@ -0,0 +1,625 @@
+import Containerization
+import ContainerizationOCI
+import ContainerizationOS
+import Foundation
+import GhostVMKit
+import SystemPackage
+
+struct GhostboxHostsEntryCommands: GhostboxDomainHandler {
+    let resource = "hostsEntry"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "hostsEntry.create":
+            let decoded = try GhostboxParameters(parameters, allowed: ["hostsEntry", "ipAddress", "hostname", "comment"])
+            return try register(
+                Hosts.Entry(
+                    ipAddress: decoded.requiredString("ipAddress"),
+                    hostnames: decoded.requiredStringArray("hostname"),
+                    comment: try decoded.optionalString("comment")
+                ),
+                name: decoded.requiredString("hostsEntry"),
+                session: session
+            )
+        case "hostsEntry.localhostIpv4", "hostsEntry.localhostIpv6", "hostsEntry.ipv6Localnet",
+             "hostsEntry.ipv6Mcastprefix", "hostsEntry.ipv6Allnodes", "hostsEntry.ipv6Allrouters":
+            let decoded = try GhostboxParameters(parameters, allowed: ["hostsEntry", "comment"])
+            let comment = try decoded.optionalString("comment")
+            let entry: Hosts.Entry
+            switch method.rawValue {
+            case "hostsEntry.localhostIpv4": entry = .localHostIPV4(comment: comment)
+            case "hostsEntry.localhostIpv6": entry = .localHostIPV6(comment: comment)
+            case "hostsEntry.ipv6Localnet": entry = .ipv6LocalNet(comment: comment)
+            case "hostsEntry.ipv6Mcastprefix": entry = .ipv6MulticastPrefix(comment: comment)
+            case "hostsEntry.ipv6Allnodes": entry = .ipv6AllNodes(comment: comment)
+            default: entry = .ipv6AllRouters(comment: comment)
+            }
+            return try register(entry, name: decoded.requiredString("hostsEntry"), session: session)
+        case "hostsEntry.rendered", "hostsEntry.ipAddress", "hostsEntry.hostnames", "hostsEntry.comment":
+            let decoded = try GhostboxParameters(parameters, allowed: ["hostsEntry"])
+            let reference = try decoded.requiredReference("hostsEntry", expectedKind: "hosts-entry")
+            let entry: Hosts.Entry = try session.value(for: reference, expectedKind: "hosts-entry")
+            switch method.rawValue {
+            case "hostsEntry.rendered": return .string(entry.rendered)
+            case "hostsEntry.ipAddress": return .string(entry.ipAddress)
+            case "hostsEntry.hostnames": return .strings(entry.hostnames)
+            default: return entry.comment.map(GhostboxDirectValue.string) ?? .null
+            }
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func register(_ entry: Hosts.Entry, name: String, session: GhostboxSession) throws -> GhostboxDirectValue {
+        let reference = try session.register(kind: "hosts-entry", name: name, value: entry, equivalent: ghostboxHostsEntryEqual)
+        return .reference(reference)
+    }
+}
+
+struct GhostboxHostsCommands: GhostboxDomainHandler {
+    let resource = "hosts"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "hosts.create":
+            let decoded = try GhostboxParameters(parameters, allowed: ["hosts", "entry", "comment"])
+            let entryReferences = try decoded.optionalReferences("entry", expectedKind: "hosts-entry") ?? []
+            let entries: [Hosts.Entry] = try entryReferences.map { try session.value(for: $0, expectedKind: "hosts-entry") }
+            let record = GhostboxHostsRecord(
+                value: Hosts(entries: entries, comment: try decoded.optionalString("comment")),
+                entryReferences: entryReferences
+            )
+            return try register(record, name: decoded.requiredString("hosts"), session: session)
+        case "hosts.default":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            let entries = Hosts.default.entries
+            let entryReferences = try entries.enumerated().map { index, entry in
+                try session.register(
+                    kind: "hosts-entry",
+                    name: "default-\(index)",
+                    value: entry,
+                    equivalent: ghostboxHostsEntryEqual
+                )
+            }
+            return try register(
+                GhostboxHostsRecord(value: .default, entryReferences: entryReferences),
+                name: "default",
+                session: session
+            )
+        case "hosts.hostsFile", "hosts.entries", "hosts.comment":
+            let decoded = try GhostboxParameters(parameters, allowed: ["hosts"])
+            let reference = try decoded.requiredReference("hosts", expectedKind: "hosts")
+            let record: GhostboxHostsRecord = try session.value(for: reference, expectedKind: "hosts")
+            switch method.rawValue {
+            case "hosts.hostsFile": return .string(record.value.hostsFile)
+            case "hosts.entries": return .references(record.entryReferences)
+            default: return record.value.comment.map(GhostboxDirectValue.string) ?? .null
+            }
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func register(_ record: GhostboxHostsRecord, name: String, session: GhostboxSession) throws -> GhostboxDirectValue {
+        let reference = try session.register(kind: "hosts", name: name, value: record, equivalent: ghostboxHostsRecordEqual)
+        return .reference(reference)
+    }
+}
+
+struct GhostboxSocketCommands: GhostboxDomainHandler {
+    let resource = "socket"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "socket.create":
+            let decoded = try GhostboxParameters(parameters, allowed: ["socket", "source", "destination", "permissions", "direction"])
+            let direction: UnixSocketConfiguration.Direction
+            switch try decoded.optionalString("direction") ?? "into" {
+            case "into": direction = .into
+            case "out-of": direction = .outOf
+            case let value:
+                throw DirectDispatchError(.invalidArgument, "invalid socket direction '\(value)'")
+            }
+            let socket = UnixSocketConfiguration(
+                source: ghostboxFileURL(try decoded.requiredString("source")),
+                destination: ghostboxFileURL(try decoded.requiredString("destination")),
+                permissions: try ghostboxPermissions(parameters["permissions"]),
+                direction: direction
+            )
+            let reference = try session.register(
+                kind: "socket",
+                name: decoded.requiredString("socket"),
+                value: socket,
+                equivalent: ghostboxSocketEqual
+            )
+            return .reference(reference)
+        case "socket.id", "socket.source", "socket.destination", "socket.permissions", "socket.direction":
+            let decoded = try GhostboxParameters(parameters, allowed: ["socket"])
+            let reference = try decoded.requiredReference("socket", expectedKind: "socket")
+            let socket: UnixSocketConfiguration = try session.value(for: reference, expectedKind: "socket")
+            switch method.rawValue {
+            case "socket.id": return .string(socket.id)
+            case "socket.source": return .string(socket.source.path)
+            case "socket.destination": return .string(socket.destination.path)
+            case "socket.permissions":
+                return socket.permissions.map { .unsignedInteger(UInt64($0.rawValue)) } ?? .null
+            default: return .string(ghostboxDirectionString(socket.direction))
+            }
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+struct GhostboxRLimitKindCommands: GhostboxDomainHandler {
+    let resource = "rlimitKind"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "rlimitKind.create" else { throw ghostboxUnsupported(method) }
+        let decoded = try GhostboxParameters(parameters, allowed: ["rlimitKind", "ociName"])
+        let kind = try LinuxRLimit.Kind(decoded.requiredString("ociName"))
+        let reference = try session.register(
+            kind: "rlimit-kind",
+            name: decoded.requiredString("rlimitKind"),
+            value: kind,
+            equivalent: ==
+        )
+        return .reference(reference)
+    }
+}
+
+struct GhostboxRLimitCommands: GhostboxDomainHandler {
+    let resource = "rlimit"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "rlimit.create", "rlimit.createEqual":
+            let allowed: Set = method.rawValue == "rlimit.create"
+                ? ["rlimit", "kind", "hard", "soft"]
+                : ["rlimit", "kind", "limit"]
+            let decoded = try GhostboxParameters(parameters, allowed: allowed)
+            let kindReference = try decoded.requiredReference("kind", expectedKind: "rlimit-kind")
+            let kind: LinuxRLimit.Kind = try session.value(for: kindReference, expectedKind: "rlimit-kind")
+            let value: LinuxRLimit
+            if method.rawValue == "rlimit.create" {
+                value = LinuxRLimit(
+                    kind: kind,
+                    hard: try decoded.requiredUInt64("hard"),
+                    soft: try decoded.requiredUInt64("soft")
+                )
+            } else {
+                value = LinuxRLimit(kind: kind, limit: try decoded.requiredUInt64("limit"))
+            }
+            let reference = try session.register(
+                kind: "rlimit",
+                name: decoded.requiredString("rlimit"),
+                value: GhostboxRLimitRecord(value: value, kindReference: kindReference),
+                equivalent: ==
+            )
+            return .reference(reference)
+        case "rlimit.kind", "rlimit.hard", "rlimit.soft", "rlimit.toOCI":
+            let decoded = try GhostboxParameters(parameters, allowed: ["rlimit"])
+            let reference = try decoded.requiredReference("rlimit", expectedKind: "rlimit")
+            let record: GhostboxRLimitRecord = try session.value(for: reference, expectedKind: "rlimit")
+            switch method.rawValue {
+            case "rlimit.kind": return .reference(record.kindReference)
+            case "rlimit.hard": return .unsignedInteger(record.value.hard)
+            case "rlimit.soft": return .unsignedInteger(record.value.soft)
+            default: return try ghostboxEncodedValue(record.value.toOCI())
+            }
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+struct GhostboxCapabilitiesCommands: GhostboxDomainHandler {
+    let resource = "capabilities"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "capabilities.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["capabilities", "bounding", "effective", "inheritable", "permitted", "ambient"]
+            )
+            let capabilities = Containerization.LinuxCapabilities(
+                bounding: try ghostboxCapabilities(decoded.optionalStringArray("bounding") ?? []),
+                effective: try ghostboxCapabilities(decoded.optionalStringArray("effective") ?? []),
+                inheritable: try ghostboxCapabilities(decoded.optionalStringArray("inheritable") ?? []),
+                permitted: try ghostboxCapabilities(decoded.optionalStringArray("permitted") ?? []),
+                ambient: try ghostboxCapabilities(decoded.optionalStringArray("ambient") ?? [])
+            )
+            return try register(capabilities, name: decoded.requiredString("capabilities"), session: session)
+        case "capabilities.createUniform":
+            let decoded = try GhostboxParameters(parameters, allowed: ["capabilities", "capability"])
+            return try register(
+                Containerization.LinuxCapabilities(
+                    capabilities: try ghostboxCapabilities(decoded.requiredStringArray("capability"))
+                ),
+                name: decoded.requiredString("capabilities"),
+                session: session
+            )
+        case "capabilities.all", "capabilities.defaultOCI":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            let isAll = method.rawValue == "capabilities.all"
+            return try register(
+                isAll ? .allCapabilities : .defaultOCICapabilities,
+                name: isAll ? "all" : "default-oci",
+                session: session
+            )
+        case "capabilities.bounding", "capabilities.effective", "capabilities.inheritable",
+             "capabilities.permitted", "capabilities.ambient", "capabilities.toOCI":
+            let decoded = try GhostboxParameters(parameters, allowed: ["capabilities"])
+            let reference = try decoded.requiredReference("capabilities", expectedKind: "capabilities")
+            let capabilities: Containerization.LinuxCapabilities = try session.value(
+                for: reference,
+                expectedKind: "capabilities"
+            )
+            switch method.rawValue {
+            case "capabilities.bounding": return .strings(capabilities.bounding.map(\.description))
+            case "capabilities.effective": return .strings(capabilities.effective.map(\.description))
+            case "capabilities.inheritable": return .strings(capabilities.inheritable.map(\.description))
+            case "capabilities.permitted": return .strings(capabilities.permitted.map(\.description))
+            case "capabilities.ambient": return .strings(capabilities.ambient.map(\.description))
+            default: return try ghostboxEncodedValue(capabilities.toOCI())
+            }
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func register(
+        _ capabilities: Containerization.LinuxCapabilities,
+        name: String,
+        session: GhostboxSession
+    ) throws -> GhostboxDirectValue {
+        let reference = try session.register(
+            kind: "capabilities",
+            name: name,
+            value: capabilities,
+            equivalent: ghostboxCapabilitiesEqual
+        )
+        return .reference(reference)
+    }
+}
+
+struct GhostboxContainerConfigCommands: GhostboxDomainHandler {
+    let resource = "containerConfig"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "containerConfig.createDefault":
+            let decoded = try GhostboxParameters(parameters, allowed: ["containerConfig"])
+            return try register(.init(), name: decoded.requiredString("containerConfig"), session: session)
+        case "containerConfig.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: [
+                    "containerConfig", "process", "cpus", "memory", "hostname", "sysctl", "interface", "socket", "mount",
+                    "maskedPath", "readonlyPath", "dns", "hosts", "virtualization", "bootLog", "ociRuntimePath",
+                    "useInit", "cpuOverhead", "memoryOverhead",
+                ]
+            )
+            let processReference = try decoded.requiredReference("process", expectedKind: "process-config")
+            let process = try ghostboxProcessConfiguration(processReference, session: session)
+            let interfaceReferences = try decoded.optionalReferences("interface", expectedKind: "interface") ?? []
+            let interfaces: [any Interface] = try interfaceReferences.map {
+                try session.value(for: $0, expectedKind: "interface", as: (any Interface).self)
+            }
+            let socketReferences = try decoded.optionalReferences("socket", expectedKind: "socket") ?? []
+            let sockets: [UnixSocketConfiguration] = try socketReferences.map {
+                try session.value(for: $0, expectedKind: "socket")
+            }
+            let mountReferences = try decoded.optionalReferences("mount", expectedKind: "mount") ?? []
+            let mounts: [Containerization.Mount] = try mountReferences.map {
+                try session.value(for: $0, expectedKind: "mount")
+            }
+            let dns: DNS? = try decoded.optionalReference("dns", expectedKind: "dns").map {
+                try session.value(for: $0, expectedKind: "dns")
+            }
+            let hosts: Hosts? = try decoded.optionalReference("hosts", expectedKind: "hosts").map {
+                let record: GhostboxHostsRecord = try session.value(for: $0, expectedKind: "hosts")
+                return record.value
+            }
+            let bootLog: BootLog? = try decoded.optionalReference("bootLog", expectedKind: "boot-log").map {
+                try session.value(for: $0, expectedKind: "boot-log")
+            }
+            let config = LinuxContainer.Configuration(
+                process: process,
+                cpus: try decoded.optionalInt("cpus") ?? 4,
+                memoryInBytes: try decoded.optionalUInt64("memory") ?? 1_073_741_824,
+                hostname: try decoded.optionalString("hostname"),
+                sysctl: try ghostboxSysctls(decoded.optionalStringArray("sysctl") ?? []),
+                interfaces: interfaces,
+                sockets: sockets,
+                mounts: parameters["mount"] == nil ? LinuxContainer.defaultMounts() : mounts,
+                maskedPaths: try decoded.optionalStringArray("maskedPath") ?? LinuxContainer.defaultMaskedPaths(),
+                readonlyPaths: try decoded.optionalStringArray("readonlyPath") ?? LinuxContainer.defaultReadonlyPaths(),
+                dns: dns,
+                hosts: hosts,
+                virtualization: try decoded.optionalBool("virtualization") ?? false,
+                bootLog: bootLog,
+                ociRuntimePath: try decoded.optionalString("ociRuntimePath"),
+                useInit: try decoded.optionalBool("useInit") ?? false,
+                cpuOverhead: try decoded.optionalInt("cpuOverhead") ?? 1,
+                memoryOverhead: try decoded.optionalUInt64("memoryOverhead") ?? 134_217_728
+            )
+            return try register(config, name: decoded.requiredString("containerConfig"), session: session)
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func register(
+        _ config: LinuxContainer.Configuration,
+        name: String,
+        session: GhostboxSession
+    ) throws -> GhostboxDirectValue {
+        let reference = try session.register(
+            kind: "container-config",
+            name: name,
+            value: config,
+            equivalent: ghostboxContainerConfigurationEqual
+        )
+        return .reference(reference)
+    }
+}
+
+enum GhostboxConfigurationCommandHandlers {
+    static let all: [any GhostboxDomainHandler] = [
+        GhostboxHostsEntryCommands(),
+        GhostboxHostsCommands(),
+        GhostboxSocketCommands(),
+        GhostboxRLimitKindCommands(),
+        GhostboxRLimitCommands(),
+        GhostboxCapabilitiesCommands(),
+        GhostboxContainerConfigCommands(),
+    ]
+}
+
+struct GhostboxHostsRecord: Sendable {
+    let value: Hosts
+    let entryReferences: [String]
+}
+
+struct GhostboxRLimitRecord: Sendable, Equatable {
+    let value: LinuxRLimit
+    let kindReference: String
+}
+
+struct GhostboxProcessReferences: Sendable, Equatable {
+    var rlimits: [String]
+    var capabilities: String
+    var stdin: String?
+    var stdout: String?
+    var stderr: String?
+}
+
+struct GhostboxProcessConfigRecord: Sendable {
+    var configuration: LinuxProcessConfiguration
+    var references: GhostboxProcessReferences
+}
+
+func ghostboxProcessConfiguration(
+    _ reference: String,
+    session: GhostboxSession
+) throws -> LinuxProcessConfiguration {
+    let record: GhostboxProcessConfigRecord = try session.valueSnapshot(
+        for: reference,
+        expectedKind: "process-config"
+    )
+    return record.configuration
+}
+
+func ghostboxReferenceName(_ reference: String) -> String {
+    String(reference.split(separator: "/", maxSplits: 1, omittingEmptySubsequences: false).last ?? "")
+}
+
+func ghostboxDecode(
+    _ type: Value.Type,
+    from object: [String: GhostboxJSONValue],
+    parameter: String
+) throws -> Value {
+    do {
+        return try JSONDecoder().decode(type, from: JSONEncoder().encode(GhostboxJSONValue.object(object)))
+    } catch {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' is not valid \(type): \(error.localizedDescription)")
+    }
+}
+
+func ghostboxHostsEntryEqual(_ lhs: Hosts.Entry, _ rhs: Hosts.Entry) -> Bool {
+    lhs.ipAddress == rhs.ipAddress && lhs.hostnames == rhs.hostnames && lhs.comment == rhs.comment
+}
+
+private func ghostboxHostsRecordEqual(_ lhs: GhostboxHostsRecord, _ rhs: GhostboxHostsRecord) -> Bool {
+    lhs.entryReferences == rhs.entryReferences
+        && lhs.value.comment == rhs.value.comment
+        && lhs.value.entries.count == rhs.value.entries.count
+        && zip(lhs.value.entries, rhs.value.entries).allSatisfy(ghostboxHostsEntryEqual)
+}
+
+private func ghostboxFileURL(_ value: String) -> URL {
+    if let url = URL(string: value), url.isFileURL { return url }
+    return URL(filePath: value)
+}
+
+private func ghostboxPermissions(_ value: GhostboxJSONValue?) throws -> FilePermissions? {
+    guard let value else { return nil }
+    let raw: UInt64?
+    switch value {
+    case .unsignedInteger(let value): raw = value
+    case .integer(let value): raw = value >= 0 ? UInt64(value) : nil
+    case .string(let value):
+        let digits = value.hasPrefix("0o") ? String(value.dropFirst(2)) : value
+        raw = UInt64(digits, radix: 8)
+    default: raw = nil
+    }
+    guard let raw, raw <= 0o7777 else {
+        throw DirectDispatchError(.invalidArgument, "parameter 'permissions' must be an octal file mode")
+    }
+    return FilePermissions(rawValue: numericCast(raw))
+}
+
+private func ghostboxDirectionString(_ direction: UnixSocketConfiguration.Direction) -> String {
+    switch direction {
+    case .into: return "into"
+    case .outOf: return "out-of"
+    }
+}
+
+private func ghostboxSocketEqual(_ lhs: UnixSocketConfiguration, _ rhs: UnixSocketConfiguration) -> Bool {
+    lhs.source == rhs.source
+        && lhs.destination == rhs.destination
+        && lhs.permissions == rhs.permissions
+        && ghostboxDirectionString(lhs.direction) == ghostboxDirectionString(rhs.direction)
+}
+
+private func ghostboxCapabilities(_ values: [String]) throws -> [CapabilityName] {
+    try values.map(CapabilityName.init(rawValue:))
+}
+
+func ghostboxCapabilitiesEqual(
+    _ lhs: Containerization.LinuxCapabilities,
+    _ rhs: Containerization.LinuxCapabilities
+) -> Bool {
+    lhs.bounding == rhs.bounding
+        && lhs.effective == rhs.effective
+        && lhs.inheritable == rhs.inheritable
+        && lhs.permitted == rhs.permitted
+        && lhs.ambient == rhs.ambient
+}
+
+private func ghostboxSysctls(_ values: [String]) throws -> [String: String] {
+    var result: [String: String] = [:]
+    for value in values {
+        guard let separator = value.firstIndex(of: "="), separator != value.startIndex else {
+            throw DirectDispatchError(.invalidArgument, "sysctl '\(value)' must use KEY=VALUE syntax")
+        }
+        let key = String(value[.. Bool {
+    lhs.type == rhs.type
+        && lhs.source == rhs.source
+        && lhs.destination == rhs.destination
+        && lhs.options == rhs.options
+        && ghostboxRuntimeOptionsEqual(lhs.runtimeOptions, rhs.runtimeOptions)
+}
+
+private func ghostboxRuntimeOptionsEqual(
+    _ lhs: Containerization.Mount.RuntimeOptions,
+    _ rhs: Containerization.Mount.RuntimeOptions
+) -> Bool {
+    switch (lhs, rhs) {
+    case (.virtioblk(let lhs), .virtioblk(let rhs)),
+         (.virtiofs(let lhs), .virtiofs(let rhs)),
+         (.any(let lhs), .any(let rhs)):
+        return lhs == rhs
+    case (.shared, .shared):
+        return true
+    default:
+        return false
+    }
+}
+
+func ghostboxProcessConfigurationEqual(_ lhs: LinuxProcessConfiguration, _ rhs: LinuxProcessConfiguration) -> Bool {
+    lhs.arguments == rhs.arguments
+        && lhs.environmentVariables == rhs.environmentVariables
+        && lhs.workingDirectory == rhs.workingDirectory
+        && ghostboxUserEqual(lhs.user, rhs.user)
+        && lhs.rlimits == rhs.rlimits
+        && lhs.noNewPrivileges == rhs.noNewPrivileges
+        && ghostboxCapabilitiesEqual(lhs.capabilities, rhs.capabilities)
+        && lhs.terminal == rhs.terminal
+        && (lhs.stdin == nil) == (rhs.stdin == nil)
+        && (lhs.stdout == nil) == (rhs.stdout == nil)
+        && (lhs.stderr == nil) == (rhs.stderr == nil)
+}
+
+private func ghostboxUserEqual(_ lhs: ContainerizationOCI.User, _ rhs: ContainerizationOCI.User) -> Bool {
+    lhs.uid == rhs.uid
+        && lhs.gid == rhs.gid
+        && lhs.umask == rhs.umask
+        && lhs.additionalGids == rhs.additionalGids
+        && lhs.username == rhs.username
+}
+
+func ghostboxContainerConfigurationEqual(
+    _ lhs: LinuxContainer.Configuration,
+    _ rhs: LinuxContainer.Configuration
+) -> Bool {
+    ghostboxProcessConfigurationEqual(lhs.process, rhs.process)
+        && lhs.cpus == rhs.cpus
+        && lhs.memoryInBytes == rhs.memoryInBytes
+        && lhs.hostname == rhs.hostname
+        && lhs.sysctl == rhs.sysctl
+        && lhs.interfaces.count == rhs.interfaces.count
+        && lhs.sockets.count == rhs.sockets.count
+        && zip(lhs.sockets, rhs.sockets).allSatisfy(ghostboxSocketEqual)
+        && lhs.mounts.count == rhs.mounts.count
+        && zip(lhs.mounts, rhs.mounts).allSatisfy(ghostboxMountEqual)
+        && lhs.maskedPaths == rhs.maskedPaths
+        && lhs.readonlyPaths == rhs.readonlyPaths
+        && ghostboxOptionalDNSEqual(lhs.dns, rhs.dns)
+        && ghostboxOptionalHostsEqual(lhs.hosts, rhs.hosts)
+        && lhs.virtualization == rhs.virtualization
+        && (lhs.bootLog == nil) == (rhs.bootLog == nil)
+        && lhs.ociRuntimePath == rhs.ociRuntimePath
+        && lhs.useInit == rhs.useInit
+        && lhs.cpuOverhead == rhs.cpuOverhead
+        && lhs.memoryOverhead == rhs.memoryOverhead
+}
+
+private func ghostboxOptionalDNSEqual(_ lhs: DNS?, _ rhs: DNS?) -> Bool {
+    switch (lhs, rhs) {
+    case (.some(let lhs), .some(let rhs)): return ghostboxDNSEqual(lhs, rhs)
+    case (.none, .none): return true
+    default: return false
+    }
+}
+
+private func ghostboxOptionalHostsEqual(_ lhs: Hosts?, _ rhs: Hosts?) -> Bool {
+    switch (lhs, rhs) {
+    case (.some(let lhs), .some(let rhs)):
+        return lhs.comment == rhs.comment
+            && lhs.entries.count == rhs.entries.count
+            && zip(lhs.entries, rhs.entries).allSatisfy(ghostboxHostsEntryEqual)
+    case (.none, .none): return true
+    default: return false
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxContainerAPICommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxContainerAPICommands.swift
new file mode 100644
index 0000000..7688adf
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxContainerAPICommands.swift
@@ -0,0 +1,227 @@
+import ContainerAPIClient
+import ContainerPersistence
+import ContainerResource
+import Foundation
+import GhostVMKit
+
+struct GhostboxContainerMemorySizeCommands: GhostboxDomainHandler {
+    let resource = "crMemorySize"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "crMemorySize.create":
+            let decoded = try GhostboxParameters(parameters, allowed: ["memorySize", "value"])
+            let name = try decoded.requiredString("memorySize")
+            let memorySize: MemorySize
+            do {
+                memorySize = try MemorySize(decoded.requiredString("value"))
+            } catch {
+                throw DirectDispatchError(.invalidArgument, "invalid memory size: \(error)")
+            }
+            let bytes = memorySize.measurement.converted(to: .bytes).value
+            guard bytes.isFinite, bytes >= 0, bytes <= Double(UInt64.max) else {
+                throw DirectDispatchError(.invalidArgument, "memory size is outside the UInt64 byte range")
+            }
+            let reference = try session.registerNew(
+                kind: "memory-size",
+                name: name,
+                makeValue: { memorySize },
+                equivalent: ==
+            )
+            return .reference(reference)
+
+        case "crMemorySize.formatted":
+            let memorySize = try value(parameters, session: session)
+            return .string(memorySize.formatted)
+
+        case "crMemorySize.toUInt64":
+            let decoded = try GhostboxParameters(parameters, allowed: ["memorySize", "unit"])
+            let reference = try decoded.requiredReference("memorySize", expectedKind: "memory-size")
+            let memorySize: MemorySize = try session.value(for: reference, expectedKind: "memory-size")
+            let unit: UnitInformationStorage
+            switch try decoded.requiredString("unit") {
+            case "bytes": unit = .bytes
+            case "kibibytes": unit = .kibibytes
+            case "mebibytes": unit = .mebibytes
+            case "gibibytes": unit = .gibibytes
+            case "tebibytes": unit = .tebibytes
+            case "pebibytes": unit = .pebibytes
+            default:
+                throw DirectDispatchError(.invalidArgument, "unsupported information-storage unit")
+            }
+            return .unsignedInteger(memorySize.toUInt64(unit: unit))
+
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func value(
+        _ parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) throws -> MemorySize {
+        let decoded = try GhostboxParameters(parameters, allowed: ["memorySize"])
+        let reference = try decoded.requiredReference("memorySize", expectedKind: "memory-size")
+        return try session.value(for: reference, expectedKind: "memory-size")
+    }
+}
+
+struct GhostboxContainerResourceLabelsCommands: GhostboxDomainHandler {
+    let resource = "crResourceLabels"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "crResourceLabels.create":
+            let decoded = try GhostboxParameters(parameters, allowed: ["resourceLabels", "label"])
+            let name = try decoded.requiredString("resourceLabels")
+            let labels = try parseLabels(try decoded.optionalStringArray("label") ?? [])
+            let value: ResourceLabels
+            do {
+                value = try ResourceLabels(labels)
+            } catch {
+                throw DirectDispatchError(.invalidArgument, error.localizedDescription)
+            }
+            return .reference(try session.registerNew(
+                kind: "resource-labels",
+                name: name,
+                makeValue: { value },
+                equivalent: ==
+            ))
+
+        case "crResourceLabels.validateKey":
+            let decoded = try GhostboxParameters(parameters, allowed: ["key"])
+            do {
+                try ResourceLabels.validateLabelKey(decoded.requiredString("key"))
+            } catch {
+                throw DirectDispatchError(.invalidArgument, error.localizedDescription)
+            }
+            return .void
+
+        case "crResourceLabels.validate":
+            let decoded = try GhostboxParameters(parameters, allowed: ["key", "value"])
+            do {
+                try ResourceLabels.validateLabel(
+                    key: decoded.requiredString("key"),
+                    value: decoded.requiredString("value")
+                )
+            } catch {
+                throw DirectDispatchError(.invalidArgument, error.localizedDescription)
+            }
+            return .void
+
+        case "crResourceLabels.dictionary":
+            return .object(try labels(parameters, session: session).dictionary.mapValues(GhostboxDirectValue.string))
+
+        case "crResourceLabels.value":
+            let decoded = try GhostboxParameters(parameters, allowed: ["resourceLabels", "key"])
+            let reference = try decoded.requiredReference("resourceLabels", expectedKind: "resource-labels")
+            let labels: ResourceLabels = try session.value(for: reference, expectedKind: "resource-labels")
+            return labels[try decoded.requiredString("key")].map(GhostboxDirectValue.string) ?? .null
+
+        case "crResourceLabels.keyLengthMax":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            return .integer(Int64(ResourceLabels.keyLengthMax))
+
+        case "crResourceLabels.labelLengthMax":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            return .integer(Int64(ResourceLabels.labelLengthMax))
+
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func labels(
+        _ parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) throws -> ResourceLabels {
+        let decoded = try GhostboxParameters(parameters, allowed: ["resourceLabels"])
+        let reference = try decoded.requiredReference("resourceLabels", expectedKind: "resource-labels")
+        return try session.value(for: reference, expectedKind: "resource-labels")
+    }
+
+    private func parseLabels(_ labels: [String]) throws -> [String: String] {
+        var result: [String: String] = [:]
+        for label in labels {
+            guard let separator = label.firstIndex(of: "="), separator != label.startIndex else {
+                throw DirectDispatchError(.invalidArgument, "labels must use key=value syntax")
+            }
+            let key = String(label[.. GhostboxDirectValue {
+        switch method.rawValue {
+        case "crParser.memoryAsMiB":
+            let memory = try singleString(parameters, name: "memory")
+            try validateMemoryConversion(memory)
+            return .integer(try ContainerAPIClient.Parser.memoryStringAsMiB(memory))
+
+        case "crParser.memoryAsBytes":
+            let memory = try singleString(parameters, name: "memory")
+            try validateMemoryConversion(memory)
+            return .unsignedInteger(try ContainerAPIClient.Parser.memoryStringAsBytes(memory))
+
+        case "crParser.labels":
+            let decoded = try GhostboxParameters(parameters, allowed: ["label"])
+            let labels = try ContainerAPIClient.Parser.labels(decoded.requiredStringArray("label"))
+            return .object(labels.mapValues(GhostboxDirectValue.string))
+
+        case "crParser.platform":
+            return try ghostboxEncodedValue(
+                ContainerAPIClient.Parser.platform(from: singleString(parameters, name: "platform"))
+            )
+
+        case "crParser.isValidDomainName":
+            return .boolean(ContainerAPIClient.Parser.isValidDomainName(try singleString(parameters, name: "name")))
+
+        case "crParser.isValidDomainNameLabel":
+            return .boolean(ContainerAPIClient.Parser.isValidDomainNameLabel(try singleString(parameters, name: "label")))
+
+        case "crParser.parseBool":
+            return ContainerAPIClient.Parser.parseBool(string: try singleString(parameters, name: "value"))
+                .map(GhostboxDirectValue.boolean) ?? .null
+
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func singleString(_ parameters: [String: GhostboxJSONValue], name: String) throws -> String {
+        try GhostboxParameters(parameters, allowed: [name]).requiredString(name)
+    }
+
+    private func validateMemoryConversion(_ value: String) throws {
+        let memory: MemorySize
+        do {
+            memory = try MemorySize(value)
+        } catch {
+            throw DirectDispatchError(.invalidArgument, "invalid memory size: \(error)")
+        }
+        let bytes = memory.measurement.converted(to: .bytes).value
+        guard bytes.isFinite, bytes >= 0, bytes <= Double(UInt64.max) else {
+            throw DirectDispatchError(.invalidArgument, "memory size is outside the UInt64 byte range")
+        }
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxDispatcher.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxDispatcher.swift
new file mode 100644
index 0000000..d04e951
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxDispatcher.swift
@@ -0,0 +1,52 @@
+import GhostVMKit
+
+struct GhostboxDispatcher: Sendable {
+    private let handlers: [String: any GhostboxDomainHandler]
+
+    init(_ handlers: [any GhostboxDomainHandler]) {
+        self.handlers = Dictionary(uniqueKeysWithValues: handlers.map { ($0.resource, $0) })
+    }
+
+    func dispatch(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        let components = method.rawValue.split(separator: ".", maxSplits: 1, omittingEmptySubsequences: false)
+        guard components.count == 2, !components[0].isEmpty, !components[1].isEmpty else {
+            throw DirectDispatchError(.invalidArgument, "invalid direct method '\(method.rawValue)'")
+        }
+        let resource = String(components[0])
+        guard let handler = handlers[resource] else {
+            throw DirectDispatchError(.unsupported, "unsupported direct resource '\(resource)'")
+        }
+        return try await handler.handle(method: method, parameters: parameters, session: session)
+    }
+
+    static let standard = GhostboxDispatcher(
+        [
+            GhostboxDNSCommands(),
+            GhostboxContentStoreCommands(),
+            GhostboxAuthenticationCommands(),
+            GhostboxProgressHandlerCommands(),
+            GhostboxImageStoreCommands(),
+            GhostboxImageDescriptionCommands(),
+            GhostboxImageCommands(),
+            GhostboxVolumeCommands(),
+            GhostboxContainerMemorySizeCommands(),
+            GhostboxContainerResourceLabelsCommands(),
+            GhostboxContainerParserCommands(),
+            GhostboxNetworkCommands(),
+            GhostboxInterfaceCommands(),
+            GhostboxContentCommands(),
+            GhostboxProcessConfigCommands(),
+            GhostboxIOCommands(resource: "readerStream"),
+            GhostboxIOCommands(resource: "writer"),
+            GhostboxIOCommands(resource: "terminal"),
+        ] + GhostboxBootCommandHandlers.all
+            + GhostboxConfigurationCommandHandlers.all
+            + GhostboxVMCommandHandlers.all
+            + GhostboxLifecycleCommandHandlers.all
+            + GhostboxPodCommandHandlers.all
+    )
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxImageCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxImageCommands.swift
new file mode 100644
index 0000000..1a8421e
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxImageCommands.swift
@@ -0,0 +1,903 @@
+import Containerization
+import ContainerizationExtras
+import ContainerizationOCI
+import ContainerizationOS
+import Foundation
+import GhostVMKit
+
+let ghostboxImageStoreContextKey = "ghostbox.image-store"
+
+struct GhostboxProgressHandlerBox: Sendable {
+    let handler: ProgressHandler
+    let writerReference: String
+
+    init(_ handler: @escaping ProgressHandler, writerReference: String) {
+        self.handler = handler
+        self.writerReference = writerReference
+    }
+}
+
+private struct GhostboxAuthenticationRecord: Sendable {
+    let value: any Authentication
+    let username: String
+    let password: String
+}
+
+struct GhostboxContentStoreCommands: GhostboxDomainHandler {
+    let resource = "contentStore"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "contentStore.create" else { throw ghostboxUnsupportedImageMethod(method) }
+        let decoded = try GhostboxParameters(parameters, allowed: ["contentStore", "path"])
+        let store = try LocalContentStore(path: ghostboxHostURL(decoded.requiredString("path"), parameter: "path"))
+        let reference = try session.register(
+            kind: "content-store",
+            name: decoded.requiredString("contentStore"),
+            value: store,
+            equivalent: { $0 === $1 }
+        )
+        return .reference(reference)
+    }
+}
+
+struct GhostboxAuthenticationCommands: GhostboxDomainHandler {
+    let resource = "authentication"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "authentication.createBasic" else { throw ghostboxUnsupportedImageMethod(method) }
+        let decoded = try GhostboxParameters(parameters, allowed: ["authentication", "username", "password"])
+        let username = try decoded.requiredString("username")
+        let password = try decoded.requiredString("password")
+        let record = GhostboxAuthenticationRecord(
+            value: BasicAuthentication(username: username, password: password),
+            username: username,
+            password: password
+        )
+        let reference = try session.register(
+            kind: "authentication",
+            name: decoded.requiredString("authentication"),
+            value: record,
+            equivalent: { $0.username == $1.username && $0.password == $1.password }
+        )
+        return .reference(reference)
+    }
+}
+
+struct GhostboxProgressHandlerCommands: GhostboxDomainHandler {
+    let resource = "progressHandler"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "progressHandler.create" else { throw ghostboxUnsupportedImageMethod(method) }
+        let decoded = try GhostboxParameters(parameters, allowed: ["progressHandler", "writer"])
+        let writerReference = try decoded.requiredReference("writer", expectedKind: "writer")
+        let writer: any Writer = try session.value(for: writerReference, expectedKind: "writer", as: (any Writer).self)
+        let box = GhostboxProgressHandlerBox({ events in
+            for event in events {
+                try? writer.write(ghostboxProgressEventData(event))
+            }
+        }, writerReference: writerReference)
+        let reference = try session.register(
+            kind: "progress-handler",
+            name: decoded.requiredString("progressHandler"),
+            value: box,
+            equivalent: { $0.writerReference == $1.writerReference }
+        )
+        return .reference(reference)
+    }
+}
+
+private struct GhostboxImageDescriptionRecord: Sendable {
+    let description: Containerization.Image.Description
+    let provenance: String
+}
+
+struct GhostboxImageRecord: Sendable {
+    let image: Containerization.Image
+    let provenance: String
+}
+
+private struct GhostboxContentRecord: Sendable {
+    let content: any Content
+    let imageReference: String
+    let requestedDigest: String
+}
+
+struct GhostboxImageStoreCommands: GhostboxDomainHandler {
+    let resource = "imageStore"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "imageStore.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "path", "contentStore"]
+            )
+            let name = try decoded.requiredString("imageStore")
+            let path = try ghostboxHostURL(decoded.requiredString("path"), parameter: "path")
+            let contentStore = try ghostboxContentStore(
+                decoded.optionalReference("contentStore", expectedKind: "content-store"),
+                session: session
+            )
+            let store = try ImageStore(path: path, contentStore: contentStore)
+            let reference = try session.register(
+                kind: "image-store",
+                name: name,
+                value: store,
+                equivalent: { $0 === $1 }
+            )
+            return .reference(reference)
+
+        case "imageStore.default":
+            _ = try GhostboxParameters(parameters, allowed: [])
+            guard let store = session.contextValue(ghostboxImageStoreContextKey, as: ImageStore.self) else {
+                throw DirectDispatchError(.failedPrecondition, "per-VM image store is unavailable")
+            }
+            let reference = try session.register(
+                kind: "image-store",
+                name: "default",
+                value: store,
+                equivalent: { $0 === $1 }
+            )
+            return .reference(reference)
+
+        case "imageStore.path":
+            let decoded = try GhostboxParameters(parameters, allowed: ["imageStore"])
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            return .string(store.path.path)
+
+        case "imageStore.get":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "reference", "pull"]
+            )
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let image = try await store.get(
+                reference: decoded.requiredString("reference"),
+                pull: try decoded.optionalBool("pull") ?? false
+            )
+            return try ghostboxRegisterImage(image, provenance: storeReference, session: session)
+
+        case "imageStore.list":
+            let decoded = try GhostboxParameters(parameters, allowed: ["imageStore"])
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let images = try await store.list()
+            let references = try images.map {
+                try ghostboxRegisterImageReference($0, provenance: storeReference, session: session)
+            }
+            return .references(references)
+
+        case "imageStore.createImage":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "imageDescription"]
+            )
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let descriptionReference = try decoded.requiredReference(
+                "imageDescription",
+                expectedKind: "image-description"
+            )
+            let record: GhostboxImageDescriptionRecord = try session.value(
+                for: descriptionReference,
+                expectedKind: "image-description"
+            )
+            let image = try await store.create(description: record.description)
+            return try ghostboxRegisterImage(image, provenance: storeReference, session: session)
+
+        case "imageStore.delete":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "reference", "performCleanup"]
+            )
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            try await store.delete(
+                reference: decoded.requiredString("reference"),
+                performCleanup: try decoded.optionalBool("performCleanup") ?? false
+            )
+            return .void
+
+        case "imageStore.cleanUpOrphanedBlobs":
+            let decoded = try GhostboxParameters(parameters, allowed: ["imageStore"])
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            let result = try await store.cleanUpOrphanedBlobs()
+            return .object([
+                "deleted": .strings(result.deleted),
+                "freed": .unsignedInteger(result.freed),
+            ])
+
+        case "imageStore.calculateOrphanedBlobsSize":
+            let decoded = try GhostboxParameters(parameters, allowed: ["imageStore"])
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            return .unsignedInteger(try await store.calculateOrphanedBlobsSize())
+
+        case "imageStore.tag":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "existingReference", "newReference"]
+            )
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let image = try await store.tag(
+                existing: decoded.requiredString("existingReference"),
+                new: decoded.requiredString("newReference")
+            )
+            return try ghostboxRegisterImage(image, provenance: storeReference, session: session)
+
+        case "imageStore.pull":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: [
+                    "imageStore", "reference", "platform", "insecure", "authentication",
+                    "progress", "maxConcurrentDownloads",
+                ]
+            )
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let maxConcurrentDownloads = try decoded.optionalInt("maxConcurrentDownloads") ?? 3
+            guard maxConcurrentDownloads > 0 else {
+                throw DirectDispatchError(
+                    .invalidArgument,
+                    "parameter 'maxConcurrentDownloads' must be greater than zero"
+                )
+            }
+            let image = try await store.pull(
+                reference: decoded.requiredString("reference"),
+                platform: try ghostboxOptionalPlatform(decoded, name: "platform"),
+                insecure: try decoded.optionalBool("insecure") ?? false,
+                auth: try ghostboxAuthentication(
+                    decoded.optionalReference("authentication", expectedKind: "authentication"),
+                    session: session
+                ),
+                progress: try ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"),
+                    session: session
+                ),
+                maxConcurrentDownloads: maxConcurrentDownloads
+            )
+            return try ghostboxRegisterImage(image, provenance: storeReference, session: session)
+
+        case "imageStore.push":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "reference", "platform", "insecure", "authentication", "progress"]
+            )
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            try await store.push(
+                reference: decoded.requiredString("reference"),
+                platform: try ghostboxOptionalPlatform(decoded, name: "platform"),
+                insecure: try decoded.optionalBool("insecure") ?? false,
+                auth: try ghostboxAuthentication(
+                    decoded.optionalReference("authentication", expectedKind: "authentication"),
+                    session: session
+                ),
+                progress: try ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"),
+                    session: session
+                )
+            )
+            return .void
+
+        case "imageStore.pushMany":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: [
+                    "imageStore", "reference", "platform", "insecure", "authentication",
+                    "maxConcurrentUploads", "progress",
+                ]
+            )
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            let references = try decoded.requiredStringArray("reference")
+            guard !references.isEmpty else {
+                throw DirectDispatchError(.invalidArgument, "parameter 'reference' must not be empty")
+            }
+            let maxConcurrentUploads = try decoded.optionalInt("maxConcurrentUploads") ?? 3
+            guard maxConcurrentUploads > 0 else {
+                throw DirectDispatchError(
+                    .invalidArgument,
+                    "parameter 'maxConcurrentUploads' must be greater than zero"
+                )
+            }
+            try await store.push(
+                references: references,
+                platform: try ghostboxOptionalPlatform(decoded, name: "platform"),
+                insecure: try decoded.optionalBool("insecure") ?? false,
+                auth: try ghostboxAuthentication(
+                    decoded.optionalReference("authentication", expectedKind: "authentication"),
+                    session: session
+                ),
+                maxConcurrentUploads: maxConcurrentUploads,
+                progress: try ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"),
+                    session: session
+                )
+            )
+            return .void
+
+        case "imageStore.save":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "reference", "out", "platform"]
+            )
+            let (_, store) = try ghostboxImageStore(decoded, session: session)
+            let references = try decoded.requiredStringArray("reference")
+            guard !references.isEmpty else {
+                throw DirectDispatchError(.invalidArgument, "parameter 'reference' must not be empty")
+            }
+            try await store.save(
+                references: references,
+                out: try ghostboxHostURL(decoded.requiredString("out"), parameter: "out"),
+                platform: try ghostboxOptionalPlatform(decoded, name: "platform")
+            )
+            return .void
+
+        case "imageStore.load":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "directory", "progress"]
+            )
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let images = try await store.load(
+                from: ghostboxHostURL(decoded.requiredString("directory"), parameter: "directory"),
+                progress: ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"),
+                    session: session
+                )
+            )
+            let references = try images.map {
+                try ghostboxRegisterImageReference($0, provenance: storeReference, session: session)
+            }
+            return .references(references)
+
+        case "imageStore.getInitImage":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageStore", "reference", "authentication", "progress"]
+            )
+            let (storeReference, store) = try ghostboxImageStore(decoded, session: session)
+            let imageReference = try decoded.requiredString("reference")
+            let image = try await store.getInitImage(
+                reference: imageReference,
+                auth: ghostboxAuthentication(
+                    decoded.optionalReference("authentication", expectedKind: "authentication"),
+                    session: session
+                ),
+                progress: ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"),
+                    session: session
+                )
+            )
+            let name = ghostboxStableName(["init-image", storeReference, imageReference])
+            let reference = try session.register(
+                kind: "init-image",
+                name: name,
+                value: image,
+                equivalent: { $0.name == $1.name }
+            )
+            return .reference(reference)
+
+        default:
+            throw ghostboxUnsupportedImageMethod(method)
+        }
+    }
+}
+
+struct GhostboxImageDescriptionCommands: GhostboxDomainHandler {
+    let resource = "imageDescription"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "imageDescription.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["imageDescription", "reference", "descriptor"]
+            )
+            let description = Containerization.Image.Description(
+                reference: try decoded.requiredString("reference"),
+                descriptor: try ghostboxDescriptor(decoded, name: "descriptor")
+            )
+            let record = GhostboxImageDescriptionRecord(
+                description: description,
+                provenance: "created"
+            )
+            let reference = try session.register(
+                kind: "image-description",
+                name: decoded.requiredString("imageDescription"),
+                value: record,
+                equivalent: ghostboxImageDescriptionRecordsEqual
+            )
+            return .reference(reference)
+
+        case "imageDescription.reference",
+             "imageDescription.descriptor",
+             "imageDescription.digest",
+             "imageDescription.mediaType":
+            let decoded = try GhostboxParameters(parameters, allowed: ["imageDescription"])
+            let reference = try decoded.requiredReference("imageDescription", expectedKind: "image-description")
+            let record: GhostboxImageDescriptionRecord = try session.value(
+                for: reference,
+                expectedKind: "image-description"
+            )
+            switch method.rawValue {
+            case "imageDescription.reference":
+                return .string(record.description.reference)
+            case "imageDescription.descriptor":
+                return try ghostboxCodableValue(record.description.descriptor)
+            case "imageDescription.digest":
+                return .string(record.description.digest)
+            default:
+                return .string(record.description.mediaType)
+            }
+
+        default:
+            throw ghostboxUnsupportedImageMethod(method)
+        }
+    }
+}
+
+struct GhostboxImageCommands: GhostboxDomainHandler {
+    let resource = "image"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "image.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["image", "imageDescription", "contentStore"]
+            )
+            let descriptionReference = try decoded.requiredReference(
+                "imageDescription",
+                expectedKind: "image-description"
+            )
+            let description: GhostboxImageDescriptionRecord = try session.value(
+                for: descriptionReference,
+                expectedKind: "image-description"
+            )
+            let contentStoreReference = try decoded.requiredReference("contentStore", expectedKind: "content-store")
+            let contentStore: any ContentStore = try session.value(
+                for: contentStoreReference,
+                expectedKind: "content-store",
+                as: (any ContentStore).self
+            )
+            let record = GhostboxImageRecord(
+                image: Containerization.Image(description: description.description, contentStore: contentStore),
+                provenance: contentStoreReference
+            )
+            let reference = try session.register(
+                kind: "image",
+                name: decoded.requiredString("image"),
+                value: record,
+                equivalent: ghostboxImageRecordsEqual
+            )
+            return .reference(reference)
+
+        case "image.description":
+            let decoded = try GhostboxParameters(parameters, allowed: ["image"])
+            let (imageReference, record) = try ghostboxImage(decoded, session: session)
+            let descriptionRecord = GhostboxImageDescriptionRecord(
+                description: record.image.description,
+                provenance: imageReference
+            )
+            let name = ghostboxStableName([
+                "image-description", imageReference, record.image.reference, record.image.digest,
+            ])
+            _ = try session.register(
+                kind: "image-description",
+                name: name,
+                value: descriptionRecord,
+                equivalent: ghostboxImageDescriptionRecordsEqual
+            )
+            return .object([
+                "reference": .string(record.image.description.reference),
+                "descriptor": try ghostboxCodableValue(record.image.description.descriptor),
+            ])
+
+        case "image.descriptor",
+             "image.digest",
+             "image.mediaType",
+             "image.reference",
+             "image.index",
+             "image.referencedDigests":
+            let decoded = try GhostboxParameters(parameters, allowed: ["image"])
+            let (_, record) = try ghostboxImage(decoded, session: session)
+            switch method.rawValue {
+            case "image.descriptor":
+                return try ghostboxCodableValue(record.image.descriptor)
+            case "image.digest":
+                return .string(record.image.digest)
+            case "image.mediaType":
+                return .string(record.image.mediaType)
+            case "image.reference":
+                return .string(record.image.reference)
+            case "image.index":
+                return try await ghostboxCodableValue(record.image.index())
+            default:
+                return .strings(try await record.image.referencedDigests())
+            }
+
+        case "image.manifest":
+            let decoded = try GhostboxParameters(parameters, allowed: ["image", "platform"])
+            let (_, record) = try ghostboxImage(decoded, session: session)
+            return try await ghostboxCodableValue(
+                record.image.manifest(for: ghostboxPlatform(decoded, name: "platform"))
+            )
+
+        case "image.descriptorFor":
+            let decoded = try GhostboxParameters(parameters, allowed: ["image", "platform"])
+            let (_, record) = try ghostboxImage(decoded, session: session)
+            return try await ghostboxCodableValue(
+                record.image.descriptor(for: ghostboxPlatform(decoded, name: "platform"))
+            )
+
+        case "image.config":
+            let decoded = try GhostboxParameters(parameters, allowed: ["image", "platform"])
+            let (_, record) = try ghostboxImage(decoded, session: session)
+            return try await ghostboxCodableValue(
+                record.image.config(for: ghostboxPlatform(decoded, name: "platform"))
+            )
+
+        case "image.getContent":
+            let decoded = try GhostboxParameters(parameters, allowed: ["image", "digest"])
+            let (imageReference, record) = try ghostboxImage(decoded, session: session)
+            let digest = try decoded.requiredString("digest")
+            let content = try await record.image.getContent(digest: digest)
+            let contentRecord = GhostboxContentRecord(
+                content: content,
+                imageReference: imageReference,
+                requestedDigest: digest
+            )
+            let name = ghostboxStableName(["content", imageReference, digest])
+            let reference = try session.register(
+                kind: "content",
+                name: name,
+                value: contentRecord,
+                equivalent: ghostboxContentRecordsEqual
+            )
+            return .reference(reference)
+
+        default:
+            throw ghostboxUnsupportedImageMethod(method)
+        }
+    }
+}
+
+struct GhostboxContentCommands: GhostboxDomainHandler {
+    let resource = "content"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "content.path",
+             "content.digest",
+             "content.size",
+             "content.data":
+            let decoded = try GhostboxParameters(parameters, allowed: ["content"])
+            let record = try ghostboxContent(decoded, session: session)
+            switch method.rawValue {
+            case "content.path":
+                return .string(record.content.path.path)
+            case "content.digest":
+                return .string(try record.content.digest().digestString)
+            case "content.size":
+                return .unsignedInteger(try record.content.size())
+            default:
+                let size = try record.content.size()
+                try ghostboxCheckBytePayload(size)
+                let data = try record.content.data()
+                try ghostboxCheckBytePayload(data.count)
+                return .bytes(data)
+            }
+
+        case "content.dataRange":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["content", "offset", "length"]
+            )
+            let record = try ghostboxContent(decoded, session: session)
+            let offset = try decoded.requiredUInt64("offset")
+            let length = try decoded.requiredInt("length")
+            guard length >= 0 else {
+                throw DirectDispatchError(.invalidArgument, "parameter 'length' must not be negative")
+            }
+            let readLength: Int
+            if length == 0 {
+                let size = try record.content.size()
+                let remaining = offset < size ? size - offset : 0
+                try ghostboxCheckBytePayload(remaining)
+                guard let boundedLength = Int(exactly: remaining) else {
+                    throw DirectDispatchError(.resourceExhausted, "content range is too large")
+                }
+                readLength = boundedLength
+            } else {
+                try ghostboxCheckBytePayload(length)
+                readLength = length
+            }
+            if readLength == 0 {
+                return .bytes(Data())
+            }
+            guard let data = try record.content.data(offset: offset, length: readLength) else {
+                return .null
+            }
+            try ghostboxCheckBytePayload(data.count)
+            return .bytes(data)
+
+        default:
+            throw ghostboxUnsupportedImageMethod(method)
+        }
+    }
+}
+
+private func ghostboxImageStore(
+    _ parameters: GhostboxParameters,
+    session: GhostboxSession
+) throws -> (String, ImageStore) {
+    let reference = try parameters.requiredReference("imageStore", expectedKind: "image-store")
+    let store: ImageStore = try session.value(for: reference, expectedKind: "image-store")
+    return (reference, store)
+}
+
+private func ghostboxImage(
+    _ parameters: GhostboxParameters,
+    session: GhostboxSession
+) throws -> (String, GhostboxImageRecord) {
+    let reference = try parameters.requiredReference("image", expectedKind: "image")
+    let record: GhostboxImageRecord = try session.value(for: reference, expectedKind: "image")
+    return (reference, record)
+}
+
+private func ghostboxContent(
+    _ parameters: GhostboxParameters,
+    session: GhostboxSession
+) throws -> GhostboxContentRecord {
+    let reference = try parameters.requiredReference("content", expectedKind: "content")
+    return try session.value(for: reference, expectedKind: "content")
+}
+
+private func ghostboxContentStore(
+    _ reference: String?,
+    session: GhostboxSession
+) throws -> (any ContentStore)? {
+    guard let reference else { return nil }
+    let store: any ContentStore = try session.value(
+        for: reference,
+        expectedKind: "content-store",
+        as: (any ContentStore).self
+    )
+    return store
+}
+
+private func ghostboxAuthentication(
+    _ reference: String?,
+    session: GhostboxSession
+) throws -> (any Authentication)? {
+    guard let reference else { return nil }
+    let authentication: GhostboxAuthenticationRecord = try session.value(
+        for: reference,
+        expectedKind: "authentication"
+    )
+    return authentication.value
+}
+
+func ghostboxProgressHandler(
+    _ reference: String?,
+    session: GhostboxSession
+) throws -> ProgressHandler? {
+    guard let reference else { return nil }
+    let box: GhostboxProgressHandlerBox = try session.value(
+        for: reference,
+        expectedKind: "progress-handler"
+    )
+    return box.handler
+}
+
+private func ghostboxProgressEventData(_ event: ProgressEvent) -> Data {
+    let value: Int64
+    switch event {
+    case .addItems(let count), .addTotalItems(let count): value = Int64(count)
+    case .addSize(let bytes), .addTotalSize(let bytes): value = bytes
+    }
+    let object = GhostboxJSONValue.object([
+        "event": .string(event.event),
+        "value": value >= 0 ? .unsignedInteger(UInt64(value)) : .integer(value),
+    ])
+    var data = (try? JSONEncoder().encode(object)) ?? Data()
+    data.append(0x0a)
+    return data
+}
+
+func ghostboxImageValue(_ reference: String, session: GhostboxSession) throws -> Containerization.Image {
+    let canonical = try GhostboxReference.canonical(reference, expectedKind: "image")
+    let record: GhostboxImageRecord = try session.value(for: canonical, expectedKind: "image")
+    return record.image
+}
+
+private func ghostboxRegisterImage(
+    _ image: Containerization.Image,
+    provenance: String,
+    session: GhostboxSession
+) throws -> GhostboxDirectValue {
+    .reference(try ghostboxRegisterImageReference(image, provenance: provenance, session: session))
+}
+
+private func ghostboxRegisterImageReference(
+    _ image: Containerization.Image,
+    provenance: String,
+    session: GhostboxSession
+) throws -> String {
+    let record = GhostboxImageRecord(image: image, provenance: provenance)
+    let name = ghostboxStableName(["image", provenance, image.reference, image.digest])
+    return try session.register(
+        kind: "image",
+        name: name,
+        value: record,
+        equivalent: ghostboxImageRecordsEqual
+    )
+}
+
+private func ghostboxImageDescriptionRecordsEqual(
+    _ lhs: GhostboxImageDescriptionRecord,
+    _ rhs: GhostboxImageDescriptionRecord
+) -> Bool {
+    lhs.provenance == rhs.provenance
+        && lhs.description.reference == rhs.description.reference
+        && lhs.description.descriptor == rhs.description.descriptor
+}
+
+private func ghostboxImageRecordsEqual(_ lhs: GhostboxImageRecord, _ rhs: GhostboxImageRecord) -> Bool {
+    lhs.provenance == rhs.provenance
+        && lhs.image.reference == rhs.image.reference
+        && lhs.image.descriptor == rhs.image.descriptor
+}
+
+private func ghostboxContentRecordsEqual(_ lhs: GhostboxContentRecord, _ rhs: GhostboxContentRecord) -> Bool {
+    lhs.imageReference == rhs.imageReference
+        && lhs.requestedDigest == rhs.requestedDigest
+        && lhs.content.path.standardizedFileURL == rhs.content.path.standardizedFileURL
+}
+
+private func ghostboxDescriptor(
+    _ parameters: GhostboxParameters,
+    name: String
+) throws -> Descriptor {
+    guard let value = parameters.optionalValue(name) else {
+        throw DirectDispatchError(.invalidArgument, "missing required parameter '\(name)'")
+    }
+    if case .object(let object) = value {
+        return try ghostboxDecode(Descriptor.self, from: .object(object), parameter: name)
+    }
+    guard case .string(let raw) = value else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' must be a JSON string or object")
+    }
+    do {
+        return try JSONDecoder().decode(Descriptor.self, from: Data(raw.utf8))
+    } catch {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' is not a valid OCI descriptor: \(error.localizedDescription)")
+    }
+}
+
+func ghostboxOptionalPlatform(
+    _ parameters: GhostboxParameters,
+    name: String
+) throws -> Platform? {
+    guard let value = parameters.optionalValue(name) else { return nil }
+    if case .object(let object) = value {
+        return try ghostboxDecode(Platform.self, from: .object(object), parameter: name)
+    }
+    guard case .string(let raw) = value else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' must be a platform string or object")
+    }
+    do {
+        if raw.first == "{" {
+            return try JSONDecoder().decode(Platform.self, from: Data(raw.utf8))
+        }
+        return try Platform(from: raw)
+    } catch {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(name)' is not a valid OCI platform: \(error.localizedDescription)")
+    }
+}
+
+private func ghostboxPlatform(
+    _ parameters: GhostboxParameters,
+    name: String
+) throws -> Platform {
+    guard let platform = try ghostboxOptionalPlatform(parameters, name: name) else {
+        throw DirectDispatchError(.invalidArgument, "missing required parameter '\(name)'")
+    }
+    return platform
+}
+
+private func ghostboxDecode(
+    _ type: Value.Type,
+    from value: GhostboxJSONValue,
+    parameter: String
+) throws -> Value {
+    do {
+        return try JSONDecoder().decode(type, from: JSONEncoder().encode(value))
+    } catch {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' is invalid: \(error.localizedDescription)")
+    }
+}
+
+private func ghostboxCodableValue(_ value: Value) throws -> GhostboxDirectValue {
+    let data = try JSONEncoder().encode(value)
+    let json = try JSONDecoder().decode(GhostboxJSONValue.self, from: data)
+    return ghostboxDirectValue(json)
+}
+
+private func ghostboxDirectValue(_ value: GhostboxJSONValue) -> GhostboxDirectValue {
+    switch value {
+    case .null:
+        return .null
+    case .boolean(let value):
+        return .boolean(value)
+    case .string(let value):
+        return .string(value)
+    case .integer(let value):
+        return .integer(value)
+    case .unsignedInteger(let value):
+        return .unsignedInteger(value)
+    case .array(let values):
+        return .array(values.map(ghostboxDirectValue))
+    case .object(let values):
+        return .object(values.mapValues(ghostboxDirectValue))
+    }
+}
+
+private func ghostboxHostURL(_ value: String, parameter: String) throws -> URL {
+    if value.hasPrefix("file://") {
+        guard let url = URL(string: value), url.isFileURL else {
+            throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' must be a file URL or path")
+        }
+        return url
+    }
+    return URL(fileURLWithPath: value)
+}
+
+private func ghostboxCheckBytePayload(_ count: T) throws {
+    guard count <= T(GhostboxDirectLimits.bytePayloadBytes) else {
+        throw DirectDispatchError(
+            .resourceExhausted,
+            "content payload exceeds the \(GhostboxDirectLimits.bytePayloadBytes)-byte direct transport limit"
+        )
+    }
+}
+
+private func ghostboxStableName(_ components: [String]) -> String {
+    var hash: UInt64 = 0xcbf29ce484222325
+    for component in components {
+        for byte in component.utf8 {
+            hash ^= UInt64(byte)
+            hash &*= 0x100000001b3
+        }
+        hash ^= 0xff
+        hash &*= 0x100000001b3
+    }
+    return String(hash, radix: 16)
+}
+
+private func ghostboxUnsupportedImageMethod(_ method: GhostboxDirectMethod) -> DirectDispatchError {
+    DirectDispatchError(.unsupported, "unsupported direct method '\(method.rawValue)'")
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxLifecycleCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxLifecycleCommands.swift
new file mode 100644
index 0000000..b002122
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxLifecycleCommands.swift
@@ -0,0 +1,1057 @@
+import Containerization
+import ContainerizationError
+import ContainerizationExtras
+import ContainerizationOS
+import Foundation
+import GhostVMKit
+
+struct GhostboxManagerCommands: GhostboxDomainHandler {
+    let resource = "manager"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "manager.create", "manager.createAtRoot", "manager.createFromReference",
+             "manager.createFromReferenceAtRoot", "manager.createWithVMM":
+            return try await createManager(method: method, parameters: parameters, session: session)
+        case "manager.imageStore":
+            let decoded = try GhostboxParameters(parameters, allowed: ["manager"])
+            let record = try manager(decoded, session: session)
+            return .reference(record.imageStoreReference)
+        case GhostboxDirectMethod.managerClose.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["manager"])
+            let managerReference = try decoded.requiredReference("manager", expectedKind: "manager")
+            let record: GhostboxManagerRecord = try session.value(for: managerReference, expectedKind: "manager")
+            try await record.box.retireIfUnused(reference: managerReference)
+            try session.unregister(managerReference, expectedKind: "manager", matching: record)
+            if record.ownsImageStoreReference {
+                let store: ImageStore = try session.value(
+                    for: record.imageStoreReference,
+                    expectedKind: "image-store"
+                )
+                try session.unregister(record.imageStoreReference, expectedKind: "image-store", matching: store)
+            }
+            return .void
+        case "manager.createContainer", "manager.createContainerFromImage", "manager.createContainerFromMounts":
+            return try await createContainer(method: method, parameters: parameters, session: session)
+        case "manager.releaseNetwork", "manager.delete":
+            let decoded = try GhostboxParameters(parameters, allowed: ["manager", "container"])
+            let managerReference = try decoded.requiredReference("manager", expectedKind: "manager")
+            let record: GhostboxManagerRecord = try session.value(for: managerReference, expectedKind: "manager")
+            let containerReference = try decoded.requiredReference("container", expectedKind: "container")
+            let container: GhostboxContainerRecord = try session.value(for: containerReference, expectedKind: "container")
+            guard container.managerReference == managerReference else {
+                throw DirectDispatchError(.invalidArgument, "container does not belong to the requested manager")
+            }
+            if method.rawValue == "manager.releaseNetwork" {
+                try await record.box.releaseNetwork(container.value.id)
+            } else {
+                guard let generation = container.managerGeneration else {
+                    throw DirectDispatchError(.invalidArgument, "container has no manager allocation generation")
+                }
+                try await record.box.delete(container.value.id, generation: generation)
+                try session.unregister(containerReference, expectedKind: "container", matching: container)
+            }
+            return .void
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func createManager(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        var allowed: Set = ["manager", "network"]
+        if method.rawValue == "manager.createWithVMM" {
+            allowed.insert("vmm")
+        } else {
+            allowed.formUnion(["kernel", "rosetta", "nestedVirtualization"])
+            if method.rawValue.contains("FromReference") {
+                allowed.formUnion(["initfsReference"])
+            } else {
+                allowed.insert("initfs")
+            }
+            if method.rawValue.contains("AtRoot") {
+                allowed.insert("root")
+            } else {
+                allowed.insert("imageStore")
+            }
+        }
+        let decoded = try GhostboxParameters(parameters, allowed: allowed)
+        let managerName = try decoded.requiredString("manager")
+        _ = try GhostboxReference.canonical(kind: "manager", name: managerName)
+        let network = try ghostboxManagerNetwork(decoded, session: session)
+        let manager: ContainerManager
+        let provenance: String
+        var imageStoreReference: String?
+
+        if method.rawValue == "manager.createWithVMM" {
+            let vmmReference = try decoded.requiredReference("vmm", expectedKind: "vmm")
+            let vmm: GhostboxVMMRecord = try session.value(for: vmmReference, expectedKind: "vmm")
+            manager = try ContainerManager(vmm: vmm.value, network: network)
+            provenance = "vmm:\(vmmReference)"
+        } else {
+            let kernelReference = try decoded.requiredReference("kernel", expectedKind: "kernel")
+            let kernel: Kernel = try session.value(for: kernelReference, expectedKind: "kernel")
+            let rosetta = try decoded.optionalBool("rosetta") ?? false
+            let nested = try decoded.optionalBool("nestedVirtualization") ?? false
+            if method.rawValue == "manager.create" {
+                let initfsReference = try decoded.requiredReference("initfs", expectedKind: "mount")
+                let initfs: Containerization.Mount = try session.value(for: initfsReference, expectedKind: "mount")
+                let suppliedImageStoreReference = try decoded.requiredReference("imageStore", expectedKind: "image-store")
+                imageStoreReference = suppliedImageStoreReference
+                let store: ImageStore = try session.value(for: suppliedImageStoreReference, expectedKind: "image-store")
+                manager = try ContainerManager(
+                    kernel: kernel, initfs: initfs, imageStore: store, network: network,
+                    rosetta: rosetta, nestedVirtualization: nested
+                )
+                provenance = "kernel:\(kernelReference)|initfs:\(initfsReference)"
+            } else if method.rawValue == "manager.createAtRoot" {
+                let initfsReference = try decoded.requiredReference("initfs", expectedKind: "mount")
+                let initfs: Containerization.Mount = try session.value(for: initfsReference, expectedKind: "mount")
+                manager = try ContainerManager(
+                    kernel: kernel, initfs: initfs, root: try decoded.optionalString("root").map(ghostboxHostURL),
+                    network: network, rosetta: rosetta, nestedVirtualization: nested
+                )
+                provenance = "kernel:\(kernelReference)|initfs:\(initfsReference)"
+            } else if method.rawValue == "manager.createFromReference" {
+                let suppliedImageStoreReference = try decoded.requiredReference("imageStore", expectedKind: "image-store")
+                imageStoreReference = suppliedImageStoreReference
+                let store: ImageStore = try session.value(for: suppliedImageStoreReference, expectedKind: "image-store")
+                let initfsReference = try decoded.requiredString("initfsReference")
+                let initfs = try await ghostboxInitBlock(reference: initfsReference, imageStore: store)
+                manager = try ContainerManager(
+                    kernel: kernel, initfs: initfs, imageStore: store, network: network,
+                    rosetta: rosetta, nestedVirtualization: nested
+                )
+                provenance = "kernel:\(kernelReference)|initfs-reference:\(initfsReference)"
+            } else {
+                let initfsReference = try decoded.requiredString("initfsReference")
+                let store: ImageStore
+                if let root = try decoded.optionalString("root") {
+                    store = try ImageStore(path: ghostboxHostURL(root))
+                } else {
+                    store = .default
+                }
+                let initfs = try await ghostboxInitBlock(reference: initfsReference, imageStore: store)
+                manager = try ContainerManager(
+                    kernel: kernel, initfs: initfs, imageStore: store, network: network,
+                    rosetta: rosetta, nestedVirtualization: nested
+                )
+                provenance = "kernel:\(kernelReference)|initfs-reference:\(initfsReference)"
+            }
+        }
+
+        let resolvedImageStoreReference: String
+        if let imageStoreReference {
+            resolvedImageStoreReference = imageStoreReference
+        } else {
+            resolvedImageStoreReference = try session.register(
+                kind: "image-store",
+                name: "\(managerName)-images",
+                value: manager.imageStore,
+                equivalent: { $0 === $1 }
+            )
+        }
+        let record = GhostboxManagerRecord(
+            box: GhostboxManagerBox(manager),
+            imageStoreReference: resolvedImageStoreReference,
+            ownsImageStoreReference: imageStoreReference == nil,
+            provenance: provenance
+        )
+        do {
+            let reference = try session.register(
+                kind: "manager",
+                name: managerName,
+                value: record,
+                equivalent: { $0.provenance == $1.provenance && $0.imageStoreReference == $1.imageStoreReference },
+                cleanupPriority: 70,
+                cleanup: { await $0.box.cleanupAllocations() }
+            )
+            return .reference(reference)
+        } catch {
+            if imageStoreReference == nil {
+                try? session.unregister(
+                    resolvedImageStoreReference,
+                    expectedKind: "image-store",
+                    matching: manager.imageStore
+                )
+            }
+            throw error
+        }
+    }
+
+    private func createContainer(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        let baseAllowed: Set = [
+            "manager", "container", "networking", "process", "cpus", "memory", "hostname", "sysctl",
+            "interfaces", "sockets", "mounts", "maskedPaths", "readonlyPaths", "dns", "hosts",
+            "virtualization", "bootLog", "ociRuntimePath", "useInit", "cpuOverhead", "memoryOverhead",
+        ]
+        let methodAllowed: Set
+        switch method.rawValue {
+        case "manager.createContainer":
+            methodAllowed = ["reference", "rootfsSize", "writableLayerSize", "readOnly", "progress"]
+        case "manager.createContainerFromImage":
+            methodAllowed = ["image", "rootfsSize", "writableLayerSize", "readOnly", "progress"]
+        default:
+            methodAllowed = ["image", "rootfs", "writableLayer"]
+        }
+        let decoded = try GhostboxParameters(parameters, allowed: baseAllowed.union(methodAllowed))
+        let managerReference = try decoded.requiredReference("manager", expectedKind: "manager")
+        let manager: GhostboxManagerRecord = try session.value(for: managerReference, expectedKind: "manager")
+        let name = try decoded.requiredString("container")
+        _ = try GhostboxReference.canonical(kind: "container", name: name)
+        let overrides = try GhostboxContainerOverrides(parameters: parameters, decoded: decoded, session: session)
+        let networking = try decoded.optionalBool("networking") ?? true
+        let reference: String
+
+        switch method.rawValue {
+        case "manager.createContainer":
+            reference = try await manager.box.create(
+                id: name,
+                reference: decoded.requiredString("reference"),
+                rootfsSize: try decoded.optionalUInt64("rootfsSize") ?? 8_589_934_592,
+                writableLayerSize: try decoded.optionalUInt64("writableLayerSize"),
+                readOnly: try decoded.optionalBool("readOnly") ?? false,
+                networking: networking,
+                progress: try ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"), session: session
+                ),
+                overrides: overrides,
+                registration: { container, generation in
+                    try ghostboxRegisterContainer(
+                        container, name: name, managerReference: managerReference,
+                        managerBox: manager.box, managerGeneration: generation,
+                        rootfsReference: nil, writableLayerReference: nil,
+                        session: session
+                    )
+                }
+            )
+        case "manager.createContainerFromImage":
+            let imageReference = try decoded.requiredReference("image", expectedKind: "image")
+            reference = try await manager.box.create(
+                id: name,
+                image: ghostboxImageValue(imageReference, session: session),
+                rootfsSize: try decoded.optionalUInt64("rootfsSize") ?? 8_589_934_592,
+                writableLayerSize: try decoded.optionalUInt64("writableLayerSize"),
+                readOnly: try decoded.optionalBool("readOnly") ?? false,
+                networking: networking,
+                progress: try ghostboxProgressHandler(
+                    decoded.optionalReference("progress", expectedKind: "progress-handler"), session: session
+                ),
+                overrides: overrides,
+                registration: { container, generation in
+                    try ghostboxRegisterContainer(
+                        container, name: name, managerReference: managerReference,
+                        managerBox: manager.box, managerGeneration: generation,
+                        rootfsReference: nil, writableLayerReference: nil,
+                        session: session
+                    )
+                }
+            )
+        default:
+            let imageReference = try decoded.requiredReference("image", expectedKind: "image")
+            let suppliedRootfsReference = try decoded.requiredReference("rootfs", expectedKind: "mount")
+            let rootfs: Containerization.Mount = try session.value(for: suppliedRootfsReference, expectedKind: "mount")
+            let writableLayerReference = try decoded.optionalReference("writableLayer", expectedKind: "mount")
+            let writableLayer: Containerization.Mount? = try writableLayerReference.map {
+                try session.value(for: $0, expectedKind: "mount")
+            }
+            reference = try await manager.box.create(
+                id: name,
+                image: ghostboxImageValue(imageReference, session: session),
+                rootfs: rootfs,
+                writableLayer: writableLayer,
+                networking: networking,
+                overrides: overrides,
+                registration: { container, generation in
+                    try ghostboxRegisterContainer(
+                        container, name: name, managerReference: managerReference,
+                        managerBox: manager.box, managerGeneration: generation,
+                        rootfsReference: suppliedRootfsReference,
+                        writableLayerReference: writableLayerReference, session: session
+                    )
+                }
+            )
+        }
+        return .reference(reference)
+    }
+
+    private func manager(_ decoded: GhostboxParameters, session: GhostboxSession) throws -> GhostboxManagerRecord {
+        let reference = try decoded.requiredReference("manager", expectedKind: "manager")
+        return try session.value(for: reference, expectedKind: "manager")
+    }
+}
+
+struct GhostboxLiveContainerCommands: GhostboxDomainHandler {
+    let resource = "container"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        if ghostboxContainerStaticMethods.contains(method.rawValue) {
+            return try await GhostboxContainerCommands().handle(method: method, parameters: parameters, session: session)
+        }
+        if method.rawValue == "container.list" {
+            _ = try GhostboxParameters(parameters, allowed: [])
+            let containers: [(reference: String, value: GhostboxContainerRecord)] = try session.valueSnapshots(
+                ofKind: "container"
+            )
+            return .array(containers.map { reference, record in
+                .object([
+                    "reference": .reference(reference),
+                    "id": .string(record.value.id),
+                    "name": .string(ghostboxReferenceName(reference)),
+                    "managerReference": record.managerReference.map(GhostboxDirectValue.reference) ?? .null,
+                    "status": .string(record.lifecycleStatus.rawValue),
+                    "cpuCount": .integer(Int64(record.value.cpus)),
+                    "memoryBytes": .unsignedInteger(record.value.memoryInBytes),
+                ])
+            })
+        }
+        if method.rawValue == "container.createDirect" {
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["container", "rootfs", "writableLayer", "vmm", "configuration"]
+            )
+            let name = try decoded.requiredString("container")
+            let rootfsReference = try decoded.requiredReference("rootfs", expectedKind: "mount")
+            let rootfs: Containerization.Mount = try session.value(for: rootfsReference, expectedKind: "mount")
+            let writableReference = try decoded.optionalReference("writableLayer", expectedKind: "mount")
+            let writable: Containerization.Mount? = try writableReference.map {
+                try session.value(for: $0, expectedKind: "mount")
+            }
+            let vmmReference = try decoded.requiredReference("vmm", expectedKind: "vmm")
+            let vmm: GhostboxVMMRecord = try session.value(for: vmmReference, expectedKind: "vmm")
+            let configReference = try decoded.requiredReference("configuration", expectedKind: "container-config")
+            let config: LinuxContainer.Configuration = try session.value(
+                for: configReference,
+                expectedKind: "container-config"
+            )
+            let container = try LinuxContainer(
+                name, rootfs: rootfs, writableLayer: writable, vmm: vmm.value, configuration: config
+            )
+            return .reference(try ghostboxRegisterContainer(
+                container, name: name, managerReference: nil, managerBox: nil, managerGeneration: nil,
+                rootfsReference: rootfsReference,
+                writableLayerReference: writableReference, session: session
+            ))
+        }
+
+        let allowed = ghostboxContainerAllowedParameters(method.rawValue)
+        let decoded = try GhostboxParameters(parameters, allowed: allowed)
+        let reference = try decoded.requiredReference("container", expectedKind: "container")
+        let record: GhostboxContainerRecord = try session.value(for: reference, expectedKind: "container")
+        let container = record.value
+        switch method.rawValue {
+        case "container.id": return .string(container.id)
+        case "container.rootfs":
+            if let existing = record.rootfsReference { return .reference(existing) }
+            return .reference(try registerMount(container.rootfs, container: reference, suffix: "rootfs", session: session))
+        case "container.writableLayer":
+            guard let layer = container.writableLayer else { return .null }
+            if let existing = record.writableLayerReference { return .reference(existing) }
+            return .reference(try registerMount(layer, container: reference, suffix: "writable", session: session))
+        case "container.config":
+            let name = "\(ghostboxReferenceName(reference))-config"
+            let configReference = try session.register(
+                kind: "container-config", name: name, value: container.config,
+                equivalent: ghostboxContainerConfigurationEqual
+            )
+            return .reference(configReference)
+        case "container.cpus": return .integer(Int64(container.cpus))
+        case "container.memory": return .unsignedInteger(container.memoryInBytes)
+        case "container.interfaces":
+            let references = try container.interfaces.enumerated().map { index, interface in
+                try session.register(
+                    kind: "interface", name: "\(ghostboxReferenceName(reference))-\(index)",
+                    value: GhostboxInterfaceRecord(value: interface, provenance: nil),
+                    equivalent: ghostboxInterfaceRecordsEqual
+                )
+            }
+            return .references(references)
+        case "container.create":
+            try await container.create()
+            record.setLifecycleStatus(.created)
+            return .void
+        case "container.start":
+            try await container.start()
+            record.setLifecycleStatus(.running)
+            return .void
+        case "container.stop":
+            try await container.stop()
+            record.setLifecycleStatus(.stopped)
+            return .void
+        case "container.kill":
+            try await container.kill(Signal(decoded.requiredString("signal")))
+            record.setLifecycleStatus(.stopping)
+            return .void
+        case "container.wait":
+            let status = try await container.wait(timeoutInSeconds: decoded.optionalInt64("timeoutSeconds"))
+            record.setLifecycleStatus(.exited)
+            return ghostboxExitStatusValue(status)
+        case "container.resize":
+            try await container.resize(to: Terminal.Size(
+                width: decoded.requiredInteger("width", as: UInt16.self),
+                height: decoded.requiredInteger("height", as: UInt16.self)
+            ))
+            return .void
+        case "container.exec":
+            let configReference = try decoded.requiredReference("configuration", expectedKind: "process-config")
+            let config = try ghostboxProcessConfiguration(configReference, session: session)
+            let processName = try decoded.requiredString("process")
+            let process = try await container.exec(processName, configuration: config)
+            return .reference(try ghostboxRegisterProcess(process, name: "\(ghostboxReferenceName(reference))-\(processName)", session: session))
+        case "container.dialVsock":
+            let handle = try await container.dialVsock(port: decoded.requiredInteger("port", as: UInt32.self))
+            return .reference(try ghostboxRegisterFileHandle(handle, session: session))
+        case "container.closeStdin": try await container.closeStdin(); return .void
+        case "container.statistics":
+            return ghostboxStatisticsValue(try await container.statistics(categories: try ghostboxStatCategories(decoded.optionalStringArray("category"))))
+        case "container.filesystemOperation":
+            try await container.filesystemOperation(
+                operation: try ghostboxFilesystemOperation(decoded.requiredString("operation")),
+                path: decoded.requiredString("path")
+            )
+            return .void
+        case "container.copyIn":
+            try await container.copyIn(
+                from: ghostboxHostURL(decoded.requiredString("source")),
+                to: URL(filePath: decoded.requiredString("destination")),
+                mode: try ghostboxFileMode(decoded.optionalString("mode") ?? "0644"),
+                createParents: decoded.optionalBool("createParents") ?? true,
+                chunkSize: decoded.optionalInt("chunkSize") ?? LinuxContainer.defaultCopyChunkSize
+            )
+            return .void
+        case "container.copyOut":
+            try await container.copyOut(
+                from: URL(filePath: decoded.requiredString("source")),
+                to: ghostboxHostURL(decoded.requiredString("destination")),
+                createParents: decoded.optionalBool("createParents") ?? true,
+                chunkSize: decoded.optionalInt("chunkSize") ?? LinuxContainer.defaultCopyChunkSize
+            )
+            return .void
+        default: throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func registerMount(
+        _ mount: Containerization.Mount,
+        container: String,
+        suffix: String,
+        session: GhostboxSession
+    ) throws -> String {
+        try session.register(
+            kind: "mount", name: "\(ghostboxReferenceName(container))-\(suffix)",
+            value: mount, equivalent: ghostboxMountEqual
+        )
+    }
+}
+
+struct GhostboxProcessCommands: GhostboxDomainHandler {
+    let resource = "process"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        let allowed: Set
+        switch method.rawValue {
+        case "process.kill": allowed = ["process", "signal"]
+        case "process.resize": allowed = ["process", "width", "height"]
+        case "process.wait": allowed = ["process", "timeoutSeconds"]
+        default: allowed = ["process"]
+        }
+        let decoded = try GhostboxParameters(parameters, allowed: allowed)
+        let reference = try decoded.requiredReference("process", expectedKind: "process")
+        let process: LinuxProcess = try session.value(for: reference, expectedKind: "process")
+        switch method.rawValue {
+        case "process.id": return .string(process.id)
+        case "process.owningContainer": return process.owningContainer.map(GhostboxDirectValue.string) ?? .null
+        case "process.pid": return .integer(Int64(process.pid))
+        case "process.start": try await process.start(); return .void
+        case "process.kill": try await process.kill(Signal(decoded.requiredString("signal"))); return .void
+        case "process.resize":
+            try await process.resize(to: Terminal.Size(
+                width: decoded.requiredInteger("width", as: UInt16.self),
+                height: decoded.requiredInteger("height", as: UInt16.self)
+            ))
+            return .void
+        case "process.closeStdin": try await process.closeStdin(); return .void
+        case "process.wait": return ghostboxExitStatusValue(try await process.wait(timeoutInSeconds: decoded.optionalInt64("timeoutSeconds")))
+        case "process.delete":
+            try await process.delete()
+            try session.unregister(reference, expectedKind: "process", matching: process)
+            return .void
+        default: throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+enum GhostboxLifecycleCommandHandlers {
+    static let all: [any GhostboxDomainHandler] = [
+        GhostboxManagerCommands(),
+        GhostboxLiveContainerCommands(),
+        GhostboxProcessCommands(),
+    ]
+}
+
+struct GhostboxManagerRecord: Sendable {
+    let box: GhostboxManagerBox
+    let imageStoreReference: String
+    let ownsImageStoreReference: Bool
+    let provenance: String
+}
+
+actor GhostboxManagerBox {
+    private var value: ContainerManager
+    private var containerGenerations: [String: UUID] = [:]
+    private var operationInProgress = false
+    private var operationWaiters: [CheckedContinuation] = []
+    private var retired = false
+
+    init(_ value: ContainerManager) { self.value = value }
+
+    func releaseNetwork(_ id: String) async throws {
+        await acquireOperation()
+        defer { releaseOperation() }
+        try ensureActive()
+        try value.releaseNetwork(id)
+    }
+
+    func delete(_ id: String, generation: UUID) async throws {
+        await acquireOperation()
+        defer { releaseOperation() }
+        try ensureActive()
+        guard containerGenerations[id] == generation else { return }
+        var manager = value
+        do {
+            try manager.delete(id)
+            value = manager
+            containerGenerations.removeValue(forKey: id)
+        } catch {
+            value = manager
+            throw error
+        }
+    }
+
+    func create(
+        id: String, reference: String, rootfsSize: UInt64, writableLayerSize: UInt64?, readOnly: Bool,
+        networking: Bool, progress: ProgressHandler?, overrides: GhostboxContainerOverrides,
+        registration: @Sendable (LinuxContainer, UUID) throws -> String
+    ) async throws -> String {
+        await acquireOperation()
+        do {
+            try ensureActive()
+        } catch {
+            releaseOperation()
+            throw error
+        }
+        var manager = value
+        var allocated: LinuxContainer?
+        do {
+            let container = try await manager.create(
+                id, reference: reference, rootfsSizeInBytes: rootfsSize,
+                writableLayerSizeInBytes: writableLayerSize, readOnly: readOnly,
+                networking: networking, progress: progress
+            ) { try overrides.apply(to: &$0) }
+            allocated = container
+            let generation = UUID()
+            containerGenerations[id] = generation
+            let reference = try registration(container, generation)
+            value = manager
+            releaseOperation()
+            return reference
+        } catch {
+            if allocated != nil {
+                do {
+                    try manager.delete(id)
+                    containerGenerations.removeValue(forKey: id)
+                } catch {}
+            }
+            value = manager
+            releaseOperation()
+            throw error
+        }
+    }
+
+    func create(
+        id: String, image: Containerization.Image, rootfsSize: UInt64, writableLayerSize: UInt64?,
+        readOnly: Bool, networking: Bool, progress: ProgressHandler?, overrides: GhostboxContainerOverrides,
+        registration: @Sendable (LinuxContainer, UUID) throws -> String
+    ) async throws -> String {
+        await acquireOperation()
+        do {
+            try ensureActive()
+        } catch {
+            releaseOperation()
+            throw error
+        }
+        var manager = value
+        var allocated: LinuxContainer?
+        do {
+            let container = try await manager.create(
+                id, image: image, rootfsSizeInBytes: rootfsSize,
+                writableLayerSizeInBytes: writableLayerSize, readOnly: readOnly,
+                networking: networking, progress: progress
+            ) { try overrides.apply(to: &$0) }
+            allocated = container
+            let generation = UUID()
+            containerGenerations[id] = generation
+            let reference = try registration(container, generation)
+            value = manager
+            releaseOperation()
+            return reference
+        } catch {
+            if allocated != nil {
+                do {
+                    try manager.delete(id)
+                    containerGenerations.removeValue(forKey: id)
+                } catch {}
+            }
+            value = manager
+            releaseOperation()
+            throw error
+        }
+    }
+
+    func create(
+        id: String, image: Containerization.Image, rootfs: Containerization.Mount,
+        writableLayer: Containerization.Mount?, networking: Bool, overrides: GhostboxContainerOverrides,
+        registration: @Sendable (LinuxContainer, UUID) throws -> String
+    ) async throws -> String {
+        await acquireOperation()
+        do {
+            try ensureActive()
+        } catch {
+            releaseOperation()
+            throw error
+        }
+        var manager = value
+        var allocated: LinuxContainer?
+        do {
+            let container = try await manager.create(
+                id, image: image, rootfs: rootfs, writableLayer: writableLayer, networking: networking
+            ) { try overrides.apply(to: &$0) }
+            allocated = container
+            let generation = UUID()
+            containerGenerations[id] = generation
+            let reference = try registration(container, generation)
+            value = manager
+            releaseOperation()
+            return reference
+        } catch {
+            if allocated != nil {
+                do {
+                    try manager.delete(id)
+                    containerGenerations.removeValue(forKey: id)
+                } catch {}
+            }
+            value = manager
+            releaseOperation()
+            throw error
+        }
+    }
+
+    func cleanup(_ container: LinuxContainer, generation: UUID) async {
+        await acquireOperation()
+        defer { releaseOperation() }
+
+        try? await container.stop()
+        guard containerGenerations[container.id] == generation else { return }
+        var manager = value
+        do {
+            try manager.delete(container.id)
+            containerGenerations.removeValue(forKey: container.id)
+        } catch {}
+        value = manager
+    }
+
+    func cleanupAllocations() async {
+        await acquireOperation()
+        defer { releaseOperation() }
+
+        var manager = value
+        for id in Array(containerGenerations.keys) {
+            do {
+                try manager.delete(id)
+                containerGenerations.removeValue(forKey: id)
+            } catch {}
+        }
+        value = manager
+    }
+
+    func retireIfUnused(reference: String) async throws {
+        await acquireOperation()
+        defer { releaseOperation() }
+        try ensureActive()
+        guard containerGenerations.isEmpty else {
+            throw DirectDispatchError(
+                .failedPrecondition,
+                "manager '\(reference)' still has managed containers"
+            )
+        }
+        retired = true
+    }
+
+    private func ensureActive() throws {
+        guard !retired else {
+            throw DirectDispatchError(.failedPrecondition, "manager is closed")
+        }
+    }
+
+    private func acquireOperation() async {
+        if !operationInProgress {
+            operationInProgress = true
+            return
+        }
+        await withCheckedContinuation { continuation in
+            operationWaiters.append(continuation)
+        }
+    }
+
+    private func releaseOperation() {
+        guard !operationWaiters.isEmpty else {
+            operationInProgress = false
+            return
+        }
+        operationWaiters.removeFirst().resume()
+    }
+}
+
+enum GhostboxContainerLifecycleStatus: String, Sendable {
+    case configured
+    case created
+    case running
+    case stopping
+    case stopped
+    case exited
+}
+
+struct GhostboxContainerRecord: Sendable {
+    let value: LinuxContainer
+    let managerReference: String?
+    let managerGeneration: UUID?
+    let rootfsReference: String?
+    let writableLayerReference: String?
+    private let status: GhostboxMutableSlot
+
+    init(
+        value: LinuxContainer,
+        managerReference: String?,
+        managerGeneration: UUID?,
+        rootfsReference: String?,
+        writableLayerReference: String?,
+        lifecycleStatus: GhostboxContainerLifecycleStatus = .configured
+    ) {
+        self.value = value
+        self.managerReference = managerReference
+        self.managerGeneration = managerGeneration
+        self.rootfsReference = rootfsReference
+        self.writableLayerReference = writableLayerReference
+        status = GhostboxMutableSlot(lifecycleStatus)
+    }
+
+    var lifecycleStatus: GhostboxContainerLifecycleStatus { status.get() }
+
+    func setLifecycleStatus(_ lifecycleStatus: GhostboxContainerLifecycleStatus) {
+        status.set(lifecycleStatus)
+    }
+}
+
+struct GhostboxContainerOverrides: Sendable {
+    let process: LinuxProcessConfiguration?
+    let cpus: Int?
+    let memory: UInt64?
+    let hostname: String?
+    let hasHostname: Bool
+    let sysctl: [String: String]?
+    let interfaces: [any Interface]?
+    let sockets: [UnixSocketConfiguration]?
+    let mounts: [Containerization.Mount]?
+    let maskedPaths: [String]?
+    let readonlyPaths: [String]?
+    let dns: DNS?
+    let hosts: Hosts?
+    let virtualization: Bool?
+    let bootLog: BootLog?
+    let ociRuntimePath: String?
+    let hasOCIRuntimePath: Bool
+    let useInit: Bool?
+    let cpuOverhead: Int?
+    let memoryOverhead: UInt64?
+
+    init(parameters: [String: GhostboxJSONValue], decoded: GhostboxParameters, session: GhostboxSession) throws {
+        process = try decoded.optionalReference("process", expectedKind: "process-config").map {
+            try ghostboxProcessConfiguration($0, session: session)
+        }
+        cpus = try decoded.optionalInt("cpus")
+        memory = try decoded.optionalUInt64("memory")
+        hostname = try decoded.optionalString("hostname")
+        hasHostname = parameters["hostname"] != nil
+        sysctl = try decoded.optionalStringArray("sysctl").map(ghostboxParseAssignments)
+        interfaces = try decoded.optionalReferences("interfaces", expectedKind: "interface").map { references in
+            try references.map { try session.value(for: $0, expectedKind: "interface", as: (any Interface).self) }
+        }
+        sockets = try decoded.optionalReferences("sockets", expectedKind: "socket").map { references in
+            try references.map { try session.value(for: $0, expectedKind: "socket") }
+        }
+        mounts = try decoded.optionalReferences("mounts", expectedKind: "mount").map { references in
+            try references.map { try session.value(for: $0, expectedKind: "mount") }
+        }
+        maskedPaths = try decoded.optionalStringArray("maskedPaths")
+        readonlyPaths = try decoded.optionalStringArray("readonlyPaths")
+        dns = try decoded.optionalReference("dns", expectedKind: "dns").map {
+            try session.value(for: $0, expectedKind: "dns")
+        }
+        hosts = try decoded.optionalReference("hosts", expectedKind: "hosts").map {
+            let record: GhostboxHostsRecord = try session.value(for: $0, expectedKind: "hosts")
+            return record.value
+        }
+        virtualization = try decoded.optionalBool("virtualization")
+        bootLog = try decoded.optionalReference("bootLog", expectedKind: "boot-log").map {
+            try session.value(for: $0, expectedKind: "boot-log")
+        }
+        ociRuntimePath = try decoded.optionalString("ociRuntimePath")
+        hasOCIRuntimePath = parameters["ociRuntimePath"] != nil
+        useInit = try decoded.optionalBool("useInit")
+        cpuOverhead = try decoded.optionalInt("cpuOverhead")
+        memoryOverhead = try decoded.optionalUInt64("memoryOverhead")
+    }
+
+    func apply(to config: inout LinuxContainer.Configuration) throws {
+        if let process { config.process = process }
+        if let cpus { config.cpus = cpus }
+        if let memory { config.memoryInBytes = memory }
+        if hasHostname { config.hostname = hostname }
+        if let sysctl { config.sysctl = sysctl }
+        if let interfaces { config.interfaces = interfaces }
+        if let sockets { config.sockets = sockets }
+        if let mounts { config.mounts = mounts }
+        if let maskedPaths { config.maskedPaths = maskedPaths }
+        if let readonlyPaths { config.readonlyPaths = readonlyPaths }
+        if let dns { config.dns = dns }
+        if let hosts { config.hosts = hosts }
+        if let virtualization { config.virtualization = virtualization }
+        if let bootLog { config.bootLog = bootLog }
+        if hasOCIRuntimePath { config.ociRuntimePath = ociRuntimePath }
+        if let useInit { config.useInit = useInit }
+        if let overhead = GhostboxResourceOverheadPolicy.cpu(requested: cpus, explicit: cpuOverhead) {
+            config.cpuOverhead = overhead
+        }
+        if let overhead = GhostboxResourceOverheadPolicy.memory(requested: memory, explicit: memoryOverhead) {
+            config.memoryOverhead = overhead
+        }
+    }
+}
+
+private let ghostboxContainerStaticMethods: Set = [
+    "container.defaultMounts", "container.defaultOCIMounts", "container.defaultMaskedPaths",
+    "container.defaultReadonlyPaths", "container.defaultCopyChunkSize", "container.maxIDLength",
+]
+
+private func ghostboxContainerAllowedParameters(_ method: String) -> Set {
+    switch method {
+    case "container.kill": return ["container", "signal"]
+    case "container.wait": return ["container", "timeoutSeconds"]
+    case "container.resize": return ["container", "width", "height"]
+    case "container.exec": return ["container", "process", "configuration"]
+    case "container.dialVsock": return ["container", "port"]
+    case "container.statistics": return ["container", "category"]
+    case "container.filesystemOperation": return ["container", "operation", "path"]
+    case "container.copyIn": return ["container", "source", "destination", "mode", "createParents", "chunkSize"]
+    case "container.copyOut": return ["container", "source", "destination", "createParents", "chunkSize"]
+    default: return ["container"]
+    }
+}
+
+func ghostboxRegisterContainer(
+    _ container: LinuxContainer,
+    name: String,
+    managerReference: String?,
+    managerBox: GhostboxManagerBox?,
+    managerGeneration: UUID?,
+    rootfsReference: String?,
+    writableLayerReference: String?,
+    session: GhostboxSession
+) throws -> String {
+    let record = GhostboxContainerRecord(
+        value: container, managerReference: managerReference,
+        managerGeneration: managerGeneration,
+        rootfsReference: rootfsReference, writableLayerReference: writableLayerReference
+    )
+    return try session.register(
+        kind: "container", name: name, value: record,
+        equivalent: { $0.value === $1.value },
+        cleanupPriority: 80,
+        cleanup: {
+            if let managerBox, let managerGeneration {
+                await managerBox.cleanup($0.value, generation: managerGeneration)
+            } else {
+                try? await $0.value.stop()
+            }
+        }
+    )
+}
+
+func ghostboxRegisterProcess(_ process: LinuxProcess, name: String, session: GhostboxSession) throws -> String {
+    try session.register(
+        kind: "process", name: name, value: process, equivalent: { $0 === $1 },
+        cleanupPriority: 90,
+        cleanup: { try? await $0.delete() }
+    )
+}
+
+func ghostboxRegisterFileHandle(_ handle: FileHandle, session: GhostboxSession) throws -> String {
+    try session.register(
+        kind: "file-handle", name: UUID().uuidString.lowercased(), value: handle,
+        equivalent: { $0 === $1 },
+        cleanupPriority: 100,
+        cleanup: { try? $0.close() }
+    )
+}
+
+func ghostboxExitStatusValue(_ status: ExitStatus) -> GhostboxDirectValue {
+    .object([
+        "exitCode": .integer(Int64(status.exitCode)),
+        "exitedAt": .string(ISO8601DateFormatter().string(from: status.exitedAt)),
+    ])
+}
+
+func ghostboxStatCategories(_ names: [String]?) throws -> StatCategory {
+    guard let names, !names.isEmpty else { return .all }
+    var result: StatCategory = []
+    for name in names {
+        switch name {
+        case "all": result.formUnion(.all)
+        case "process": result.insert(.process)
+        case "memory": result.insert(.memory)
+        case "cpu": result.insert(.cpu)
+        case "block-io": result.insert(.blockIO)
+        case "network": result.insert(.network)
+        case "memory-events": result.insert(.memoryEvents)
+        default: throw DirectDispatchError(.invalidArgument, "unknown statistics category '\(name)'")
+        }
+    }
+    return result
+}
+
+func ghostboxStatisticsValue(_ statistics: ContainerStatistics) -> GhostboxDirectValue {
+    var result: [String: GhostboxDirectValue] = ["id": .string(statistics.id)]
+    if let process = statistics.process {
+        result["process"] = .object(["current": .unsignedInteger(process.current), "limit": .unsignedInteger(process.limit)])
+    }
+    if let memory = statistics.memory {
+        result["memory"] = .object([
+            "usageBytes": .unsignedInteger(memory.usageBytes), "limitBytes": .unsignedInteger(memory.limitBytes),
+            "swapUsageBytes": .unsignedInteger(memory.swapUsageBytes), "swapLimitBytes": .unsignedInteger(memory.swapLimitBytes),
+            "cacheBytes": .unsignedInteger(memory.cacheBytes), "kernelStackBytes": .unsignedInteger(memory.kernelStackBytes),
+            "slabBytes": .unsignedInteger(memory.slabBytes), "pageFaults": .unsignedInteger(memory.pageFaults),
+            "majorPageFaults": .unsignedInteger(memory.majorPageFaults), "inactiveFile": .unsignedInteger(memory.inactiveFile),
+            "anon": .unsignedInteger(memory.anon), "workingsetRefaultAnon": .unsignedInteger(memory.workingsetRefaultAnon),
+            "workingsetRefaultFile": .unsignedInteger(memory.workingsetRefaultFile),
+            "pgstealKswapd": .unsignedInteger(memory.pgstealKswapd), "pgstealDirect": .unsignedInteger(memory.pgstealDirect),
+            "pgstealKhugepaged": .unsignedInteger(memory.pgstealKhugepaged),
+        ])
+    }
+    if let cpu = statistics.cpu {
+        result["cpu"] = .object([
+            "usageUsec": .unsignedInteger(cpu.usageUsec), "userUsec": .unsignedInteger(cpu.userUsec),
+            "systemUsec": .unsignedInteger(cpu.systemUsec), "throttlingPeriods": .unsignedInteger(cpu.throttlingPeriods),
+            "throttledPeriods": .unsignedInteger(cpu.throttledPeriods), "throttledTimeUsec": .unsignedInteger(cpu.throttledTimeUsec),
+        ])
+    }
+    if let blockIO = statistics.blockIO {
+        result["blockIO"] = .array(blockIO.devices.map { device in
+            .object([
+                "major": .unsignedInteger(device.major), "minor": .unsignedInteger(device.minor),
+                "readBytes": .unsignedInteger(device.readBytes), "writeBytes": .unsignedInteger(device.writeBytes),
+                "readOperations": .unsignedInteger(device.readOperations), "writeOperations": .unsignedInteger(device.writeOperations),
+            ])
+        })
+    }
+    if let networks = statistics.networks {
+        result["networks"] = .array(networks.map { network in
+            .object([
+                "interface": .string(network.interface), "receivedPackets": .unsignedInteger(network.receivedPackets),
+                "transmittedPackets": .unsignedInteger(network.transmittedPackets), "receivedBytes": .unsignedInteger(network.receivedBytes),
+                "transmittedBytes": .unsignedInteger(network.transmittedBytes), "receivedErrors": .unsignedInteger(network.receivedErrors),
+                "transmittedErrors": .unsignedInteger(network.transmittedErrors),
+            ])
+        })
+    }
+    if let events = statistics.memoryEvents {
+        result["memoryEvents"] = .object([
+            "low": .unsignedInteger(events.low), "high": .unsignedInteger(events.high), "max": .unsignedInteger(events.max),
+            "oom": .unsignedInteger(events.oom), "oomKill": .unsignedInteger(events.oomKill),
+        ])
+    }
+    return .object(result)
+}
+
+func ghostboxFilesystemOperation(_ raw: String) throws -> FilesystemOperation {
+    switch raw {
+    case "freeze": return .freeze
+    case "thaw": return .thaw
+    case "trim": return .trim
+    default: throw DirectDispatchError(.invalidArgument, "unknown filesystem operation '\(raw)'")
+    }
+}
+
+func ghostboxHostURL(_ raw: String) -> URL {
+    if let url = URL(string: raw), url.scheme != nil { return url }
+    return URL(filePath: raw)
+}
+
+private func ghostboxManagerNetwork(_ decoded: GhostboxParameters, session: GhostboxSession) throws -> (any Network)? {
+    guard let reference = try decoded.optionalReference("network", expectedKind: "network") else {
+        return session.contextValue(ghostboxSharedNetworkContextKey, as: GhostboxNetwork.self)
+    }
+    return try ghostboxNetwork(reference, session: session)
+}
+
+private func ghostboxInitBlock(reference: String, imageStore: ImageStore) async throws -> Containerization.Mount {
+    let directory = imageStore.path.appendingPathComponent("ghostbox/initfs", isDirectory: true)
+    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    let path = directory.appendingPathComponent(String(reference.stableHash, radix: 16) + ".ext4")
+    let image = try await imageStore.getInitImage(reference: reference)
+    do {
+        return try await image.initBlock(at: path, for: .linuxArm)
+    } catch let error as ContainerizationError {
+        guard error.code == .exists else { throw error }
+        return .block(format: "ext4", source: path.absolutePath(), destination: "/", options: ["ro"])
+    }
+}
+
+private func ghostboxParseAssignments(_ assignments: [String]) throws -> [String: String] {
+    var result: [String: String] = [:]
+    for assignment in assignments {
+        guard let separator = assignment.firstIndex(of: "="), separator != assignment.startIndex else {
+            throw DirectDispatchError(.invalidArgument, "value '\(assignment)' must use KEY=VALUE syntax")
+        }
+        let key = String(assignment[.. UInt32 {
+    let digits = raw.hasPrefix("0o") ? String(raw.dropFirst(2)) : raw
+    guard let value = UInt32(digits, radix: 8), value <= 0o7777 else {
+        throw DirectDispatchError(.invalidArgument, "file mode must be an octal value")
+    }
+    return value
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxNetworkCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxNetworkCommands.swift
new file mode 100644
index 0000000..9b2bd98
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxNetworkCommands.swift
@@ -0,0 +1,384 @@
+import Containerization
+import ContainerizationExtras
+import Foundation
+import GhostVMKit
+import Virtualization
+import vmnet
+
+struct GhostboxNetworkCommands: GhostboxDomainHandler {
+    let resource = "network"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "network.vmnetCreate":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["network", "mode", "subnet", "prefixV6"]
+            )
+            let name = try decoded.requiredString("network")
+            let mode = try ghostboxNetworkMode(decoded.optionalString("mode") ?? "shared")
+            let subnet = try decoded.optionalString("subnet").map {
+                try ghostboxCIDRv4($0, parameter: "subnet")
+            }
+            let prefixV6 = try decoded.optionalString("prefixV6").map {
+                try ghostboxCIDRv6($0, parameter: "prefixV6")
+            }
+            let network: GhostboxNetwork
+            if let shared: GhostboxNetwork = session.contextValue(ghostboxSharedNetworkContextKey) {
+                guard mode == .VMNET_SHARED_MODE else {
+                    throw DirectDispatchError(.invalidArgument, "the GhostVM network only supports shared mode")
+                }
+                guard subnet == nil || subnet == shared.subnet else {
+                    throw DirectDispatchError(.invalidArgument, "the requested subnet does not match the GhostVM network")
+                }
+                guard prefixV6 == nil else {
+                    throw DirectDispatchError(.unsupported, "the GhostVM shared network does not provide IPv6")
+                }
+                network = shared
+            } else {
+                network = try GhostboxNetwork(mode: mode, subnet: subnet, prefixV6: prefixV6)
+            }
+            let reference = try session.registerNew(
+                kind: "network",
+                name: name,
+                makeValue: {
+                    GhostboxMutableSlot(GhostboxNetworkRecord(
+                        value: network
+                    ))
+                },
+                equivalent: {
+                    let lhs = $0.get()
+                    let rhs = $1.get()
+                    return lhs.retired == rhs.retired && ghostboxNetworksEqual(lhs.value, rhs.value)
+                }
+            )
+            return .reference(reference)
+
+        case GhostboxDirectMethod.networkDelete.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["network"])
+            let reference = try decoded.requiredReference("network", expectedKind: "network")
+            let slot: GhostboxMutableSlot = try session.mutableValue(
+                for: reference,
+                expectedKind: "network"
+            )
+            try slot.update { record in
+                guard !record.retired else {
+                    throw DirectDispatchError(.failedPrecondition, "network '\(reference)' is closing")
+                }
+                guard record.allocationIDs.isEmpty else {
+                    throw DirectDispatchError(
+                        .failedPrecondition,
+                        "network '\(reference)' still has allocated interfaces"
+                    )
+                }
+                record.retired = true
+            }
+            try session.unregister(reference, expectedKind: "network", matching: slot)
+            return .void
+
+        case "network.subnet", "network.prefixV6", "network.ipv4Gateway", "network.ipv6Gateway":
+            let decoded = try GhostboxParameters(parameters, allowed: ["network"])
+            let reference = try decoded.requiredReference("network", expectedKind: "network")
+            let network = try ghostboxNetwork(reference, session: session)
+            switch method.rawValue {
+            case "network.subnet":
+                return .string(network.subnet.description)
+            case "network.prefixV6":
+                return network.prefixV6.map { .string($0.description) } ?? .null
+            case "network.ipv4Gateway":
+                return .string(network.ipv4Gateway.description)
+            default:
+                return network.ipv6Gateway.map { .string($0.description) } ?? .null
+            }
+
+        case "network.createInterface", "network.createInterfaceMtu", "network.createInterfaceWithoutGateway":
+            let allowed: Set = method.rawValue == "network.createInterfaceMtu"
+                ? ["network", "interface", "mtu"]
+                : ["network", "interface"]
+            let decoded = try GhostboxParameters(parameters, allowed: allowed)
+            let networkReference = try decoded.requiredReference("network", expectedKind: "network")
+            let name = try decoded.requiredString("interface")
+            _ = try GhostboxReference.canonical(kind: "interface", name: name)
+            let slot: GhostboxMutableSlot = try session.mutableValue(
+                for: networkReference,
+                expectedKind: "network"
+            )
+            var interface: (any Interface)?
+            try slot.update { record in
+                guard !record.retired else {
+                    throw DirectDispatchError(.failedPrecondition, "network '\(networkReference)' is closing")
+                }
+                switch method.rawValue {
+                case "network.createInterface":
+                    interface = try record.value.createInterface(name)
+                case "network.createInterfaceMtu":
+                    interface = try record.value.createInterface(
+                        name,
+                        mtu: decoded.requiredInteger("mtu", as: UInt32.self)
+                    )
+                default:
+                    interface = try record.value.createInterfaceWithoutGateway(name)
+                }
+                if interface != nil { record.allocationIDs.insert(name) }
+            }
+            guard let interface else { return .null }
+
+            let record = GhostboxInterfaceRecord(
+                value: interface,
+                provenance: .init(networkReference: networkReference, allocationID: name)
+            )
+            do {
+                let reference = try session.register(
+                    kind: "interface",
+                    name: name,
+                    value: record,
+                    equivalent: ghostboxInterfaceRecordsEqual
+                )
+                return .reference(reference)
+            } catch {
+                try? slot.update {
+                    try $0.value.releaseInterface(name)
+                    $0.allocationIDs.remove(name)
+                }
+                throw error
+            }
+
+        case "network.releaseInterface":
+            let decoded = try GhostboxParameters(parameters, allowed: ["network", "interface"])
+            let networkReference = try decoded.requiredReference("network", expectedKind: "network")
+            let interfaceReference = try decoded.requiredReference("interface", expectedKind: "interface")
+            let record = try ghostboxInterfaceRecord(interfaceReference, session: session)
+            guard let provenance = record.provenance else {
+                throw DirectDispatchError(
+                    .invalidArgument,
+                    "interface '\(interfaceReference)' was not allocated by a network"
+                )
+            }
+            guard provenance.networkReference == networkReference else {
+                throw DirectDispatchError(
+                    .invalidArgument,
+                    "interface '\(interfaceReference)' does not belong to network '\(networkReference)'"
+                )
+            }
+            let slot: GhostboxMutableSlot = try session.mutableValue(
+                for: networkReference,
+                expectedKind: "network"
+            )
+            try slot.update {
+                guard !$0.retired else {
+                    throw DirectDispatchError(.failedPrecondition, "network '\(networkReference)' is closing")
+                }
+                try $0.value.releaseInterface(provenance.allocationID)
+                $0.allocationIDs.remove(provenance.allocationID)
+            }
+            try session.unregister(interfaceReference, expectedKind: "interface", matching: record)
+            return .void
+
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+struct GhostboxNetworkRecord: Sendable {
+    var value: GhostboxNetwork
+    var allocationIDs: Set = []
+    var retired = false
+}
+
+func ghostboxNetwork(_ reference: String, session: GhostboxSession) throws -> GhostboxNetwork {
+    let record: GhostboxNetworkRecord = try session.valueSnapshot(
+        for: reference,
+        expectedKind: "network"
+    )
+    guard !record.retired else {
+        throw DirectDispatchError(.failedPrecondition, "network '\(reference)' is closing")
+    }
+    return record.value
+}
+
+struct GhostboxInterfaceCommands: GhostboxDomainHandler {
+    let resource = "interface"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "interface.natCreate":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: [
+                    "interface", "ipv4Address", "ipv4Gateway", "ipv6Address",
+                    "ipv6Gateway", "macAddress", "mtu",
+                ]
+            )
+            let interface = NATInterface(
+                ipv4Address: try ghostboxCIDRv4(
+                    decoded.requiredString("ipv4Address"),
+                    parameter: "ipv4Address"
+                ),
+                ipv4Gateway: try decoded.optionalString("ipv4Gateway").map {
+                    try ghostboxIPv4Address($0, parameter: "ipv4Gateway")
+                },
+                ipv6Address: try decoded.optionalString("ipv6Address").map {
+                    try ghostboxCIDRv6($0, parameter: "ipv6Address")
+                },
+                ipv6Gateway: try decoded.optionalString("ipv6Gateway").map {
+                    try ghostboxIPv6Address($0, parameter: "ipv6Gateway")
+                },
+                macAddress: try decoded.optionalString("macAddress").map {
+                    try ghostboxMACAddress($0, parameter: "macAddress")
+                },
+                mtu: try decoded.optionalInteger("mtu", as: UInt32.self) ?? 1500
+            )
+            let record = GhostboxInterfaceRecord(value: interface, provenance: nil)
+            let reference = try session.register(
+                kind: "interface",
+                name: decoded.requiredString("interface"),
+                value: record,
+                equivalent: ghostboxInterfaceRecordsEqual
+            )
+            return .reference(reference)
+
+        case "interface.ipv4Address", "interface.ipv4Gateway", "interface.ipv6Address",
+             "interface.ipv6Gateway", "interface.macAddress", "interface.mtu":
+            let decoded = try GhostboxParameters(parameters, allowed: ["interface"])
+            let reference = try decoded.requiredReference("interface", expectedKind: "interface")
+            let interface = try ghostboxInterface(reference, session: session)
+            switch method.rawValue {
+            case "interface.ipv4Address":
+                return .string(interface.ipv4Address.description)
+            case "interface.ipv4Gateway":
+                return interface.ipv4Gateway.map { .string($0.description) } ?? .null
+            case "interface.ipv6Address":
+                return interface.ipv6Address.map { .string($0.description) } ?? .null
+            case "interface.ipv6Gateway":
+                return interface.ipv6Gateway.map { .string($0.description) } ?? .null
+            case "interface.macAddress":
+                return interface.macAddress.map { .string($0.description) } ?? .null
+            default:
+                return .unsignedInteger(UInt64(interface.mtu))
+            }
+
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+struct GhostboxInterfaceProvenance: Sendable, Equatable {
+    let networkReference: String
+    let allocationID: String
+}
+
+struct GhostboxInterfaceRecord: Interface, VZInterface, Sendable {
+    let value: any Interface
+    let provenance: GhostboxInterfaceProvenance?
+
+    var ipv4Address: CIDRv4 { value.ipv4Address }
+    var ipv4Gateway: IPv4Address? { value.ipv4Gateway }
+    var ipv6Address: CIDRv6? { value.ipv6Address }
+    var ipv6Gateway: IPv6Address? { value.ipv6Gateway }
+    var macAddress: MACAddress? { value.macAddress }
+    var mtu: UInt32 { value.mtu }
+
+    func device() throws -> VZVirtioNetworkDeviceConfiguration {
+        guard let value = value as? any VZInterface else {
+            throw DirectDispatchError(.invalidArgument, "interface type is not supported by Virtualization")
+        }
+        return try value.device()
+    }
+}
+
+func ghostboxInterface(
+    _ reference: String,
+    session: GhostboxSession
+) throws -> any Interface {
+    try ghostboxInterfaceRecord(reference, session: session).value
+}
+
+func ghostboxInterfaceRecord(
+    _ reference: String,
+    session: GhostboxSession
+) throws -> GhostboxInterfaceRecord {
+    try session.value(for: reference, expectedKind: "interface")
+}
+
+private func ghostboxNetworkMode(_ value: String) throws -> vmnet.operating_modes_t {
+    switch value {
+    case "shared": return .VMNET_SHARED_MODE
+    case "host": return .VMNET_HOST_MODE
+    case "bridged": return .VMNET_BRIDGED_MODE
+    default:
+        throw DirectDispatchError(.invalidArgument, "unknown network mode '\(value)'")
+    }
+}
+
+private func ghostboxCIDRv4(_ value: String, parameter: String) throws -> CIDRv4 {
+    try ghostboxCIDR(value, parameter: parameter, parse: CIDRv4.init)
+}
+
+private func ghostboxCIDRv6(_ value: String, parameter: String) throws -> CIDRv6 {
+    try ghostboxCIDR(value, parameter: parameter, parse: CIDRv6.init)
+}
+
+private func ghostboxCIDR(
+    _ value: String,
+    parameter: String,
+    parse: (String) throws -> Value
+) throws -> Value {
+    guard value.split(separator: "/", omittingEmptySubsequences: false).count == 2 else {
+        throw DirectDispatchError(.invalidArgument, "parameter '\(parameter)' is not a valid CIDR value")
+    }
+    return try ghostboxParsed(value, parameter: parameter, parse: parse)
+}
+
+private func ghostboxIPv4Address(_ value: String, parameter: String) throws -> IPv4Address {
+    try ghostboxParsed(value, parameter: parameter, parse: IPv4Address.init)
+}
+
+private func ghostboxIPv6Address(_ value: String, parameter: String) throws -> IPv6Address {
+    try ghostboxParsed(value, parameter: parameter, parse: IPv6Address.init)
+}
+
+private func ghostboxMACAddress(_ value: String, parameter: String) throws -> MACAddress {
+    try ghostboxParsed(value, parameter: parameter, parse: MACAddress.init)
+}
+
+private func ghostboxParsed(
+    _ value: String,
+    parameter: String,
+    parse: (String) throws -> Value
+) throws -> Value {
+    do {
+        return try parse(value)
+    } catch {
+        throw DirectDispatchError(
+            .invalidArgument,
+            "parameter '\(parameter)' is malformed: \(error.localizedDescription)"
+        )
+    }
+}
+
+private func ghostboxNetworksEqual(_ lhs: GhostboxNetwork, _ rhs: GhostboxNetwork) -> Bool {
+    lhs.subnet == rhs.subnet && lhs.prefixV6 == rhs.prefixV6
+}
+
+func ghostboxInterfaceRecordsEqual(
+    _ lhs: GhostboxInterfaceRecord,
+    _ rhs: GhostboxInterfaceRecord
+) -> Bool {
+    lhs.ipv4Address == rhs.ipv4Address
+        && lhs.ipv4Gateway == rhs.ipv4Gateway
+        && lhs.ipv6Address == rhs.ipv6Address
+        && lhs.ipv6Gateway == rhs.ipv6Gateway
+        && lhs.macAddress == rhs.macAddress
+        && lhs.mtu == rhs.mtu
+        && lhs.provenance == rhs.provenance
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxParameters.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxParameters.swift
new file mode 100644
index 0000000..2d182e9
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxParameters.swift
@@ -0,0 +1,201 @@
+import Foundation
+import GhostVMKit
+
+struct GhostboxParameters: Sendable {
+    private let values: [String: GhostboxJSONValue]
+
+    init(_ values: [String: GhostboxJSONValue], allowed: Set) throws {
+        if let unknown = values.keys.sorted().first(where: { !allowed.contains($0) }) {
+            throw DirectDispatchError(.invalidArgument, "unknown parameter '\(unknown)'")
+        }
+        self.values = values
+    }
+
+    func contains(_ name: String) -> Bool {
+        values[name] != nil
+    }
+
+    func requiredString(_ name: String) throws -> String {
+        guard let value = values[name] else { throw missing(name) }
+        guard case .string(let result) = value else { throw typeError(name, "a string") }
+        return result
+    }
+
+    func optionalString(_ name: String) throws -> String? {
+        guard let value = values[name] else { return nil }
+        guard case .string(let result) = value else { throw typeError(name, "a string") }
+        return result
+    }
+
+    func requiredNullableString(_ name: String) throws -> String? {
+        guard let value = values[name] else { throw missing(name) }
+        if case .null = value { return nil }
+        guard case .string(let result) = value else { throw typeError(name, "a string or null") }
+        return result
+    }
+
+    func requiredBool(_ name: String) throws -> Bool {
+        guard let value = values[name] else { throw missing(name) }
+        guard case .boolean(let result) = value else { throw typeError(name, "a boolean") }
+        return result
+    }
+
+    func optionalBool(_ name: String) throws -> Bool? {
+        guard let value = values[name] else { return nil }
+        guard case .boolean(let result) = value else { throw typeError(name, "a boolean") }
+        return result
+    }
+
+    func requiredInteger(
+        _ name: String,
+        as type: T.Type = T.self
+    ) throws -> T {
+        guard let result: T = try optionalInteger(name, as: type) else { throw missing(name) }
+        return result
+    }
+
+    func optionalInteger(
+        _ name: String,
+        as type: T.Type = T.self
+    ) throws -> T? {
+        guard let value = values[name] else { return nil }
+        let result: T?
+        if T.isSigned, case .integer(let raw) = value {
+            result = T(exactly: raw)
+        } else if !T.isSigned, case .unsignedInteger(let raw) = value {
+            result = T(exactly: raw)
+        } else {
+            result = nil
+        }
+        guard let result else {
+            let signedness = T.isSigned ? "signed" : "unsigned"
+            throw typeError(name, "a \(signedness) integer representable as \(T.self)")
+        }
+        return result
+    }
+
+    func requiredNullableInteger(
+        _ name: String,
+        as type: T.Type = T.self
+    ) throws -> T? {
+        guard let value = values[name] else { throw missing(name) }
+        if case .null = value { return nil }
+        return try requiredInteger(name, as: type)
+    }
+
+    func requiredInt(_ name: String) throws -> Int {
+        try requiredInteger(name)
+    }
+
+    func optionalInt(_ name: String) throws -> Int? {
+        try optionalInteger(name)
+    }
+
+    func requiredInt64(_ name: String) throws -> Int64 {
+        try requiredInteger(name)
+    }
+
+    func optionalInt64(_ name: String) throws -> Int64? {
+        try optionalInteger(name)
+    }
+
+    func requiredUInt(_ name: String) throws -> UInt {
+        try requiredInteger(name)
+    }
+
+    func optionalUInt(_ name: String) throws -> UInt? {
+        try optionalInteger(name)
+    }
+
+    func requiredUInt64(_ name: String) throws -> UInt64 {
+        try requiredInteger(name)
+    }
+
+    func optionalUInt64(_ name: String) throws -> UInt64? {
+        try optionalInteger(name)
+    }
+
+    func requiredArray(_ name: String) throws -> [GhostboxJSONValue] {
+        guard let value = values[name] else { throw missing(name) }
+        guard case .array(let result) = value else { throw typeError(name, "an array") }
+        return result
+    }
+
+    func optionalArray(_ name: String) throws -> [GhostboxJSONValue]? {
+        guard let value = values[name] else { return nil }
+        guard case .array(let result) = value else { throw typeError(name, "an array") }
+        return result
+    }
+
+    func requiredStringArray(_ name: String) throws -> [String] {
+        try strings(requiredArray(name), name: name)
+    }
+
+    func optionalStringArray(_ name: String) throws -> [String]? {
+        guard let values = try optionalArray(name) else { return nil }
+        return try strings(values, name: name)
+    }
+
+    func requiredObject(_ name: String) throws -> [String: GhostboxJSONValue] {
+        guard let value = values[name] else { throw missing(name) }
+        guard case .object(let result) = value else { throw typeError(name, "an object") }
+        return result
+    }
+
+    func optionalObject(_ name: String) throws -> [String: GhostboxJSONValue]? {
+        guard let value = values[name] else { return nil }
+        guard case .object(let result) = value else { throw typeError(name, "an object") }
+        return result
+    }
+
+    func optionalValue(_ name: String) -> GhostboxJSONValue? {
+        values[name]
+    }
+
+    func requiredReference(_ name: String, expectedKind: String) throws -> String {
+        try GhostboxReference.canonical(requiredString(name), expectedKind: expectedKind)
+    }
+
+    func optionalReference(_ name: String, expectedKind: String) throws -> String? {
+        guard let reference = try optionalString(name) else { return nil }
+        return try GhostboxReference.canonical(reference, expectedKind: expectedKind)
+    }
+
+    func requiredNullableReference(_ name: String, expectedKind: String) throws -> String? {
+        guard let reference = try requiredNullableString(name) else { return nil }
+        return try GhostboxReference.canonical(reference, expectedKind: expectedKind)
+    }
+
+    func requiredReferences(_ name: String, expectedKind: String) throws -> [String] {
+        try requiredStringArray(name).map {
+            try GhostboxReference.canonical($0, expectedKind: expectedKind)
+        }
+    }
+
+    func optionalReferences(_ name: String, expectedKind: String) throws -> [String]? {
+        guard let references = try optionalStringArray(name) else { return nil }
+        return try references.map {
+            try GhostboxReference.canonical($0, expectedKind: expectedKind)
+        }
+    }
+
+    private func strings(_ values: [GhostboxJSONValue], name: String) throws -> [String] {
+        try values.enumerated().map { index, value in
+            guard case .string(let result) = value else {
+                throw DirectDispatchError(
+                    .invalidArgument,
+                    "parameter '\(name)' element \(index) must be a string"
+                )
+            }
+            return result
+        }
+    }
+
+    private func missing(_ name: String) -> DirectDispatchError {
+        DirectDispatchError(.invalidArgument, "missing required parameter '\(name)'")
+    }
+
+    private func typeError(_ name: String, _ expected: String) -> DirectDispatchError {
+        DirectDispatchError(.invalidArgument, "parameter '\(name)' must be \(expected)")
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxPodCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxPodCommands.swift
new file mode 100644
index 0000000..f343fcb
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxPodCommands.swift
@@ -0,0 +1,498 @@
+import Containerization
+import ContainerizationOS
+import Foundation
+import GhostVMKit
+
+struct GhostboxPodVolumeCommands: GhostboxDomainHandler {
+    let resource = "podVolume"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "podVolume.create" else { throw ghostboxUnsupported(method) }
+        let decoded = try GhostboxParameters(parameters, allowed: ["podVolume", "name", "source", "format"])
+        let source = try ghostboxPodVolumeSource(decoded.requiredObject("source"))
+        let volume = LinuxPod.PodVolume(
+            name: try decoded.requiredString("name"),
+            source: source,
+            format: try decoded.requiredString("format")
+        )
+        let reference = try session.register(
+            kind: "pod-volume", name: decoded.requiredString("podVolume"), value: volume,
+            equivalent: { $0.name == $1.name && $0.format == $1.format }
+        )
+        return .reference(reference)
+    }
+}
+
+struct GhostboxPodConfigurationCommands: GhostboxDomainHandler {
+    let resource = "podConfig"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        if method.rawValue == "podConfig.create" {
+            let decoded = try GhostboxParameters(parameters, allowed: ["podConfig"])
+            let reference = try session.registerMutable(
+                kind: "pod-config", name: decoded.requiredString("podConfig"),
+                value: LinuxPod.Configuration(), equivalent: ghostboxPodConfigurationsEqual
+            )
+            return .reference(reference)
+        }
+        let valueName = ghostboxPodConfigValueName(method.rawValue)
+        let decoded = try GhostboxParameters(parameters, allowed: ["podConfig", valueName])
+        let reference = try decoded.requiredReference("podConfig", expectedKind: "pod-config")
+        switch method.rawValue {
+        case "podConfig.setCPUs":
+            let value = try decoded.requiredInt("cpus")
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.cpus = value }
+        case "podConfig.setMemory":
+            let value = try decoded.requiredUInt64("bytes")
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.memoryInBytes = value }
+        case "podConfig.setInterfaces":
+            let references = try decoded.requiredReferences("interface", expectedKind: "interface")
+            let values: [any Interface] = try references.map {
+                try session.value(for: $0, expectedKind: "interface", as: (any Interface).self)
+            }
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.interfaces = values }
+        case "podConfig.setVirtualization":
+            let value = try decoded.requiredBool("enabled")
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.virtualization = value }
+        case "podConfig.setBootLog":
+            let objectReference = try decoded.requiredNullableReference("bootLog", expectedKind: "boot-log")
+            let value: BootLog? = try objectReference.map { try session.value(for: $0, expectedKind: "boot-log") }
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.bootLog = value }
+        case "podConfig.setShareProcessNamespace":
+            let value = try decoded.requiredBool("enabled")
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.shareProcessNamespace = value }
+        case "podConfig.setHostname":
+            let value = try decoded.requiredNullableString("hostname")
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.hostname = value }
+        case "podConfig.setDNS":
+            let objectReference = try decoded.requiredNullableReference("dns", expectedKind: "dns")
+            let value: DNS? = try objectReference.map { try session.value(for: $0, expectedKind: "dns") }
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.dns = value }
+        case "podConfig.setHosts":
+            let objectReference = try decoded.requiredNullableReference("hosts", expectedKind: "hosts")
+            let value: Hosts? = try objectReference.map {
+                let record: GhostboxHostsRecord = try session.value(for: $0, expectedKind: "hosts")
+                return record.value
+            }
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.hosts = value }
+        case "podConfig.setVolumes":
+            let references = try decoded.requiredReferences("podVolume", expectedKind: "pod-volume")
+            let values: [LinuxPod.PodVolume] = try references.map { try session.value(for: $0, expectedKind: "pod-volume") }
+            try session.updateValue(for: reference, expectedKind: "pod-config", as: LinuxPod.Configuration.self) { $0.volumes = values }
+        default: throw ghostboxUnsupported(method)
+        }
+        return .void
+    }
+}
+
+struct GhostboxPodContainerConfigurationCommands: GhostboxDomainHandler {
+    let resource = "podContainerConfig"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        if method.rawValue == "podContainerConfig.create" {
+            let decoded = try GhostboxParameters(parameters, allowed: ["podContainerConfig"])
+            let reference = try session.registerMutable(
+                kind: "pod-container-config", name: decoded.requiredString("podContainerConfig"),
+                value: LinuxPod.ContainerConfiguration(), equivalent: ghostboxPodContainerConfigurationsEqual
+            )
+            return .reference(reference)
+        }
+        let valueName = ghostboxPodContainerConfigValueName(method.rawValue)
+        let decoded = try GhostboxParameters(parameters, allowed: ["podContainerConfig", valueName])
+        let reference = try decoded.requiredReference("podContainerConfig", expectedKind: "pod-container-config")
+        switch method.rawValue {
+        case "podContainerConfig.setProcess":
+            let processReference = try decoded.requiredReference("processConfig", expectedKind: "process-config")
+            let value = try ghostboxProcessConfiguration(processReference, session: session)
+            try update(reference, session: session) { $0.process = value }
+        case "podContainerConfig.setCPUs":
+            let value: Int? = try decoded.requiredNullableInteger("cpus")
+            try update(reference, session: session) { $0.cpus = value }
+        case "podContainerConfig.setMemory":
+            let value: UInt64? = try decoded.requiredNullableInteger("bytes")
+            try update(reference, session: session) { $0.memoryInBytes = value }
+        case "podContainerConfig.setHostname":
+            let value = try decoded.requiredNullableString("hostname")
+            try update(reference, session: session) { $0.hostname = value }
+        case "podContainerConfig.setSysctl":
+            let value = try ghostboxPodAssignments(decoded.requiredStringArray("keyValue"))
+            try update(reference, session: session) { $0.sysctl = value }
+        case "podContainerConfig.setMounts":
+            let references = try decoded.requiredReferences("mount", expectedKind: "mount")
+            let value: [Containerization.Mount] = try references.map { try session.value(for: $0, expectedKind: "mount") }
+            try update(reference, session: session) { $0.mounts = value }
+        case "podContainerConfig.setMaskedPaths":
+            let value = try decoded.requiredStringArray("path")
+            try update(reference, session: session) { $0.maskedPaths = value }
+        case "podContainerConfig.setReadonlyPaths":
+            let value = try decoded.requiredStringArray("path")
+            try update(reference, session: session) { $0.readonlyPaths = value }
+        case "podContainerConfig.setSockets":
+            let references = try decoded.requiredReferences("socket", expectedKind: "socket")
+            let value: [UnixSocketConfiguration] = try references.map { try session.value(for: $0, expectedKind: "socket") }
+            try update(reference, session: session) { $0.sockets = value }
+        case "podContainerConfig.setDNS":
+            let objectReference = try decoded.requiredNullableReference("dns", expectedKind: "dns")
+            let value: DNS? = try objectReference.map { try session.value(for: $0, expectedKind: "dns") }
+            try update(reference, session: session) { $0.dns = value }
+        case "podContainerConfig.setHosts":
+            let objectReference = try decoded.requiredNullableReference("hosts", expectedKind: "hosts")
+            let value: Hosts? = try objectReference.map {
+                let record: GhostboxHostsRecord = try session.value(for: $0, expectedKind: "hosts")
+                return record.value
+            }
+            try update(reference, session: session) { $0.hosts = value }
+        case "podContainerConfig.setUseInit":
+            let value = try decoded.requiredBool("enabled")
+            try update(reference, session: session) { $0.useInit = value }
+        default: throw ghostboxUnsupported(method)
+        }
+        return .void
+    }
+
+    private func update(
+        _ reference: String,
+        session: GhostboxSession,
+        _ body: (inout LinuxPod.ContainerConfiguration) throws -> Void
+    ) throws {
+        try session.updateValue(for: reference, expectedKind: "pod-container-config", body)
+    }
+}
+
+struct GhostboxPodCommands: GhostboxDomainHandler {
+    let resource = "pod"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        if method.rawValue == "pod.createDirect" {
+            return try create(parameters: parameters, session: session)
+        }
+        let decoded = try GhostboxParameters(parameters, allowed: ghostboxPodAllowedParameters(method.rawValue))
+        let podReference = try decoded.requiredReference("pod", expectedKind: "pod")
+        let record: GhostboxPodRecord = try session.value(for: podReference, expectedKind: "pod")
+        let pod = record.value
+        switch method.rawValue {
+        case "pod.id": return .string(pod.id)
+        case "pod.config": return .reference(record.configurationReference)
+        case "pod.cpus": return .integer(Int64(pod.cpus))
+        case "pod.memory": return .unsignedInteger(pod.memoryInBytes)
+        case "pod.interfaces":
+            let references = try pod.interfaces.enumerated().map { index, interface in
+                try session.register(
+                    kind: "interface", name: "\(ghostboxReferenceName(podReference))-\(index)",
+                    value: GhostboxInterfaceRecord(value: interface, provenance: nil),
+                    equivalent: ghostboxInterfaceRecordsEqual
+                )
+            }
+            return .references(references)
+        case "pod.addContainer":
+            let containerID = try decoded.requiredString("container")
+            let rootfsReference = try decoded.requiredReference("rootfs", expectedKind: "mount")
+            let rootfs: Containerization.Mount = try session.value(for: rootfsReference, expectedKind: "mount")
+            let configReference = try decoded.requiredReference("configuration", expectedKind: "pod-container-config")
+            let config: LinuxPod.ContainerConfiguration = try session.valueSnapshot(
+                for: configReference, expectedKind: "pod-container-config"
+            )
+            try await pod.addContainer(containerID, rootfs: rootfs) { $0 = config }
+            return .reference(try ghostboxPodContainerReference(podReference: podReference, containerID: containerID, session: session))
+        case "pod.create": try await pod.create(); return .void
+        case "pod.startContainer": try await pod.startContainer(try containerID(decoded, podReference: podReference, session: session)); return .void
+        case "pod.stopContainer": try await pod.stopContainer(try containerID(decoded, podReference: podReference, session: session)); return .void
+        case "pod.stop": try await pod.stop(); return .void
+        case "pod.killContainer":
+            try await pod.killContainer(
+                try containerID(decoded, podReference: podReference, session: session),
+                signal: Signal(decoded.requiredString("signal"))
+            )
+            return .void
+        case "pod.waitContainer":
+            return ghostboxExitStatusValue(try await pod.waitContainer(
+                try containerID(decoded, podReference: podReference, session: session),
+                timeoutInSeconds: decoded.optionalInt64("timeoutSeconds")
+            ))
+        case "pod.resizeContainer":
+            try await pod.resizeContainer(
+                try containerID(decoded, podReference: podReference, session: session),
+                to: Terminal.Size(
+                    width: decoded.requiredInteger("width", as: UInt16.self),
+                    height: decoded.requiredInteger("height", as: UInt16.self)
+                )
+            )
+            return .void
+        case "pod.execInContainer":
+            let id = try containerID(decoded, podReference: podReference, session: session)
+            let processID = try decoded.requiredString("process")
+            let configReference = try decoded.requiredReference("configuration", expectedKind: "process-config")
+            let config = try ghostboxProcessConfiguration(configReference, session: session)
+            let process = try await pod.execInContainer(id, processID: processID) { $0 = config }
+            return .reference(try ghostboxRegisterProcess(
+                process, name: "\(ghostboxReferenceName(podReference))-\(id)-\(processID)", session: session
+            ))
+        case "pod.listContainers":
+            let ids = await pod.listContainers()
+            return .references(try ids.map {
+                try ghostboxPodContainerReference(podReference: podReference, containerID: $0, session: session)
+            })
+        case "pod.statistics":
+            let containerReferences = try decoded.optionalReferences("container", expectedKind: "pod-container")
+            let ids = try containerReferences?.map {
+                let handle: GhostboxPodContainerHandle = try session.value(for: $0, expectedKind: "pod-container")
+                guard handle.podReference == podReference else {
+                    throw DirectDispatchError(.invalidArgument, "pod container belongs to another pod")
+                }
+                return handle.containerID
+            }
+            let values = try await pod.statistics(
+                containerIDs: ids,
+                categories: try ghostboxStatCategories(decoded.optionalStringArray("category"))
+            )
+            return .array(values.map(ghostboxStatisticsValue))
+        case "pod.dialVsock":
+            return .reference(try ghostboxRegisterFileHandle(
+                await pod.dialVsock(port: decoded.requiredInteger("port", as: UInt32.self)), session: session
+            ))
+        case "pod.filesystemOperation":
+            try await pod.filesystemOperation(
+                try containerID(decoded, podReference: podReference, session: session),
+                operation: try ghostboxFilesystemOperation(decoded.requiredString("operation")),
+                path: decoded.requiredString("path")
+            )
+            return .void
+        case "pod.closeContainerStdin":
+            try await pod.closeContainerStdin(try containerID(decoded, podReference: podReference, session: session))
+            return .void
+        case "pod.relayUnixSocket":
+            let socketReference = try decoded.requiredReference("socket", expectedKind: "socket")
+            let socket: UnixSocketConfiguration = try session.value(for: socketReference, expectedKind: "socket")
+            try await pod.relayUnixSocket(
+                try containerID(decoded, podReference: podReference, session: session), socket: socket
+            )
+            return .void
+        default: throw ghostboxUnsupported(method)
+        }
+    }
+
+    private func create(
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) throws -> GhostboxDirectValue {
+        let decoded = try GhostboxParameters(parameters, allowed: ["pod", "vmm", "configuration"])
+        let name = try decoded.requiredString("pod")
+        let vmmReference = try decoded.requiredReference("vmm", expectedKind: "vmm")
+        let vmm: GhostboxVMMRecord = try session.value(for: vmmReference, expectedKind: "vmm")
+        let sourceConfigReference = try decoded.requiredReference("configuration", expectedKind: "pod-config")
+        let config: LinuxPod.Configuration = try session.valueSnapshot(for: sourceConfigReference, expectedKind: "pod-config")
+        let snapshotReference = try session.register(
+            kind: "pod-config", name: "\(name)-snapshot", value: config,
+            equivalent: ghostboxPodConfigurationsEqual
+        )
+        let pod = try LinuxPod(name, vmm: vmm.value) { $0 = config }
+        let reference = try session.register(
+            kind: "pod", name: name,
+            value: GhostboxPodRecord(value: pod, configurationReference: snapshotReference),
+            equivalent: { $0.value === $1.value },
+            cleanupPriority: 80,
+            cleanup: { try? await $0.value.stop() }
+        )
+        return .reference(reference)
+    }
+
+    private func containerID(
+        _ decoded: GhostboxParameters,
+        podReference: String,
+        session: GhostboxSession
+    ) throws -> String {
+        let reference = try decoded.requiredReference("podContainer", expectedKind: "pod-container")
+        let handle: GhostboxPodContainerHandle = try session.value(for: reference, expectedKind: "pod-container")
+        guard handle.podReference == podReference else {
+            throw DirectDispatchError(.invalidArgument, "pod container belongs to another pod")
+        }
+        return handle.containerID
+    }
+}
+
+enum GhostboxPodCommandHandlers {
+    static let all: [any GhostboxDomainHandler] = [
+        GhostboxPodVolumeCommands(),
+        GhostboxPodConfigurationCommands(),
+        GhostboxPodContainerConfigurationCommands(),
+        GhostboxPodCommands(),
+    ]
+}
+
+struct GhostboxPodRecord: Sendable {
+    let value: LinuxPod
+    let configurationReference: String
+}
+
+struct GhostboxPodContainerHandle: Sendable, Equatable {
+    let podReference: String
+    let containerID: String
+}
+
+private func ghostboxPodContainerReference(
+    podReference: String,
+    containerID: String,
+    session: GhostboxSession
+) throws -> String {
+    let handle = GhostboxPodContainerHandle(podReference: podReference, containerID: containerID)
+    return try session.register(
+        kind: "pod-container",
+        name: "\(ghostboxReferenceName(podReference)).\(containerID)",
+        value: handle,
+        equivalent: ==
+    )
+}
+
+private func ghostboxPodVolumeSource(
+    _ object: [String: GhostboxJSONValue]
+) throws -> LinuxPod.PodVolume.Source {
+    guard case .string(let type)? = object["type"] else {
+        throw DirectDispatchError(.invalidArgument, "pod volume source requires a string 'type'")
+    }
+    switch type {
+    case "nbd":
+        guard case .string(let rawURL)? = object["url"], let url = URL(string: rawURL), url.scheme != nil else {
+            throw DirectDispatchError(.invalidArgument, "nbd pod volume source requires an absolute 'url'")
+        }
+        let timeout = try ghostboxPodDouble(object["timeout"], name: "timeout")
+        let readOnly = try ghostboxPodBool(object["readOnly"], name: "readOnly") ?? false
+        return .nbd(url: url, timeout: timeout, readOnly: readOnly)
+    case "disk-image":
+        guard case .string(let path)? = object["path"] else {
+            throw DirectDispatchError(.invalidArgument, "disk-image pod volume source requires 'path'")
+        }
+        return .diskImage(
+            path: ghostboxHostURL(path),
+            readOnly: try ghostboxPodBool(object["readOnly"], name: "readOnly") ?? false
+        )
+    case "tmpfs":
+        return .tmpfs(sizeBytes: try ghostboxPodUInt64(object["sizeBytes"], name: "sizeBytes"))
+    default:
+        throw DirectDispatchError(.invalidArgument, "unknown pod volume source type '\(type)'")
+    }
+}
+
+private func ghostboxPodConfigValueName(_ method: String) -> String {
+    switch method {
+    case "podConfig.setCPUs": return "cpus"
+    case "podConfig.setMemory": return "bytes"
+    case "podConfig.setInterfaces": return "interface"
+    case "podConfig.setVirtualization", "podConfig.setShareProcessNamespace": return "enabled"
+    case "podConfig.setBootLog": return "bootLog"
+    case "podConfig.setHostname": return "hostname"
+    case "podConfig.setDNS": return "dns"
+    case "podConfig.setHosts": return "hosts"
+    case "podConfig.setVolumes": return "podVolume"
+    default: return "value"
+    }
+}
+
+private func ghostboxPodContainerConfigValueName(_ method: String) -> String {
+    switch method {
+    case "podContainerConfig.setProcess": return "processConfig"
+    case "podContainerConfig.setCPUs": return "cpus"
+    case "podContainerConfig.setMemory": return "bytes"
+    case "podContainerConfig.setHostname": return "hostname"
+    case "podContainerConfig.setSysctl": return "keyValue"
+    case "podContainerConfig.setMounts": return "mount"
+    case "podContainerConfig.setMaskedPaths", "podContainerConfig.setReadonlyPaths": return "path"
+    case "podContainerConfig.setSockets": return "socket"
+    case "podContainerConfig.setDNS": return "dns"
+    case "podContainerConfig.setHosts": return "hosts"
+    case "podContainerConfig.setUseInit": return "enabled"
+    default: return "value"
+    }
+}
+
+private func ghostboxPodAllowedParameters(_ method: String) -> Set {
+    switch method {
+    case "pod.addContainer": return ["pod", "container", "rootfs", "configuration"]
+    case "pod.startContainer", "pod.stopContainer", "pod.closeContainerStdin": return ["pod", "podContainer"]
+    case "pod.killContainer": return ["pod", "podContainer", "signal"]
+    case "pod.waitContainer": return ["pod", "podContainer", "timeoutSeconds"]
+    case "pod.resizeContainer": return ["pod", "podContainer", "width", "height"]
+    case "pod.execInContainer": return ["pod", "podContainer", "process", "configuration"]
+    case "pod.statistics": return ["pod", "container", "category"]
+    case "pod.dialVsock": return ["pod", "port"]
+    case "pod.filesystemOperation": return ["pod", "podContainer", "operation", "path"]
+    case "pod.relayUnixSocket": return ["pod", "podContainer", "socket"]
+    default: return ["pod"]
+    }
+}
+
+private func ghostboxPodAssignments(_ values: [String]) throws -> [String: String] {
+    var result: [String: String] = [:]
+    for value in values {
+        guard let separator = value.firstIndex(of: "="), separator != value.startIndex else {
+            throw DirectDispatchError(.invalidArgument, "sysctl values must use KEY=VALUE")
+        }
+        let key = String(value[.. Bool? {
+    guard let value else { return nil }
+    guard case .boolean(let result) = value else {
+        throw DirectDispatchError(.invalidArgument, "pod volume source '\(name)' must be a boolean")
+    }
+    return result
+}
+
+private func ghostboxPodUInt64(_ value: GhostboxJSONValue?, name: String) throws -> UInt64? {
+    guard let value else { return nil }
+    switch value {
+    case .unsignedInteger(let result): return result
+    case .integer(let result) where result >= 0: return UInt64(result)
+    default: throw DirectDispatchError(.invalidArgument, "pod volume source '\(name)' must be an unsigned integer")
+    }
+}
+
+private func ghostboxPodDouble(_ value: GhostboxJSONValue?, name: String) throws -> Double? {
+    guard let integer = try ghostboxPodUInt64(value, name: name) else { return nil }
+    return Double(integer)
+}
+
+private func ghostboxPodConfigurationsEqual(_ lhs: LinuxPod.Configuration, _ rhs: LinuxPod.Configuration) -> Bool {
+    lhs.cpus == rhs.cpus
+        && lhs.memoryInBytes == rhs.memoryInBytes
+        && lhs.virtualization == rhs.virtualization
+        && lhs.shareProcessNamespace == rhs.shareProcessNamespace
+        && lhs.hostname == rhs.hostname
+        && lhs.interfaces.count == rhs.interfaces.count
+        && lhs.volumes.map(\.name) == rhs.volumes.map(\.name)
+}
+
+private func ghostboxPodContainerConfigurationsEqual(
+    _ lhs: LinuxPod.ContainerConfiguration,
+    _ rhs: LinuxPod.ContainerConfiguration
+) -> Bool {
+    ghostboxProcessConfigurationEqual(lhs.process, rhs.process)
+        && lhs.cpus == rhs.cpus
+        && lhs.memoryInBytes == rhs.memoryInBytes
+        && lhs.hostname == rhs.hostname
+        && lhs.sysctl == rhs.sysctl
+        && lhs.mounts.count == rhs.mounts.count
+        && lhs.maskedPaths == rhs.maskedPaths
+        && lhs.readonlyPaths == rhs.readonlyPaths
+        && lhs.sockets.count == rhs.sockets.count
+        && lhs.useInit == rhs.useInit
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSession.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSession.swift
new file mode 100644
index 0000000..f779ded
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSession.swift
@@ -0,0 +1,55 @@
+import Foundation
+
+extension GhostboxSession {
+    @discardableResult
+    func registerMutable(
+        kind: String,
+        name: String,
+        value: Value,
+        equivalent: @escaping @Sendable (Value, Value) -> Bool
+    ) throws -> String {
+        let slot = GhostboxMutableSlot(value)
+        return try register(kind: kind, name: name, value: slot) { lhs, rhs in
+            equivalent(lhs.get(), rhs.get())
+        }
+    }
+
+    func mutableValue(
+        for reference: String,
+        expectedKind: String,
+        as type: Value.Type = Value.self
+    ) throws -> GhostboxMutableSlot {
+        try value(for: reference, expectedKind: expectedKind, as: GhostboxMutableSlot.self)
+    }
+
+    func valueSnapshot(
+        for reference: String,
+        expectedKind: String,
+        as type: Value.Type = Value.self
+    ) throws -> Value {
+        try mutableValue(for: reference, expectedKind: expectedKind, as: type).get()
+    }
+
+    func writeBack(
+        _ value: Value,
+        for reference: String,
+        expectedKind: String
+    ) throws {
+        let slot: GhostboxMutableSlot = try mutableValue(
+            for: reference,
+            expectedKind: expectedKind
+        )
+        slot.set(value)
+    }
+
+    func updateValue(
+        for reference: String,
+        expectedKind: String,
+        as type: Value.Type = Value.self,
+        _ update: (inout Value) throws -> Void
+    ) throws {
+        let slot = try mutableValue(for: reference, expectedKind: expectedKind, as: type)
+        try slot.update(update)
+    }
+
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSharedNetwork.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSharedNetwork.swift
new file mode 100644
index 0000000..5ef944f
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSharedNetwork.swift
@@ -0,0 +1,133 @@
+import Containerization
+import ContainerizationError
+import ContainerizationExtras
+import GhostVMKit
+import Virtualization
+import vmnet
+
+let ghostboxSharedNetworkContextKey = "org.ghostvm.ghostbox.shared-network"
+
+final class GhostboxNetwork: Network, @unchecked Sendable {
+    private final class SharedBackend: @unchecked Sendable {
+        let subnet: CIDRv4
+        let reference: vmnet_network_ref
+        private let lock = NSLock()
+        private var allocations: [String: UInt32] = [:]
+
+        init(reference: vmnet_network_ref, subnet: CIDRv4) {
+            self.reference = reference
+            self.subnet = subnet
+        }
+
+        deinit {
+            SharedVmnetNetwork.releaseVmnetReference(reference)
+        }
+
+        func allocate(_ id: String, gateway: Bool, mtu: UInt32) throws -> Containerization.Interface {
+            let address = try lock.withLock { () -> UInt32 in
+                guard allocations[id] == nil else {
+                    throw ContainerizationError(.exists, message: "allocation with id \(id) already exists")
+                }
+                let network = subnet.lower.value
+                let span = subnet.upper.value - network
+                guard span > 3 else {
+                    throw ContainerizationError(.empty, message: "shared GhostVM network is exhausted")
+                }
+                let midpoint = network + (span / 2) + (span % 2)
+                let first = max(network + 3, midpoint)
+                let used = Set(allocations.values)
+                guard let address = (first.. Containerization.Interface? {
+        try createInterface(id, mtu: 1500, gateway: true)
+    }
+
+    func createInterface(_ id: String, mtu: UInt32) throws -> Containerization.Interface? {
+        try createInterface(id, mtu: mtu, gateway: true)
+    }
+
+    func createInterfaceWithoutGateway(_ id: String) throws -> Containerization.Interface? {
+        try createInterface(id, mtu: 1500, gateway: false)
+    }
+
+    func releaseInterface(_ id: String) throws {
+        try lock.withLock {
+            switch backend {
+            case .owned(var network):
+                try network.releaseInterface(id)
+                backend = .owned(network)
+            case .shared(let network):
+                network.release(id)
+            }
+        }
+    }
+
+    private func createInterface(_ id: String, mtu: UInt32, gateway: Bool) throws -> Containerization.Interface? {
+        try lock.withLock {
+            switch backend {
+            case .owned(var network):
+                let interface = gateway
+                    ? try network.createInterface(id, mtu: mtu)
+                    : try network.createInterfaceWithoutGateway(id)
+                backend = .owned(network)
+                return interface
+            case .shared(let network):
+                return try network.allocate(id, gateway: gateway, mtu: mtu)
+            }
+        }
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSupport.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSupport.swift
new file mode 100644
index 0000000..d767e2c
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxSupport.swift
@@ -0,0 +1,34 @@
+import Foundation
+import GhostVMKit
+
+protocol GhostboxDomainHandler: Sendable {
+    var resource: String { get }
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue
+}
+
+func ghostboxUnsupported(_ method: GhostboxDirectMethod) -> DirectDispatchError {
+    DirectDispatchError(.unsupported, "unsupported direct method '\(method.rawValue)'")
+}
+
+func ghostboxEncodedValue(_ value: Value) throws -> GhostboxDirectValue {
+    let data = try JSONEncoder().encode(value)
+    let json = try JSONDecoder().decode(GhostboxJSONValue.self, from: data)
+    return ghostboxDirectValue(json)
+}
+
+private func ghostboxDirectValue(_ value: GhostboxJSONValue) -> GhostboxDirectValue {
+    switch value {
+    case .null: return .null
+    case .boolean(let value): return .boolean(value)
+    case .string(let value): return .string(value)
+    case .integer(let value): return .integer(value)
+    case .unsignedInteger(let value): return .unsignedInteger(value)
+    case .array(let values): return .array(values.map(ghostboxDirectValue))
+    case .object(let values): return .object(values.mapValues(ghostboxDirectValue))
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVMCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVMCommands.swift
new file mode 100644
index 0000000..c929fa2
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVMCommands.swift
@@ -0,0 +1,298 @@
+import Containerization
+import Foundation
+import GhostVMKit
+
+struct GhostboxVMConfigurationCommands: GhostboxDomainHandler {
+    let resource = "vmConfig"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        guard method.rawValue == "vmConfig.create" else { throw ghostboxUnsupported(method) }
+        let decoded = try GhostboxParameters(
+            parameters,
+            allowed: ["vmConfig", "cpus", "memory", "interface", "mount", "bootLog", "nestedVirtualization"]
+        )
+        let interfaceReferences = try decoded.optionalReferences("interface", expectedKind: "interface") ?? []
+        let interfaces: [any Interface] = try interfaceReferences.map {
+            try session.value(for: $0, expectedKind: "interface", as: (any Interface).self)
+        }
+        let mountAssignments = try decoded.optionalStringArray("mount") ?? []
+        var mountsByID: [String: [Containerization.Mount]] = [:]
+        for assignment in mountAssignments {
+            guard let separator = assignment.firstIndex(of: "="), separator != assignment.startIndex else {
+                throw DirectDispatchError(.invalidArgument, "parameter 'mount' values must use workloadID=@mount/name")
+            }
+            let workloadID = String(assignment[.. GhostboxDirectValue {
+        guard method.rawValue == "standardVmConfig.create" else { throw ghostboxUnsupported(method) }
+        let decoded = try GhostboxParameters(parameters, allowed: ["standardVmConfig", "vmConfig"])
+        let configReference = try decoded.requiredReference("vmConfig", expectedKind: "vm-config")
+        let config: GhostboxVMConfigurationRecord = try session.value(for: configReference, expectedKind: "vm-config")
+        let record = GhostboxStandardVMConfigurationRecord(
+            value: StandardVMConfig(configuration: config.value),
+            configurationReference: configReference
+        )
+        let reference = try session.register(
+            kind: "standard-vm-config",
+            name: decoded.requiredString("standardVmConfig"),
+            value: record,
+            equivalent: { $0.configurationReference == $1.configurationReference }
+        )
+        return .reference(reference)
+    }
+}
+
+struct GhostboxVMMCommands: GhostboxDomainHandler {
+    let resource = "vmm"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        switch method.rawValue {
+        case "vmm.create":
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["vmm", "kernel", "initialFilesystem", "rosetta", "nestedVirtualization"]
+            )
+            let kernelReference = try decoded.requiredReference("kernel", expectedKind: "kernel")
+            let kernel: Kernel = try session.value(for: kernelReference, expectedKind: "kernel")
+            let filesystemReference = try decoded.requiredReference("initialFilesystem", expectedKind: "mount")
+            let filesystem: Containerization.Mount = try session.value(for: filesystemReference, expectedKind: "mount")
+            let rosetta = try decoded.optionalBool("rosetta") ?? false
+            let nestedVirtualization = try decoded.optionalBool("nestedVirtualization") ?? false
+            let record = GhostboxVMMRecord(
+                value: VZVirtualMachineManager(
+                    kernel: kernel,
+                    initialFilesystem: filesystem,
+                    rosetta: rosetta,
+                    nestedVirtualization: nestedVirtualization
+                ),
+                kernelReference: kernelReference,
+                initialFilesystemReference: filesystemReference,
+                rosetta: rosetta,
+                nestedVirtualization: nestedVirtualization
+            )
+            let reference = try session.register(
+                kind: "vmm",
+                name: decoded.requiredString("vmm"),
+                value: record,
+                equivalent: ghostboxVMMsEqual
+            )
+            return .reference(reference)
+
+        case "vmm.createInstance":
+            let decoded = try GhostboxParameters(parameters, allowed: ["vmm", "standardVmConfig"])
+            let vmmReference = try decoded.requiredReference("vmm", expectedKind: "vmm")
+            let vmm: GhostboxVMMRecord = try session.value(for: vmmReference, expectedKind: "vmm")
+            let configReference = try decoded.requiredReference("standardVmConfig", expectedKind: "standard-vm-config")
+            let config: GhostboxStandardVMConfigurationRecord = try session.value(
+                for: configReference,
+                expectedKind: "standard-vm-config"
+            )
+            let instance = try vmm.value.create(config: config.value)
+            let record = GhostboxVMInstanceRecord(
+                value: instance,
+                vmmReference: vmmReference,
+                configurationReference: configReference
+            )
+            let reference = try session.register(
+                kind: "vm-instance",
+                name: UUID().uuidString.lowercased(),
+                value: record,
+                equivalent: { $0.id == $1.id },
+                cleanupPriority: 70,
+                cleanup: { record in
+                    switch record.value.state {
+                    case .running, .starting, .stopping:
+                        try? await record.value.stop()
+                    case .unknown:
+                        try? await record.value.resume()
+                        try? await record.value.stop()
+                    case .stopped:
+                        break
+                    }
+                }
+            )
+            return .reference(reference)
+
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+struct GhostboxVMInstanceCommands: GhostboxDomainHandler {
+    let resource = "vmInstance"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        let allowed: Set = method.rawValue == "vmInstance.dial" ? ["vmInstance", "port"] : ["vmInstance"]
+        let decoded = try GhostboxParameters(parameters, allowed: allowed)
+        let reference = try decoded.requiredReference("vmInstance", expectedKind: "vm-instance")
+        let record: GhostboxVMInstanceRecord = try session.value(for: reference, expectedKind: "vm-instance")
+
+        switch method.rawValue {
+        case "vmInstance.state":
+            return .string(ghostboxVMState(record.value.state))
+        case "vmInstance.mounts":
+            return .object(record.value.mounts.mapValues { .array($0.map(ghostboxAttachedFilesystemValue)) })
+        case "vmInstance.virtiofsLayout":
+            switch record.value.virtiofsLayout {
+            case .unified: return .string("unified")
+            case .perTag: return .string("per-tag")
+            }
+        case "vmInstance.start":
+            try await record.value.start()
+            return .void
+        case "vmInstance.stop":
+            try await record.value.stop()
+            return .void
+        case "vmInstance.pause":
+            try await record.value.pause()
+            return .void
+        case "vmInstance.resume":
+            try await record.value.resume()
+            return .void
+        case "vmInstance.dial":
+            let handle = try await record.value.dial(decoded.requiredInteger("port", as: UInt32.self))
+            let handleReference = try session.register(
+                kind: "file-handle",
+                name: UUID().uuidString.lowercased(),
+                value: handle,
+                equivalent: { $0 === $1 },
+                cleanupPriority: 100,
+                cleanup: { try? $0.close() }
+            )
+            return .reference(handleReference)
+        default:
+            throw ghostboxUnsupported(method)
+        }
+    }
+}
+
+enum GhostboxVMCommandHandlers {
+    static let all: [any GhostboxDomainHandler] = [
+        GhostboxVMConfigurationCommands(),
+        GhostboxStandardVMConfigurationCommands(),
+        GhostboxVMMCommands(),
+        GhostboxVMInstanceCommands(),
+    ]
+}
+
+struct GhostboxVMConfigurationRecord: Sendable {
+    let value: VMConfiguration
+    let interfaceReferences: [String]
+    let mountAssignments: [String]
+    let bootLogReference: String?
+}
+
+struct GhostboxStandardVMConfigurationRecord: Sendable {
+    let value: StandardVMConfig
+    let configurationReference: String
+}
+
+struct GhostboxVMMRecord: Sendable {
+    let value: VZVirtualMachineManager
+    let kernelReference: String
+    let initialFilesystemReference: String
+    let rosetta: Bool
+    let nestedVirtualization: Bool
+}
+
+final class GhostboxVMInstanceRecord: Sendable {
+    let id = UUID()
+    let value: any VirtualMachineInstance
+    let vmmReference: String
+    let configurationReference: String
+
+    init(value: any VirtualMachineInstance, vmmReference: String, configurationReference: String) {
+        self.value = value
+        self.vmmReference = vmmReference
+        self.configurationReference = configurationReference
+    }
+}
+
+private func ghostboxVMConfigurationsEqual(
+    _ lhs: GhostboxVMConfigurationRecord,
+    _ rhs: GhostboxVMConfigurationRecord
+) -> Bool {
+    lhs.value.cpus == rhs.value.cpus
+        && lhs.value.memoryInBytes == rhs.value.memoryInBytes
+        && lhs.interfaceReferences == rhs.interfaceReferences
+        && lhs.mountAssignments == rhs.mountAssignments
+        && lhs.bootLogReference == rhs.bootLogReference
+        && lhs.value.nestedVirtualization == rhs.value.nestedVirtualization
+}
+
+private func ghostboxVMMsEqual(_ lhs: GhostboxVMMRecord, _ rhs: GhostboxVMMRecord) -> Bool {
+    lhs.kernelReference == rhs.kernelReference
+        && lhs.initialFilesystemReference == rhs.initialFilesystemReference
+        && lhs.rosetta == rhs.rosetta
+        && lhs.nestedVirtualization == rhs.nestedVirtualization
+}
+
+private func ghostboxVMState(_ state: VirtualMachineInstanceState) -> String {
+    switch state {
+    case .starting: return "starting"
+    case .running: return "running"
+    case .stopped: return "stopped"
+    case .stopping: return "stopping"
+    case .unknown: return "unknown"
+    }
+}
+
+private func ghostboxAttachedFilesystemValue(_ filesystem: AttachedFilesystem) -> GhostboxDirectValue {
+    .object([
+        "type": .string(filesystem.type),
+        "source": .string(filesystem.source),
+        "destination": .string(filesystem.destination),
+        "options": .strings(filesystem.options),
+    ])
+}
diff --git a/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift
new file mode 100644
index 0000000..c2ba72e
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift
@@ -0,0 +1,324 @@
+import Containerization
+import ContainerizationEXT4
+import Foundation
+import GhostVMKit
+import SystemPackage
+
+let ghostboxVolumeStoreContextKey = "ghostbox.volume-store"
+
+struct GhostboxVolumeMetadata: Codable, Equatable, Sendable {
+    let name: String
+    let format: String
+    let sizeInBytes: UInt64
+    let createdAt: Date
+}
+
+actor GhostboxVolumeStore {
+    static let defaultSize: UInt64 = 8 * 1024 * 1024 * 1024
+    static let minimumSize: UInt64 = 1024 * 1024
+    static let maximumSize: UInt64 = 1024 * 1024 * 1024 * 1024
+    static let volumeQuota = 128
+
+    private static let metadataFile = "entity.json"
+    private static let imageFile = "volume.img"
+
+    private let rootURL: URL
+    private var mountLeases: [String: String] = [:]
+
+    init(rootURL: URL) {
+        self.rootURL = rootURL.standardizedFileURL
+    }
+
+    func create(name: String, sizeInBytes: UInt64) throws -> GhostboxVolumeMetadata {
+        try validate(name: name)
+        guard (Self.minimumSize...Self.maximumSize).contains(sizeInBytes) else {
+            throw DirectDispatchError(
+                .invalidArgument,
+                "volume size must be between \(Self.minimumSize) and \(Self.maximumSize) bytes"
+            )
+        }
+
+        try ensureRoot()
+        let destination = volumeURL(name)
+        guard !FileManager.default.fileExists(atPath: destination.path) else {
+            throw DirectDispatchError(.alreadyExists, "volume '@volume/\(name)' already exists")
+        }
+        guard try volumeNames().count < Self.volumeQuota else {
+            throw DirectDispatchError(.resourceExhausted, "persistent volume limit of \(Self.volumeQuota) reached")
+        }
+
+        let temporary = rootURL.appendingPathComponent(".\(name).\(UUID().uuidString).tmp", isDirectory: true)
+        var committed = false
+        defer {
+            if !committed { try? FileManager.default.removeItem(at: temporary) }
+        }
+        try FileManager.default.createDirectory(
+            at: temporary,
+            withIntermediateDirectories: false,
+            attributes: [.posixPermissions: 0o700]
+        )
+
+        let imageURL = temporary.appendingPathComponent(Self.imageFile)
+        let formatter = try EXT4.Formatter(FilePath(imageURL.path), minDiskSize: sizeInBytes)
+        try formatter.close()
+        try FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: imageURL.path)
+
+        let metadata = GhostboxVolumeMetadata(
+            name: name,
+            format: "ext4",
+            sizeInBytes: sizeInBytes,
+            createdAt: Date()
+        )
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601
+        encoder.outputFormatting = [.sortedKeys]
+        let metadataURL = temporary.appendingPathComponent(Self.metadataFile)
+        try encoder.encode(metadata).write(to: metadataURL, options: .atomic)
+        try FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: metadataURL.path)
+
+        do {
+            try FileManager.default.moveItem(at: temporary, to: destination)
+            committed = true
+        } catch CocoaError.fileWriteFileExists {
+            throw DirectDispatchError(.alreadyExists, "volume '@volume/\(name)' already exists")
+        }
+        return metadata
+    }
+
+    func list() throws -> [GhostboxVolumeMetadata] {
+        try ensureRoot()
+        return try volumeNames().map(load).sorted { $0.name < $1.name }
+    }
+
+    func inspect(name: String) throws -> GhostboxVolumeMetadata {
+        try validate(name: name)
+        return try load(name: name)
+    }
+
+    func delete(name: String) throws {
+        try validate(name: name)
+        _ = try load(name: name)
+        if let mountReference = mountLeases[name] {
+            throw DirectDispatchError(
+                .failedPrecondition,
+                "volume '@volume/\(name)' is in use by '\(mountReference)'"
+            )
+        }
+        try FileManager.default.removeItem(at: volumeURL(name))
+    }
+
+    func makeMount(
+        volumeName: String,
+        mountReference: String,
+        destination: String,
+        readOnly: Bool
+    ) throws -> Containerization.Mount {
+        let metadata = try inspect(name: volumeName)
+        if let existing = mountLeases[volumeName], existing != mountReference {
+            throw DirectDispatchError(
+                .failedPrecondition,
+                "volume '@volume/\(volumeName)' is already reserved by '\(existing)'"
+            )
+        }
+        mountLeases[volumeName] = mountReference
+        return Containerization.Mount.block(
+            format: metadata.format,
+            source: imageURL(volumeName).path,
+            destination: destination,
+            options: readOnly ? ["ro"] : [],
+            runtimeOptions: [
+                "vzDiskImageCachingMode=cached",
+                "vzDiskImageSynchronizationMode=fsync",
+            ]
+        )
+    }
+
+    func releaseMount(_ mountReference: String) {
+        if let name = mountLeases.first(where: { $0.value == mountReference })?.key {
+            mountLeases.removeValue(forKey: name)
+        }
+    }
+
+    func redactedSource(for mountReference: String) -> String? {
+        mountLeases.first(where: { $0.value == mountReference }).map { "@volume/\($0.key)" }
+    }
+
+    private func validate(name: String) throws {
+        _ = try GhostboxReference.canonical(kind: "volume", name: name)
+        guard name.first?.isLetter == true || name.first?.isNumber == true else {
+            throw DirectDispatchError(.invalidArgument, "volume name must begin with a letter or digit")
+        }
+    }
+
+    private func ensureRoot() throws {
+        try FileManager.default.createDirectory(
+            at: rootURL,
+            withIntermediateDirectories: true,
+            attributes: [.posixPermissions: 0o700]
+        )
+        try FileManager.default.setAttributes([.posixPermissions: 0o700], ofItemAtPath: rootURL.path)
+    }
+
+    private func volumeNames() throws -> [String] {
+        let urls = try FileManager.default.contentsOfDirectory(
+            at: rootURL,
+            includingPropertiesForKeys: [.isDirectoryKey, .isSymbolicLinkKey],
+            options: [.skipsHiddenFiles]
+        )
+        return try urls.compactMap { url in
+            let values = try url.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey])
+            guard values.isDirectory == true, values.isSymbolicLink != true else { return nil }
+            let name = url.lastPathComponent
+            guard (try? validate(name: name)) != nil else { return nil }
+            return name
+        }
+    }
+
+    private func load(name: String) throws -> GhostboxVolumeMetadata {
+        let directory = volumeURL(name)
+        do {
+            let values = try directory.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey])
+            guard values.isDirectory == true, values.isSymbolicLink != true else {
+                throw DirectDispatchError(.notFound, "volume '@volume/\(name)' was not found")
+            }
+            let decoder = JSONDecoder()
+            decoder.dateDecodingStrategy = .iso8601
+            let metadata = try decoder.decode(
+                GhostboxVolumeMetadata.self,
+                from: Data(contentsOf: directory.appendingPathComponent(Self.metadataFile))
+            )
+            guard metadata.name == name, metadata.format == "ext4" else {
+                throw DirectDispatchError(.failedPrecondition, "volume '@volume/\(name)' has invalid metadata")
+            }
+            let image = imageURL(name)
+            let imageValues = try image.resourceValues(forKeys: [.isRegularFileKey, .isSymbolicLinkKey])
+            guard imageValues.isRegularFile == true, imageValues.isSymbolicLink != true else {
+                throw DirectDispatchError(.failedPrecondition, "volume '@volume/\(name)' has no valid backing image")
+            }
+            return metadata
+        } catch let error as DirectDispatchError {
+            throw error
+        } catch let error as CocoaError where error.code == .fileNoSuchFile {
+            throw DirectDispatchError(.notFound, "volume '@volume/\(name)' was not found")
+        } catch {
+            throw DirectDispatchError(.failedPrecondition, "volume '@volume/\(name)' could not be read: \(error.localizedDescription)")
+        }
+    }
+
+    private func volumeURL(_ name: String) -> URL {
+        rootURL.appendingPathComponent(name, isDirectory: true)
+    }
+
+    private func imageURL(_ name: String) -> URL {
+        volumeURL(name).appendingPathComponent(Self.imageFile)
+    }
+}
+
+struct GhostboxVolumeCommands: GhostboxDomainHandler {
+    let resource = "volume"
+
+    func handle(
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue],
+        session: GhostboxSession
+    ) async throws -> GhostboxDirectValue {
+        let store = try ghostboxVolumeStore(session)
+        switch method.rawValue {
+        case GhostboxDirectMethod.volumeCreate.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["volume", "size"])
+            let name = try decoded.requiredString("volume")
+            let size = try decoded.optionalUInt64("size") ?? GhostboxVolumeStore.defaultSize
+            _ = try await store.create(name: name, sizeInBytes: size)
+            return .reference(try GhostboxReference.canonical(kind: "volume", name: name))
+
+        case GhostboxDirectMethod.volumeList.rawValue:
+            _ = try GhostboxParameters(parameters, allowed: [])
+            let values = try await store.list()
+            return .references(try values.map { try GhostboxReference.canonical(kind: "volume", name: $0.name) })
+
+        case GhostboxDirectMethod.volumeInspect.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["volume"])
+            let name = try volumeName(decoded)
+            return metadataValue(try await store.inspect(name: name))
+
+        case GhostboxDirectMethod.volumeMount.rawValue:
+            let decoded = try GhostboxParameters(
+                parameters,
+                allowed: ["volume", "mount", "destination", "readOnly"]
+            )
+            let volumeName = try volumeName(decoded)
+            let mountName = try decoded.requiredString("mount")
+            let mountReference = try GhostboxReference.canonical(kind: "mount", name: mountName)
+            let destination = try decoded.requiredString("destination")
+            guard ghostboxIsValidVolumeDestination(destination) else {
+                throw DirectDispatchError(
+                    .invalidArgument,
+                    "volume destination must be an absolute non-root path without dot components"
+                )
+            }
+            let mount = try await store.makeMount(
+                volumeName: volumeName,
+                mountReference: mountReference,
+                destination: destination,
+                readOnly: try decoded.optionalBool("readOnly") ?? false
+            )
+            do {
+                let reference = try session.register(
+                    kind: "mount",
+                    name: mountName,
+                    value: mount,
+                    equivalent: ghostboxVolumeMountsEqual,
+                    cleanup: { _ in await store.releaseMount(mountReference) }
+                )
+                return .reference(reference)
+            } catch {
+                await store.releaseMount(mountReference)
+                throw error
+            }
+
+        case GhostboxDirectMethod.volumeDelete.rawValue:
+            let decoded = try GhostboxParameters(parameters, allowed: ["volume"])
+            try await store.delete(name: volumeName(decoded))
+            return .void
+
+        default:
+            throw DirectDispatchError(.unsupported, "unsupported volume method '\(method.rawValue)'")
+        }
+    }
+
+    private func volumeName(_ decoded: GhostboxParameters) throws -> String {
+        let reference = try decoded.requiredReference("volume", expectedKind: "volume")
+        return String(reference.dropFirst("@volume/".count))
+    }
+
+    private func metadataValue(_ metadata: GhostboxVolumeMetadata) -> GhostboxDirectValue {
+        .object([
+            "name": .string(metadata.name),
+            "format": .string(metadata.format),
+            "sizeInBytes": .unsignedInteger(metadata.sizeInBytes),
+            "createdAt": .string(ISO8601DateFormatter().string(from: metadata.createdAt)),
+        ])
+    }
+}
+
+func ghostboxVolumeStore(_ session: GhostboxSession) throws -> GhostboxVolumeStore {
+    guard let store = session.contextValue(ghostboxVolumeStoreContextKey, as: GhostboxVolumeStore.self) else {
+        throw DirectDispatchError(.unavailable, "persistent volume storage is unavailable")
+    }
+    return store
+}
+
+private func ghostboxIsValidVolumeDestination(_ path: String) -> Bool {
+    guard path.hasPrefix("/"), path != "/", !path.contains("\0") else { return false }
+    return path.split(separator: "/", omittingEmptySubsequences: false).dropFirst().allSatisfy {
+        !$0.isEmpty && $0 != "." && $0 != ".."
+    }
+}
+
+private func ghostboxVolumeMountsEqual(_ lhs: Containerization.Mount, _ rhs: Containerization.Mount) -> Bool {
+    lhs.type == rhs.type
+        && lhs.source == rhs.source
+        && lhs.destination == rhs.destination
+        && lhs.options == rhs.options
+        && String(describing: lhs.runtimeOptions) == String(describing: rhs.runtimeOptions)
+}
diff --git a/macOS/GhostVMContainerRuntime/GhostboxAttachmentReadiness.swift b/macOS/GhostVMContainerRuntime/GhostboxAttachmentReadiness.swift
new file mode 100644
index 0000000..2c7669b
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/GhostboxAttachmentReadiness.swift
@@ -0,0 +1,54 @@
+import Foundation
+
+final class GhostboxAttachmentReadiness: @unchecked Sendable {
+    private let lock = NSLock()
+    private var ready = false
+    private var closed = false
+    private var waiters: [CheckedContinuation] = []
+
+    func wait() async throws {
+        try await withCheckedThrowingContinuation { continuation in
+            let result = lock.withLock { () -> Bool? in
+                if ready { return true }
+                if closed { return false }
+                waiters.append(continuation)
+                return nil
+            }
+            if result == true {
+                continuation.resume()
+            } else if result == false {
+                continuation.resume(throwing: DirectDispatchError(
+                    .failedPrecondition,
+                    "terminal proxy was closed before attachment"
+                ))
+            }
+        }
+    }
+
+    func markReady() {
+        let continuations = lock.withLock {
+            guard !ready, !closed else { return [CheckedContinuation]() }
+            ready = true
+            let continuations = waiters
+            waiters.removeAll()
+            return continuations
+        }
+        continuations.forEach { $0.resume() }
+    }
+
+    func close() {
+        let continuations = lock.withLock {
+            guard !closed else { return [CheckedContinuation]() }
+            closed = true
+            let continuations = waiters
+            waiters.removeAll()
+            return continuations
+        }
+        for continuation in continuations {
+            continuation.resume(throwing: DirectDispatchError(
+                .failedPrecondition,
+                "terminal proxy was closed before attachment"
+            ))
+        }
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/GhostboxCoreArguments.swift b/macOS/GhostVMContainerRuntime/GhostboxCoreArguments.swift
new file mode 100644
index 0000000..2cb2a42
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/GhostboxCoreArguments.swift
@@ -0,0 +1,150 @@
+import Foundation
+import GhostVMKit
+
+struct DirectDispatchError: Error, LocalizedError {
+    let code: ContainerRuntimeErrorCode
+    let message: String
+
+    init(_ code: ContainerRuntimeErrorCode, _ message: String) {
+        self.code = code
+        self.message = message
+    }
+
+    var errorDescription: String? { message }
+}
+
+enum GhostboxResourceOverheadPolicy {
+    // The bundled Linux environment reserves this much RAM before reporting MemTotal.
+    static let guestKernelMemoryBytes: UInt64 = 28_808 * 1024
+
+    static func cpu(requested: Int?, explicit: Int?) -> Int? {
+        explicit ?? requested.map { _ in 0 }
+    }
+
+    static func memory(requested: UInt64?, explicit: UInt64?) -> UInt64? {
+        explicit ?? requested.map { _ in guestKernelMemoryBytes }
+    }
+}
+
+struct GhostboxCommandArguments: Sendable {
+    let positionals: [String]
+    private let options: [String: [String?]]
+
+    init(_ arguments: [String]) throws {
+        var positionals: [String] = []
+        var options: [String: [String?]] = [:]
+        var index = 0
+        var optionsEnded = false
+
+        while index < arguments.count {
+            let argument = arguments[index]
+            if !optionsEnded, argument == "--" {
+                optionsEnded = true
+                index += 1
+                continue
+            }
+            guard !optionsEnded, argument.hasPrefix("--"), argument.count > 2 else {
+                positionals.append(argument)
+                index += 1
+                continue
+            }
+
+            if let equals = argument.firstIndex(of: "=") {
+                let name = String(argument[.. 2 else {
+                    throw DirectDispatchError(.invalidArgument, "invalid option '\(argument)'")
+                }
+                options[name, default: []].append(String(argument[argument.index(after: equals)...]))
+                index += 1
+                continue
+            }
+
+            if index + 1 < arguments.count, !arguments[index + 1].hasPrefix("--") {
+                options[argument, default: []].append(arguments[index + 1])
+                index += 2
+            } else {
+                options[argument, default: []].append(nil)
+                index += 1
+            }
+        }
+
+        self.positionals = positionals
+        self.options = options
+    }
+
+    func contains(_ name: String) -> Bool {
+        options[name] != nil
+    }
+
+    func rejectOptions(except allowed: Set = []) throws {
+        if let unknown = options.keys.first(where: { !allowed.contains($0) }) {
+            throw DirectDispatchError(.invalidArgument, "unknown option '\(unknown)'")
+        }
+    }
+
+    func values(_ name: String) throws -> [String] {
+        guard let values = options[name] else { return [] }
+        return try values.map { value in
+            guard let value else {
+                throw DirectDispatchError(.invalidArgument, "option \(name) requires a value")
+            }
+            return value
+        }
+    }
+
+    func string(_ name: String) throws -> String? {
+        guard let values = options[name] else { return nil }
+        guard values.count == 1 else {
+            throw DirectDispatchError(.invalidArgument, "option \(name) may be specified once")
+        }
+        guard let value = values[0] else {
+            throw DirectDispatchError(.invalidArgument, "option \(name) requires a value")
+        }
+        return value
+    }
+
+    func boolean(_ name: String, default defaultValue: Bool = false) throws -> Bool {
+        guard let values = options[name] else { return defaultValue }
+        guard values.count == 1 else {
+            throw DirectDispatchError(.invalidArgument, "option \(name) may be specified once")
+        }
+        guard let value = values[0] else { return true }
+        switch value.lowercased() {
+        case "true", "1", "yes": return true
+        case "false", "0", "no": return false
+        default: throw DirectDispatchError(.invalidArgument, "option \(name) requires a boolean value")
+        }
+    }
+
+    func integer(_ name: String) throws -> Int64? {
+        guard let value = try string(name) else { return nil }
+        guard let result = Int64(value) else {
+            throw DirectDispatchError(.invalidArgument, "option \(name) requires a signed integer")
+        }
+        return result
+    }
+
+    func unsignedInteger(_ name: String) throws -> UInt64? {
+        guard let value = try string(name) else { return nil }
+        guard let result = UInt64(value) else {
+            throw DirectDispatchError(.invalidArgument, "option \(name) requires an unsigned integer")
+        }
+        return result
+    }
+
+    func jsonString(_ name: String) throws -> String? {
+        guard let value = try string(name) else { return nil }
+        do {
+            return try JSONDecoder().decode(String.self, from: Data(value.utf8))
+        } catch {
+            throw DirectDispatchError(.invalidArgument, "option \(name) requires a JSON string")
+        }
+    }
+
+    func reference(at index: Int, expectedKind: String) throws -> String {
+        guard positionals.indices.contains(index) else {
+            throw DirectDispatchError(.invalidArgument, "missing @\(expectedKind)/NAME reference")
+        }
+        return try GhostboxReference.canonical(positionals[index], expectedKind: expectedKind)
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/GhostboxCoreSession.swift b/macOS/GhostVMContainerRuntime/GhostboxCoreSession.swift
new file mode 100644
index 0000000..ad005ba
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/GhostboxCoreSession.swift
@@ -0,0 +1,307 @@
+import Foundation
+import GhostVMKit
+
+enum GhostboxReference {
+    static func canonical(kind: String, name: String) throws -> String {
+        guard isComponent(kind), isComponent(name) else {
+            throw DirectDispatchError(.invalidArgument, "object kind and name may contain only letters, digits, '.', '_', or '-'")
+        }
+        return "@\(kind)/\(name)"
+    }
+
+    static func canonical(_ reference: String, expectedKind: String) throws -> String {
+        guard reference.first == "@",
+              let slash = reference.firstIndex(of: "/"),
+              reference[reference.index(after: slash)...].firstIndex(of: "/") == nil else {
+            throw DirectDispatchError(.invalidArgument, "invalid @\(expectedKind)/NAME reference")
+        }
+        let kind = String(reference[reference.index(after: reference.startIndex).. Bool {
+        !value.isEmpty && value.utf8.count <= 128 && value.utf8.allSatisfy {
+            (48...57).contains($0) || (65...90).contains($0) || (97...122).contains($0) || [45, 46, 95].contains($0)
+        }
+    }
+}
+
+final class GhostboxMutableSlot: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value: Value
+
+    init(_ value: Value) {
+        self.value = value
+    }
+
+    func get() -> Value {
+        lock.withLock { value }
+    }
+
+    func set(_ value: Value) {
+        lock.withLock { self.value = value }
+    }
+
+    func update(_ body: (inout Value) throws -> Void) rethrows {
+        try lock.withLock { try body(&value) }
+    }
+}
+
+final class GhostboxSession: @unchecked Sendable {
+    static let objectQuota = 256
+
+    private struct Entry {
+        let value: Any
+        let isEquivalent: (Any) -> Bool
+        let cleanupPriority: Int
+        let cancel: @Sendable () -> Void
+        let cleanup: @Sendable () async -> Void
+    }
+
+    private let lock = NSLock()
+    private let context: [String: Any]
+    private var entries: [String: Entry] = [:]
+    private var activeInvocations = 0
+    private var closing = false
+    private var idleWaiters: [CheckedContinuation] = []
+
+    init(context: [String: Any] = [:]) {
+        self.context = context
+    }
+
+    var count: Int {
+        lock.withLock { entries.count }
+    }
+
+    func contextValue(_ key: String, as type: Value.Type = Value.self) -> Value? {
+        context[key] as? Value
+    }
+
+    @discardableResult
+    func register(
+        kind: String,
+        name: String,
+        value: Value,
+        equivalent: @escaping @Sendable (Value, Value) -> Bool,
+        cleanupPriority: Int = 0,
+        cancel: @escaping @Sendable (Value) -> Void = { _ in },
+        cleanup: @escaping @Sendable (Value) async -> Void = { _ in }
+    ) throws -> String {
+        let reference = try GhostboxReference.canonical(kind: kind, name: name)
+        return try lock.withLock {
+            guard !closing || activeInvocations > 0 else {
+                throw DirectDispatchError(.unavailable, "direct session is closing")
+            }
+            if let existing = entries[reference] {
+                guard existing.isEquivalent(value) else {
+                    throw DirectDispatchError(.alreadyExists, "object '\(reference)' already exists")
+                }
+                return reference
+            }
+            guard entries.count < Self.objectQuota else {
+                throw DirectDispatchError(.resourceExhausted, "direct object limit of \(Self.objectQuota) reached")
+            }
+            entries[reference] = Entry(
+                value: value,
+                isEquivalent: { candidate in
+                    guard let candidate = candidate as? Value else { return false }
+                    return equivalent(value, candidate)
+                },
+                cleanupPriority: cleanupPriority,
+                cancel: { cancel(value) },
+                cleanup: { await cleanup(value) }
+            )
+            return reference
+        }
+    }
+
+    @discardableResult
+    func registerNew(
+        kind: String,
+        name: String,
+        makeValue: () throws -> Value,
+        equivalent: @escaping @Sendable (Value, Value) -> Bool,
+        cleanupPriority: Int = 0,
+        cancel: @escaping @Sendable (Value) -> Void = { _ in },
+        cleanup: @escaping @Sendable (Value) async -> Void = { _ in }
+    ) throws -> String {
+        let reference = try GhostboxReference.canonical(kind: kind, name: name)
+        return try lock.withLock {
+            guard !closing || activeInvocations > 0 else {
+                throw DirectDispatchError(.unavailable, "direct session is closing")
+            }
+            guard entries[reference] == nil else {
+                throw DirectDispatchError(.alreadyExists, "object '\(reference)' already exists")
+            }
+            guard entries.count < Self.objectQuota else {
+                throw DirectDispatchError(.resourceExhausted, "direct object limit of \(Self.objectQuota) reached")
+            }
+            let value = try makeValue()
+            entries[reference] = Entry(
+                value: value,
+                isEquivalent: { candidate in
+                    guard let candidate = candidate as? Value else { return false }
+                    return equivalent(value, candidate)
+                },
+                cleanupPriority: cleanupPriority,
+                cancel: { cancel(value) },
+                cleanup: { await cleanup(value) }
+            )
+            return reference
+        }
+    }
+
+    func registerAliases(
+        _ aliases: [(kind: String, name: String)],
+        value: Value,
+        equivalent: @escaping @Sendable (Value, Value) -> Bool
+    ) throws -> [String] {
+        let references = try aliases.map { try GhostboxReference.canonical(kind: $0.kind, name: $0.name) }
+        return try lock.withLock {
+            guard !closing || activeInvocations > 0 else {
+                throw DirectDispatchError(.unavailable, "direct session is closing")
+            }
+            for reference in references {
+                if let existing = entries[reference], !existing.isEquivalent(value) {
+                    throw DirectDispatchError(.alreadyExists, "object '\(reference)' already exists")
+                }
+            }
+            let newCount = references.filter { entries[$0] == nil }.count
+            guard entries.count + newCount <= Self.objectQuota else {
+                throw DirectDispatchError(.resourceExhausted, "direct object limit of \(Self.objectQuota) reached")
+            }
+            for reference in references where entries[reference] == nil {
+                entries[reference] = Entry(
+                    value: value,
+                    isEquivalent: { candidate in
+                        guard let candidate = candidate as? Value else { return false }
+                        return equivalent(value, candidate)
+                    },
+                    cleanupPriority: 0,
+                    cancel: {},
+                    cleanup: {}
+                )
+            }
+            return references
+        }
+    }
+
+    func value(
+        for reference: String,
+        expectedKind: String,
+        as type: Value.Type = Value.self
+    ) throws -> Value {
+        let canonical = try GhostboxReference.canonical(reference, expectedKind: expectedKind)
+        let result: (found: Bool, value: Value?) = lock.withLock {
+            guard let entry = entries[canonical] else { return (false, nil) }
+            return (true, entry.value as? Value)
+        }
+        guard result.found else {
+            throw DirectDispatchError(.notFound, "object '\(canonical)' was not found")
+        }
+        guard let value = result.value else {
+            throw DirectDispatchError(.failedPrecondition, "object '\(canonical)' has an incompatible stored representation")
+        }
+        return value
+    }
+
+    func valueSnapshots(
+        ofKind kind: String,
+        as type: Value.Type = Value.self
+    ) throws -> [(reference: String, value: Value)] {
+        let prefix = String(try GhostboxReference.canonical(kind: kind, name: "snapshot").dropLast("snapshot".count))
+        return try lock.withLock {
+            try entries.compactMap { reference, entry in
+                guard reference.hasPrefix(prefix) else { return nil }
+                guard let value = entry.value as? Value else {
+                    throw DirectDispatchError(
+                        .failedPrecondition,
+                        "object '\(reference)' has an incompatible stored representation"
+                    )
+                }
+                return (reference: reference, value: value)
+            }.sorted { $0.reference < $1.reference }
+        }
+    }
+
+    @discardableResult
+    func unregister(
+        _ reference: String,
+        expectedKind: String,
+        matching value: Value
+    ) throws -> Bool {
+        let canonical = try GhostboxReference.canonical(reference, expectedKind: expectedKind)
+        return lock.withLock {
+            guard let entry = entries[canonical], entry.isEquivalent(value) else { return false }
+            entries.removeValue(forKey: canonical)
+            return true
+        }
+    }
+
+    @discardableResult
+    func unregisterAndCleanup(
+        _ reference: String,
+        expectedKind: String,
+        matching value: Value
+    ) async throws -> Bool {
+        let canonical = try GhostboxReference.canonical(reference, expectedKind: expectedKind)
+        let cleanup: (@Sendable () async -> Void)? = lock.withLock {
+            guard let entry = entries[canonical], entry.isEquivalent(value) else { return nil }
+            entries.removeValue(forKey: canonical)
+            return entry.cleanup
+        }
+        guard let cleanup else { return false }
+        await cleanup()
+        return true
+    }
+
+    func beginInvocation() throws {
+        try lock.withLock {
+            guard !closing else {
+                throw DirectDispatchError(.unavailable, "direct session is closing")
+            }
+            activeInvocations += 1
+        }
+    }
+
+    func endInvocation() {
+        let waiters: [CheckedContinuation] = lock.withLock {
+            precondition(activeInvocations > 0)
+            activeInvocations -= 1
+            guard closing, activeInvocations == 0 else { return [] }
+            defer { idleWaiters.removeAll() }
+            return idleWaiters
+        }
+        for waiter in waiters { waiter.resume() }
+    }
+
+    func close() async {
+        let cancellations = lock.withLock {
+            closing = true
+            return entries.values.map(\.cancel)
+        }
+        for cancel in cancellations { cancel() }
+
+        await withCheckedContinuation { continuation in
+            let resumeImmediately = lock.withLock {
+                if activeInvocations == 0 { return true }
+                idleWaiters.append(continuation)
+                return false
+            }
+            if resumeImmediately { continuation.resume() }
+        }
+
+        let cleanups = lock.withLock {
+            let values = entries.values.sorted { $0.cleanupPriority > $1.cleanupPriority }.map(\.cleanup)
+            entries.removeAll()
+            return values
+        }
+        for cleanup in cleanups {
+            await cleanup()
+        }
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/Info.plist b/macOS/GhostVMContainerRuntime/Info.plist
new file mode 100644
index 0000000..db9ed08
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/Info.plist
@@ -0,0 +1,27 @@
+
+
+
+
+	CFBundleDevelopmentRegion
+	en
+	CFBundleExecutable
+	$(EXECUTABLE_NAME)
+	CFBundleIdentifier
+	$(PRODUCT_BUNDLE_IDENTIFIER)
+	CFBundleInfoDictionaryVersion
+	6.0
+	CFBundleName
+	$(PRODUCT_NAME)
+	CFBundlePackageType
+	XPC!
+	LSMinimumSystemVersion
+	$(MACOSX_DEPLOYMENT_TARGET)
+	XPCService
+	
+		RunLoopType
+		dispatch_main
+		ServiceType
+		Application
+	
+
+
diff --git a/macOS/GhostVMContainerRuntime/RuntimeMain.swift b/macOS/GhostVMContainerRuntime/RuntimeMain.swift
new file mode 100644
index 0000000..3601eba
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/RuntimeMain.swift
@@ -0,0 +1,562 @@
+import Containerization
+import ContainerizationError
+import ContainerizationExtras
+import ContainerizationOCI
+import ContainerizationOS
+import Foundation
+import GhostVMKit
+import XPC
+import vmnet
+
+// The shared protocol constants live as nested types on ContainerRuntimeXPCProtocol;
+// pull them into file-local aliases (shadowing Foundation.Operation) for readability.
+private typealias Key = ContainerRuntimeXPCProtocol.Key
+private typealias Operation = ContainerRuntimeXPCProtocol.Operation
+
+final class FileWriter: Writer, @unchecked Sendable {
+    private let handle: FileHandle
+
+    init(_ handle: FileHandle) {
+        self.handle = handle
+    }
+
+    func write(_ data: Data) throws {
+        try handle.write(contentsOf: data)
+    }
+
+    func close() throws {}
+}
+
+/// Hosts all container VMs for the containing GhostVMHelper as an application-scoped
+/// XPC service. Tracks backend operations and direct object sessions.
+private final class RuntimeBroker: @unchecked Sendable {
+    private let lock = NSLock()
+    private var builds: [String: BuildContext] = [:]
+    private var connectionRuns: [ObjectIdentifier: Set] = [:]
+    private var directSessions: [ObjectIdentifier: GhostboxSession] = [:]
+    private let directDispatcher = GhostboxDispatcher.standard
+
+    func handle(connection: xpc_connection_t, request: xpc_object_t) {
+        let version = xpc_dictionary_get_uint64(request, Key.version)
+        guard let operation = Self.string(request, Key.operation) else {
+            sendReply(connection: connection, request: request, error: "missing operation")
+            return
+        }
+        guard version == ContainerRuntimeXPCProtocol.version else {
+            sendReply(connection: connection, request: request, error: "unsupported protocol version \(version)")
+            return
+        }
+
+        switch operation {
+        case Operation.ping:
+            sendReply(connection: connection, request: request, ok: true)
+        case Operation.build:
+            handleBuild(connection: connection, request: request)
+        case Operation.cancel:
+            handleCancel(connection: connection, request: request)
+        case Operation.invoke:
+            handleInvoke(connection: connection, request: request)
+        case Operation.attach:
+            handleAttach(connection: connection, request: request)
+        case Operation.shutdown:
+            handleShutdown(connection: connection, request: request)
+        default:
+            sendReply(connection: connection, request: request, error: "unsupported operation '\(operation)'")
+        }
+    }
+
+    /// Connection invalidated (client gone). Cancel every operation owned by it.
+    func disconnect(connection: xpc_connection_t) {
+        let count = cancelAll(for: connection)
+        clearDirectSession(for: connection)
+        if count > 0 {
+            log("runtime[\(getpid())]: connection invalidated, cancelling \(count) operation(s)")
+        }
+    }
+
+    private func remove(_ context: BuildContext) {
+        let identifier = context.runIdentifier
+        let connectionID = ObjectIdentifier(context.connection)
+        lock.lock()
+        if builds[identifier] === context { builds.removeValue(forKey: identifier) }
+        if var set = connectionRuns[connectionID] {
+            set.remove(identifier)
+            connectionRuns[connectionID] = set.isEmpty ? nil : set
+        }
+        lock.unlock()
+    }
+
+    private func handleBuild(connection: xpc_connection_t, request: xpc_object_t) {
+        guard let identifier = Self.string(request, Key.runIdentifier), !identifier.isEmpty else {
+            sendReply(connection: connection, request: request, error: "missing build identifier")
+            return
+        }
+        let stdoutFD = xpc_dictionary_dup_fd(request, Key.stdout)
+        let stderrFD = xpc_dictionary_dup_fd(request, Key.stderr)
+        guard stdoutFD >= 0, stderrFD >= 0 else {
+            if stdoutFD >= 0 { close(stdoutFD) }
+            if stderrFD >= 0 { close(stderrFD) }
+            sendExit(connection: connection, runIdentifier: identifier, exitCode: 125, message: "missing build output file descriptors")
+            return
+        }
+        let stdoutHandle = FileHandle(fileDescriptor: stdoutFD, closeOnDealloc: false)
+        let stderrHandle = FileHandle(fileDescriptor: stderrFD, closeOnDealloc: false)
+
+        let options: RuntimeBuildOptions
+        do {
+            options = try RuntimeBuildOptions.parse(Self.decodeArguments(request))
+        } catch {
+            try? stdoutHandle.close()
+            try? stderrHandle.close()
+            sendExit(connection: connection, runIdentifier: identifier, exitCode: 125, message: "invalid build payload: \(error.localizedDescription)")
+            return
+        }
+        guard let serialization = xpc_dictionary_get_value(request, Key.networkSerialization) else {
+            try? stdoutHandle.close()
+            try? stderrHandle.close()
+            sendExit(connection: connection, runIdentifier: identifier, exitCode: 125, message: "missing network serialization")
+            return
+        }
+        var vmnetStatus: vmnet_return_t = .VMNET_FAILURE
+        guard let networkReference = vmnet_network_create_with_serialization(serialization, &vmnetStatus),
+              vmnetStatus == .VMNET_SUCCESS else {
+            try? stdoutHandle.close()
+            try? stderrHandle.close()
+            sendExit(connection: connection, runIdentifier: identifier, exitCode: 125, message: "failed to reconstruct vmnet network (status \(vmnetStatus.rawValue))")
+            return
+        }
+        guard let ipv4Address = Self.string(request, Key.ipv4Address),
+              let ipv4Gateway = Self.string(request, Key.ipv4Gateway),
+              let macAddress = Self.string(request, Key.macAddress) else {
+            SharedVmnetNetwork.releaseVmnetReference(networkReference)
+            try? stdoutHandle.close()
+            try? stderrHandle.close()
+            sendExit(connection: connection, runIdentifier: identifier, exitCode: 125, message: "missing network endpoint fields")
+            return
+        }
+
+        let context = BuildContext(
+            connection: connection,
+            runIdentifier: identifier,
+            options: options,
+            networkReference: networkReference,
+            ipv4Address: ipv4Address,
+            ipv4Gateway: ipv4Gateway,
+            macAddress: macAddress,
+            mtu: UInt32(xpc_dictionary_get_uint64(request, Key.mtu)),
+            stdoutHandle: stdoutHandle,
+            stderrHandle: stderrHandle,
+            onComplete: { [weak self] context in self?.remove(context) }
+        )
+        lock.lock()
+        let duplicate = builds[identifier] != nil
+        if !duplicate {
+            builds[identifier] = context
+            connectionRuns[ObjectIdentifier(connection), default: []].insert(identifier)
+        }
+        lock.unlock()
+        guard !duplicate else {
+            sendExit(connection: connection, runIdentifier: identifier, exitCode: 125, message: "duplicate operation identifier '\(identifier)'")
+            return
+        }
+        xpc_transaction_begin()
+        context.start()
+    }
+
+    private func handleCancel(connection: xpc_connection_t, request: xpc_object_t) {
+        let connectionID = ObjectIdentifier(connection)
+        let runIdentifier = Self.string(request, Key.runIdentifier) ?? ""
+        lock.lock()
+        let belongs = connectionRuns[connectionID]?.contains(runIdentifier) ?? false
+        let build = belongs ? builds[runIdentifier] : nil
+        lock.unlock()
+        build?.cancelTask()
+        sendReply(connection: connection, request: request, ok: true, runIdentifier: runIdentifier)
+    }
+
+    private func handleShutdown(connection: xpc_connection_t, request: xpc_object_t) {
+        sendReply(connection: connection, request: request, ok: true)
+        let count = cancelAll(for: connection)
+        clearDirectSession(for: connection)
+        log("runtime[\(getpid())]: shutdown requested, cancelling \(count) operation(s) for this connection")
+    }
+
+    private func handleInvoke(connection: xpc_connection_t, request: xpc_object_t) {
+        guard let payload = Self.data(request, Key.payload) else {
+            sendReply(connection: connection, request: request, error: "missing invoke payload")
+            return
+        }
+
+        let directRequest: GhostboxDirectRequest
+        do {
+            directRequest = try JSONDecoder().decode(GhostboxDirectRequest.self, from: payload)
+        } catch {
+            sendReply(connection: connection, request: request, error: "invalid invoke payload: \(error)")
+            return
+        }
+
+        let session: GhostboxSession
+        do {
+            session = try directSession(for: connection, request: request)
+        } catch {
+            sendReply(connection: connection, request: request, error: error.localizedDescription)
+            return
+        }
+        do {
+            try session.beginInvocation()
+        } catch {
+            sendReply(connection: connection, request: request, error: error.localizedDescription)
+            return
+        }
+        let connectionBox = ConnectionBox(value: connection)
+        let requestBox = ConnectionBox(value: request)
+        xpc_transaction_begin()
+        Task { [self, directRequest, session, connectionBox, requestBox] in
+            defer {
+                session.endInvocation()
+                xpc_transaction_end()
+            }
+
+            let response: GhostboxDirectResponse
+            do {
+                try directRequest.validate()
+                let result = try await directDispatcher.dispatch(
+                    method: directRequest.method,
+                    parameters: directRequest.parameters,
+                    session: session
+                )
+                response = .success(id: directRequest.id, value: result)
+            } catch let error as DirectDispatchError {
+                response = .failure(id: directRequest.id, code: error.code, message: error.message)
+            } catch let error as ContainerizationError {
+                response = .failure(
+                    id: directRequest.id,
+                    code: Self.directErrorCode(error.code),
+                    message: error.localizedDescription
+                )
+            } catch let error as ContainerProtocolError {
+                response = .failure(
+                    id: directRequest.id,
+                    code: .invalidArgument,
+                    message: error.localizedDescription
+                )
+            } catch {
+                response = .failure(
+                    id: directRequest.id,
+                    code: .internalError,
+                    message: error.localizedDescription
+                )
+            }
+
+            do {
+                sendPayload(
+                    connection: connectionBox.value,
+                    request: requestBox.value,
+                    payload: try JSONEncoder().encode(response)
+                )
+            } catch {
+                sendReply(
+                    connection: connectionBox.value,
+                    request: requestBox.value,
+                    error: "failed to encode invoke response: \(error)"
+                )
+            }
+        }
+    }
+
+    private func handleAttach(connection: xpc_connection_t, request: xpc_object_t) {
+        guard let payload = Self.data(request, Key.payload) else {
+            sendReply(connection: connection, request: request, error: "missing attachment payload")
+            return
+        }
+        let descriptor = xpc_dictionary_dup_fd(request, Key.descriptor)
+        guard descriptor >= 0 else {
+            sendReply(connection: connection, request: request, error: "missing attachment descriptor")
+            return
+        }
+
+        let connectionBox = ConnectionBox(value: connection)
+        let requestBox = ConnectionBox(value: request)
+        let session: GhostboxSession
+        do {
+            session = try directSession(for: connection, request: request)
+        } catch {
+            Darwin.close(descriptor)
+            sendReply(connection: connection, request: request, error: error.localizedDescription)
+            return
+        }
+        do {
+            try session.beginInvocation()
+        } catch {
+            Darwin.close(descriptor)
+            sendReply(connection: connection, request: request, error: error.localizedDescription)
+            return
+        }
+        xpc_transaction_begin()
+        Task.detached { [self, connectionBox, requestBox, payload, session, descriptor] in
+            defer {
+                Darwin.close(descriptor)
+                session.endInvocation()
+                xpc_transaction_end()
+            }
+
+            var requestID = "unknown"
+            var sentResponse = false
+            do {
+                let directRequest = try JSONDecoder().decode(GhostboxDirectRequest.self, from: payload)
+                try directRequest.validate()
+                requestID = directRequest.id
+                let attachment = try ghostboxIOAttachment(
+                    method: directRequest.method,
+                    parameters: directRequest.parameters,
+                    session: session
+                )
+                let response = GhostboxDirectResponse.success(
+                    id: directRequest.id,
+                    value: .string(attachment.attachmentStream.rawValue)
+                )
+                guard ghostboxWriteAll(fd: descriptor, try response.encodeLine()) else {
+                    throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EPIPE)
+                }
+                sentResponse = true
+                try attachment.attach(fd: descriptor)
+            } catch let error as DirectDispatchError {
+                let frame: Data?
+                if sentResponse {
+                    frame = try? GhostboxIOFrame.error(error.message).encodeLine()
+                } else {
+                    frame = try? GhostboxDirectResponse.failure(
+                        id: requestID,
+                        code: error.code,
+                        message: error.message
+                    ).encodeLine()
+                }
+                if let frame { _ = ghostboxWriteAll(fd: descriptor, frame) }
+            } catch let error as ContainerProtocolError {
+                let frame: Data?
+                if sentResponse {
+                    frame = try? GhostboxIOFrame.error(error.localizedDescription).encodeLine()
+                } else {
+                    frame = try? GhostboxDirectResponse.failure(
+                        id: requestID,
+                        code: .invalidArgument,
+                        message: error.localizedDescription
+                    ).encodeLine()
+                }
+                if let frame { _ = ghostboxWriteAll(fd: descriptor, frame) }
+            } catch {
+                let message = error.localizedDescription
+                let frame: Data?
+                if sentResponse {
+                    frame = try? GhostboxIOFrame.error(message).encodeLine()
+                } else {
+                    frame = try? GhostboxDirectResponse.failure(
+                        id: requestID,
+                        code: .internalError,
+                        message: message
+                    ).encodeLine()
+                }
+                if let frame { _ = ghostboxWriteAll(fd: descriptor, frame) }
+            }
+            sendReply(connection: connectionBox.value, request: requestBox.value, ok: true)
+        }
+    }
+
+    private static func directErrorCode(_ code: ContainerizationError.Code) -> ContainerRuntimeErrorCode {
+        switch code {
+        case .invalidArgument: return .invalidArgument
+        case .exists: return .alreadyExists
+        case .notFound: return .notFound
+        case .cancelled, .interrupted: return .cancelled
+        case .invalidState, .empty: return .failedPrecondition
+        case .timeout: return .timeout
+        case .unsupported: return .unsupported
+        case .internalError, .unknown: return .internalError
+        default: return .internalError
+        }
+    }
+
+    private func directSession(for connection: xpc_connection_t, request: xpc_object_t) throws -> GhostboxSession {
+        let connectionID = ObjectIdentifier(connection)
+        lock.lock()
+        if let session = directSessions[connectionID] {
+            lock.unlock()
+            return session
+        }
+        guard let serialization = xpc_dictionary_get_value(request, Key.networkSerialization),
+              let subnetString = Self.string(request, Key.ipv4Subnet),
+              let volumeRoot = Self.string(request, Key.volumeRoot),
+              volumeRoot.hasPrefix("/"),
+              let imageRoot = Self.string(request, Key.imageRoot),
+              imageRoot.hasPrefix("/") else {
+            lock.unlock()
+            throw ContainerizationError(.invalidArgument, message: "missing shared GhostVM runtime metadata")
+        }
+        var status: vmnet_return_t = .VMNET_FAILURE
+        guard let reference = vmnet_network_create_with_serialization(serialization, &status),
+              status == .VMNET_SUCCESS else {
+            lock.unlock()
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to reconstruct shared GhostVM network (status \(status.rawValue))"
+            )
+        }
+        let network: GhostboxNetwork
+        do {
+            network = GhostboxNetwork(sharedReference: reference, subnet: try CIDRv4(subnetString))
+        } catch {
+            SharedVmnetNetwork.releaseVmnetReference(reference)
+            lock.unlock()
+            throw error
+        }
+        let session: GhostboxSession
+        do {
+            session = GhostboxSession(context: [
+                ghostboxSharedNetworkContextKey: network,
+                ghostboxVolumeStoreContextKey: GhostboxVolumeStore(rootURL: URL(fileURLWithPath: volumeRoot)),
+                ghostboxImageStoreContextKey: try ImageStore(path: URL(fileURLWithPath: imageRoot)),
+            ])
+        } catch {
+            SharedVmnetNetwork.releaseVmnetReference(reference)
+            lock.unlock()
+            throw error
+        }
+        directSessions[connectionID] = session
+        lock.unlock()
+        xpc_transaction_begin()
+        return session
+    }
+
+    private func clearDirectSession(for connection: xpc_connection_t) {
+        lock.lock()
+        let session = directSessions.removeValue(forKey: ObjectIdentifier(connection))
+        lock.unlock()
+        if let session {
+            Task {
+                await session.close()
+                xpc_transaction_end()
+            }
+        }
+    }
+
+    private func sendPayload(
+        connection: xpc_connection_t,
+        request: xpc_object_t,
+        payload: Data
+    ) {
+        let reply = xpc_dictionary_create_reply(request) ?? xpc_dictionary_create_empty()
+        payload.withUnsafeBytes { bytes in
+            xpc_dictionary_set_data(reply, Key.payload, bytes.baseAddress, bytes.count)
+        }
+        xpc_connection_send_message(connection, reply)
+    }
+
+    private func cancelAll(for connection: xpc_connection_t) -> Int {
+        let connectionID = ObjectIdentifier(connection)
+        lock.lock()
+        let runIdentifiers = connectionRuns[connectionID] ?? []
+        let buildContexts = runIdentifiers.compactMap { builds[$0] }
+        lock.unlock()
+        for context in buildContexts {
+            context.cancelTask()
+        }
+        return buildContexts.count
+    }
+
+    private func sendReply(
+        connection: xpc_connection_t,
+        request: xpc_object_t,
+        ok: Bool = false,
+        error: String? = nil,
+        runIdentifier: String? = nil
+    ) {
+        let reply = xpc_dictionary_create_reply(request) ?? xpc_dictionary_create_empty()
+        if ok {
+            xpc_dictionary_set_bool(reply, Key.ok, true)
+        }
+        if let error {
+            xpc_dictionary_set_string(reply, Key.error, error)
+        }
+        if let runIdentifier {
+            xpc_dictionary_set_string(reply, Key.runIdentifier, runIdentifier)
+        }
+        xpc_connection_send_message(connection, reply)
+    }
+
+    private func sendExit(
+        connection: xpc_connection_t,
+        runIdentifier: String,
+        exitCode: Int32,
+        message: String?
+    ) {
+        let event = xpc_dictionary_create_empty()
+        xpc_dictionary_set_string(event, Key.operation, Operation.exit)
+        xpc_dictionary_set_string(event, Key.runIdentifier, runIdentifier)
+        xpc_dictionary_set_int64(event, Key.exitCode, Int64(exitCode))
+        if let message {
+            xpc_dictionary_set_string(event, Key.error, message)
+        }
+        xpc_connection_send_message(connection, event)
+    }
+
+    private static func string(_ dictionary: xpc_object_t, _ key: String) -> String? {
+        guard let value = xpc_dictionary_get_string(dictionary, key) else { return nil }
+        return String(cString: value)
+    }
+
+    private static func decodeArguments(_ request: xpc_object_t) throws -> [String] {
+        guard let value = xpc_dictionary_get_value(request, Key.arguments) else {
+            return []
+        }
+        let length = xpc_data_get_length(value)
+        guard length > 0, let bytes = xpc_data_get_bytes_ptr(value) else {
+            return []
+        }
+        let data = Data(bytes: bytes, count: length)
+        return try JSONDecoder().decode([String].self, from: data)
+    }
+
+    private static func data(_ dictionary: xpc_object_t, _ key: String) -> Data? {
+        guard let value = xpc_dictionary_get_value(dictionary, key),
+              xpc_get_type(value) == XPC_TYPE_DATA,
+              let bytes = xpc_data_get_bytes_ptr(value) else {
+            return nil
+        }
+        return Data(bytes: bytes, count: xpc_data_get_length(value))
+    }
+
+}
+
+nonisolated(unsafe) private let broker = RuntimeBroker()
+
+nonisolated private func log(_ message: String) {
+    NSLog("%@", message)
+}
+
+/// `xpc_connection_t` is not Sendable in the XPC overlay, but each connection is
+/// retained by the runtime for the lifetime of its event handler and serviced
+/// serially on its target queue. This box lets the handler capture one safely.
+private struct ConnectionBox: @unchecked Sendable {
+    let value: xpc_connection_t
+}
+
+nonisolated private func acceptConnection(_ connection: xpc_connection_t) {
+    let connectionBox = ConnectionBox(value: connection)
+    xpc_connection_set_event_handler(connection) { event in
+        if xpc_get_type(event) == XPC_TYPE_DICTIONARY {
+            broker.handle(connection: connectionBox.value, request: event)
+        } else {
+            broker.disconnect(connection: connectionBox.value)
+        }
+    }
+    xpc_connection_activate(connection)
+}
+
+@main
+private struct GhostVMContainerRuntime {
+    nonisolated static func main() {
+        signal(SIGPIPE, SIG_IGN)
+        log("runtime[\(getpid())]: container runtime service starting")
+        xpc_main(acceptConnection)
+    }
+}
diff --git a/macOS/GhostVMContainerRuntime/entitlements.plist b/macOS/GhostVMContainerRuntime/entitlements.plist
new file mode 100644
index 0000000..dccbe21
--- /dev/null
+++ b/macOS/GhostVMContainerRuntime/entitlements.plist
@@ -0,0 +1,10 @@
+
+
+
+
+	com.apple.security.virtualization
+	
+	com.apple.vm.networking
+	
+
+
diff --git a/macOS/GhostVMFS/FileSystemExtension.swift b/macOS/GhostVMFS/FileSystemExtension.swift
new file mode 100644
index 0000000..43cb605
--- /dev/null
+++ b/macOS/GhostVMFS/FileSystemExtension.swift
@@ -0,0 +1,10 @@
+import ExtensionFoundation
+import FSKit
+import GhostFileKit
+
+@main
+struct GhostVMFileSystemExtension: UnaryFileSystemExtension {
+    var fileSystem: GhostFileSystem {
+        GhostFileSystem()
+    }
+}
diff --git a/macOS/GhostVMFS/Info.template.plist b/macOS/GhostVMFS/Info.template.plist
new file mode 100644
index 0000000..18e1ad4
--- /dev/null
+++ b/macOS/GhostVMFS/Info.template.plist
@@ -0,0 +1,66 @@
+
+
+
+
+	CFBundleDevelopmentRegion
+	$(DEVELOPMENT_LANGUAGE)
+	CFBundleExecutable
+	$(EXECUTABLE_NAME)
+	CFBundleIdentifier
+	$(PRODUCT_BUNDLE_IDENTIFIER)
+	CFBundleInfoDictionaryVersion
+	6.0
+	CFBundleName
+	$(PRODUCT_NAME)
+	CFBundlePackageType
+	XPC!
+	EXAppExtensionAttributes
+	
+		EXExtensionPointIdentifier
+		com.apple.fskit.fsmodule
+		FSActivateOptionSyntax
+		
+			shortOptions
+			g:m:o:u:
+		
+		FSCheckOptionSyntax
+		
+			shortOptions
+			nqy
+		
+		FSFormatOptionSyntax
+		
+			shortOptions
+			v
+		
+		FSMediaTypes
+		
+		FSPersonalities
+		
+			GhostVM
+			
+				FSName
+				ghostvm
+				FSfileObjectsAreCaseSensitive
+				
+			
+		
+		FSRequiresSecurityScopedPathURLResources
+		
+		FSShortName
+		ghostvm
+		FSSupportedSchemes
+		
+			ghostfile
+		
+		FSSupportsBlockResources
+		
+		FSSupportsGenericURLResources
+		
+		FSSupportsPathURLs
+		
+		FSSupportsServerURLs
+		
+	
+
+
diff --git a/macOS/GhostVMFS/entitlements.plist b/macOS/GhostVMFS/entitlements.plist
new file mode 100644
index 0000000..cbaa286
--- /dev/null
+++ b/macOS/GhostVMFS/entitlements.plist
@@ -0,0 +1,16 @@
+
+
+
+
+	com.apple.application-identifier
+	3FGZQE8AW3.org.ghostvm.ghostvm.fs
+	com.apple.developer.fskit.fsmodule
+	
+	com.apple.developer.team-identifier
+	3FGZQE8AW3
+	com.apple.security.app-sandbox
+	
+	com.apple.security.network.client
+	
+
+
diff --git a/macOS/GhostVMHelper/ContainerManagementWindow.swift b/macOS/GhostVMHelper/ContainerManagementWindow.swift
new file mode 100644
index 0000000..358f5fb
--- /dev/null
+++ b/macOS/GhostVMHelper/ContainerManagementWindow.swift
@@ -0,0 +1,538 @@
+import AppKit
+import GhostVMKit
+
+@MainActor
+final class ContainerManagementWindowController: NSWindowController, NSTableViewDataSource, NSTableViewDelegate, NSSearchFieldDelegate {
+    private enum Section: Int, CaseIterable {
+        case containers, images, volumes, logs
+
+        var title: String {
+            switch self {
+            case .containers: return "Containers"
+            case .images: return "Images"
+            case .volumes: return "Volumes"
+            case .logs: return "Logs"
+            }
+        }
+    }
+
+    private struct Item: Codable {
+        let id: String
+        let name: String
+        let detail: String
+        let status: String
+        let managerReference: String?
+    }
+
+    private let layout: VMFileLayout
+    private let runtime: () -> ContainerBridgeService?
+    private let tableView = NSTableView()
+    private let summaryLabel = NSTextField(labelWithString: "")
+    private let statusLabel = NSTextField(labelWithString: "")
+    private let searchField = NSSearchField()
+    private let addButton = NSButton()
+    private var section = Section.containers
+    private var items: [Item] = []
+    private var filteredItems: [Item] = []
+    private var imageStoreReference: String?
+
+    init(vmName: String, layout: VMFileLayout, runtime: @escaping () -> ContainerBridgeService?) {
+        self.layout = layout
+        self.runtime = runtime
+        let window = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 820, height: 520),
+            styleMask: [.titled, .closable, .miniaturizable, .resizable],
+            backing: .buffered,
+            defer: false
+        )
+        window.title = "Containers - \(vmName)"
+        window.minSize = NSSize(width: 650, height: 380)
+        window.isReleasedWhenClosed = false
+        window.setFrameAutosaveName("GhostVMContainerManagement")
+        super.init(window: window)
+        buildUI(in: window)
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    override func showWindow(_ sender: Any?) {
+        super.showWindow(sender)
+        window?.makeKeyAndOrderFront(sender)
+        refresh()
+    }
+
+    private func buildUI(in window: NSWindow) {
+        let root = NSView()
+        root.translatesAutoresizingMaskIntoConstraints = false
+        window.contentView = root
+
+        let title = NSTextField(labelWithString: "Container Management")
+        title.font = .systemFont(ofSize: 22, weight: .semibold)
+
+        let sectionControl = NSSegmentedControl(
+            labels: Section.allCases.map(\.title),
+            trackingMode: .selectOne,
+            target: self,
+            action: #selector(sectionChanged(_:))
+        )
+        sectionControl.selectedSegment = section.rawValue
+
+        let refreshButton = NSButton(
+            image: NSImage(systemSymbolName: "arrow.clockwise", accessibilityDescription: "Refresh")!,
+            target: self,
+            action: #selector(refreshClicked)
+        )
+        refreshButton.bezelStyle = .texturedRounded
+        refreshButton.toolTip = "Refresh"
+
+        addButton.image = NSImage(systemSymbolName: "plus", accessibilityDescription: "Add")
+        addButton.title = ""
+        addButton.target = self
+        addButton.action = #selector(addClicked)
+        addButton.bezelStyle = .texturedRounded
+        addButton.isEnabled = false
+
+        searchField.placeholderString = "Search"
+        searchField.delegate = self
+
+        summaryLabel.textColor = .secondaryLabelColor
+        statusLabel.textColor = .secondaryLabelColor
+        statusLabel.alignment = .right
+
+        let header = NSStackView(views: [title, NSView(), sectionControl, refreshButton, addButton])
+        header.orientation = .horizontal
+        header.alignment = .centerY
+        header.spacing = 8
+
+        let filterBar = NSStackView(views: [summaryLabel, NSView(), searchField])
+        filterBar.orientation = .horizontal
+        filterBar.alignment = .centerY
+        searchField.widthAnchor.constraint(equalToConstant: 220).isActive = true
+
+        addColumn("name", title: "Name", width: 230)
+        addColumn("detail", title: "Details", width: 310)
+        addColumn("status", title: "Status", width: 150)
+        addColumn("menu", title: "", width: 44)
+        tableView.headerView = NSTableHeaderView()
+        tableView.usesAlternatingRowBackgroundColors = true
+        tableView.rowHeight = 42
+        tableView.delegate = self
+        tableView.dataSource = self
+        tableView.allowsEmptySelection = true
+
+        let scrollView = NSScrollView()
+        scrollView.documentView = tableView
+        scrollView.hasVerticalScroller = true
+        scrollView.borderType = .bezelBorder
+
+        let stack = NSStackView(views: [header, filterBar, scrollView, statusLabel])
+        stack.orientation = .vertical
+        stack.alignment = .leading
+        stack.spacing = 12
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        root.addSubview(stack)
+
+        header.widthAnchor.constraint(equalTo: stack.widthAnchor).isActive = true
+        filterBar.widthAnchor.constraint(equalTo: stack.widthAnchor).isActive = true
+        scrollView.widthAnchor.constraint(equalTo: stack.widthAnchor).isActive = true
+        scrollView.setContentHuggingPriority(.defaultLow, for: .vertical)
+        statusLabel.widthAnchor.constraint(equalTo: stack.widthAnchor).isActive = true
+        NSLayoutConstraint.activate([
+            stack.leadingAnchor.constraint(equalTo: root.leadingAnchor, constant: 20),
+            stack.trailingAnchor.constraint(equalTo: root.trailingAnchor, constant: -20),
+            stack.topAnchor.constraint(equalTo: root.topAnchor, constant: 18),
+            stack.bottomAnchor.constraint(equalTo: root.bottomAnchor, constant: -14),
+        ])
+    }
+
+    private func addColumn(_ identifier: String, title: String, width: CGFloat) {
+        let column = NSTableColumn(identifier: NSUserInterfaceItemIdentifier(identifier))
+        column.title = title
+        column.width = width
+        if identifier == "menu" { column.resizingMask = [] }
+        tableView.addTableColumn(column)
+    }
+
+    func numberOfRows(in tableView: NSTableView) -> Int { filteredItems.count }
+
+    func tableView(_ tableView: NSTableView, viewFor tableColumn: NSTableColumn?, row: Int) -> NSView? {
+        guard row < filteredItems.count, let identifier = tableColumn?.identifier.rawValue else { return nil }
+        let item = filteredItems[row]
+        if identifier == "menu" {
+            let button = NSButton(image: NSImage(systemSymbolName: "ellipsis", accessibilityDescription: "Actions")!, target: self, action: #selector(showItemMenu(_:)))
+            button.bezelStyle = .inline
+            button.isBordered = false
+            button.tag = row
+            return button
+        }
+        let value: String
+        switch identifier {
+        case "name": value = item.name
+        case "detail": value = item.detail
+        default: value = item.status
+        }
+        let cell = NSTableCellView()
+        let label = NSTextField(labelWithString: value)
+        label.lineBreakMode = .byTruncatingMiddle
+        label.textColor = identifier == "status" ? statusColor(item.status) : .labelColor
+        label.translatesAutoresizingMaskIntoConstraints = false
+        cell.addSubview(label)
+        NSLayoutConstraint.activate([
+            label.leadingAnchor.constraint(equalTo: cell.leadingAnchor, constant: 4),
+            label.trailingAnchor.constraint(equalTo: cell.trailingAnchor, constant: -4),
+            label.centerYAnchor.constraint(equalTo: cell.centerYAnchor),
+        ])
+        return cell
+    }
+
+    private func statusColor(_ status: String) -> NSColor {
+        switch status.lowercased() {
+        case "running": return .systemGreen
+        case "stopped", "exited": return .secondaryLabelColor
+        case "stopping": return .systemOrange
+        default: return .labelColor
+        }
+    }
+
+    @objc private func sectionChanged(_ sender: NSSegmentedControl) {
+        section = Section(rawValue: sender.selectedSegment) ?? .containers
+        searchField.stringValue = ""
+        addButton.isEnabled = section == .images || section == .volumes
+        refresh()
+    }
+
+    @objc private func refreshClicked() { refresh() }
+
+    private func refresh() {
+        statusLabel.stringValue = "Refreshing..."
+        Task { @MainActor in
+            do {
+                switch section {
+                case .containers: items = try await loadContainers()
+                case .images: items = try await loadImages()
+                case .volumes: items = try await loadVolumes()
+                case .logs: items = try loadLogs()
+                }
+                applyFilter()
+                summaryLabel.stringValue = "\(items.count) \(section.title.lowercased())"
+                statusLabel.stringValue = items.isEmpty ? emptyMessage : "Updated \(Date().formatted(date: .omitted, time: .shortened))"
+            } catch {
+                if section == .containers, let cached = try? readContainerCache(), !cached.isEmpty {
+                    items = cached
+                    applyFilter()
+                    summaryLabel.stringValue = "\(items.count) containers - last known"
+                }
+                statusLabel.stringValue = error.localizedDescription
+            }
+        }
+    }
+
+    private var emptyMessage: String {
+        switch section {
+        case .containers: return "No containers"
+        case .images: return "No images"
+        case .volumes: return "No volumes"
+        case .logs: return "No retained container logs"
+        }
+    }
+
+    func controlTextDidChange(_ obj: Notification) { applyFilter() }
+
+    private func applyFilter() {
+        let query = searchField.stringValue.trimmingCharacters(in: .whitespacesAndNewlines)
+        filteredItems = query.isEmpty ? items : items.filter {
+            $0.name.localizedCaseInsensitiveContains(query) || $0.detail.localizedCaseInsensitiveContains(query)
+        }
+        tableView.reloadData()
+    }
+
+    private func invoke(_ method: String, _ parameters: [String: GhostboxJSONValue] = [:]) async throws -> GhostboxDirectValue {
+        guard let runtime = runtime() else {
+            throw NSError(domain: "GhostVMContainers", code: 1, userInfo: [NSLocalizedDescriptionKey: "Container runtime is unavailable"])
+        }
+        let response = try await runtime.invokeRuntime(GhostboxDirectRequest(method: .init(rawValue: method), parameters: parameters))
+        if let error = response.error {
+            throw NSError(domain: "GhostVMContainers", code: 2, userInfo: [NSLocalizedDescriptionKey: error.message])
+        }
+        guard let result = response.result else {
+            throw NSError(domain: "GhostVMContainers", code: 3, userInfo: [NSLocalizedDescriptionKey: "Container runtime returned no result"])
+        }
+        return result
+    }
+
+    private func loadContainers() async throws -> [Item] {
+        let result = try await invoke("container.list")
+        guard case .array(let values) = result.jsonValue else { return [] }
+        let loaded = values.compactMap { value -> Item? in
+            guard case .object(let object) = value,
+                  let reference = object.string("reference"),
+                  let name = object.string("name") else { return nil }
+            let cpu = object.integer("cpuCount").map(String.init) ?? "-"
+            let memory = object.unsignedInteger("memoryBytes").map(formatBytes) ?? "-"
+            return Item(
+                id: reference,
+                name: name,
+                detail: "CPU \(cpu)  Memory \(memory)",
+                status: object.string("status") ?? "unknown",
+                managerReference: object.string("managerReference")
+            )
+        }
+        try writeContainerCache(loaded)
+        return loaded
+    }
+
+    private func loadImages() async throws -> [Item] {
+        let store = try await invoke("imageStore.default")
+        guard let storeReference = store.referenceValue else { return [] }
+        imageStoreReference = storeReference
+        let list = try await invoke("imageStore.list", ["imageStore": .string(storeReference)])
+        var loaded: [Item] = []
+        for reference in list.referencesValue ?? [] {
+            let name = try await invoke("image.reference", ["image": .string(reference)]).jsonValue?.stringValue ?? reference
+            let digest = try await invoke("image.digest", ["image": .string(reference)]).jsonValue?.stringValue ?? ""
+            loaded.append(Item(id: reference, name: name, detail: digest, status: "Available", managerReference: nil))
+        }
+        return loaded
+    }
+
+    private func loadVolumes() async throws -> [Item] {
+        let list = try await invoke("volume.list")
+        var loaded: [Item] = []
+        for reference in list.referencesValue ?? [] {
+            let inspected = try await invoke("volume.inspect", ["volume": .string(reference)])
+            guard case .object(let object) = inspected.jsonValue else { continue }
+            loaded.append(Item(
+                id: reference,
+                name: object.string("name") ?? reference,
+                detail: "\(object.string("format") ?? "raw") - \(object.unsignedInteger("sizeInBytes").map(formatBytes) ?? "-")",
+                status: "Persistent",
+                managerReference: nil
+            ))
+        }
+        return loaded
+    }
+
+    private func loadLogs() throws -> [Item] {
+        let root = layout.containerRuntimeLogsURL
+        guard FileManager.default.fileExists(atPath: root.path) else { return [] }
+        return try FileManager.default.contentsOfDirectory(at: root, includingPropertiesForKeys: [.fileSizeKey, .contentModificationDateKey])
+            .filter { !$0.hasDirectoryPath }
+            .map { url in
+                let values = try? url.resourceValues(forKeys: [.fileSizeKey, .contentModificationDateKey])
+                return Item(
+                    id: url.path,
+                    name: url.deletingPathExtension().lastPathComponent,
+                    detail: values?.fileSize.map { formatBytes(UInt64($0)) } ?? "",
+                    status: values?.contentModificationDate?.formatted(date: .abbreviated, time: .shortened) ?? "",
+                    managerReference: nil
+                )
+            }
+            .sorted { $0.status > $1.status }
+    }
+
+    @objc private func showItemMenu(_ sender: NSButton) {
+        guard sender.tag < filteredItems.count else { return }
+        let item = filteredItems[sender.tag]
+        let menu = NSMenu()
+        switch section {
+        case .containers:
+            addMenuItem("Start", action: #selector(startContainer(_:)), item: item, to: menu)
+            addMenuItem("Stop", action: #selector(stopContainer(_:)), item: item, to: menu)
+            addMenuItem("Restart", action: #selector(restartContainer(_:)), item: item, to: menu)
+            if item.managerReference != nil {
+                menu.addItem(.separator())
+                addMenuItem("Remove...", action: #selector(removeContainer(_:)), item: item, to: menu)
+            }
+        case .images:
+            addMenuItem("Copy Reference", action: #selector(copyItemName(_:)), item: item, to: menu)
+            menu.addItem(.separator())
+            addMenuItem("Remove...", action: #selector(removeImage(_:)), item: item, to: menu)
+        case .volumes:
+            addMenuItem("Reveal in Finder", action: #selector(revealVolume(_:)), item: item, to: menu)
+            menu.addItem(.separator())
+            addMenuItem("Remove...", action: #selector(removeVolume(_:)), item: item, to: menu)
+        case .logs:
+            addMenuItem("Open", action: #selector(openLog(_:)), item: item, to: menu)
+            addMenuItem("Reveal in Finder", action: #selector(revealLog(_:)), item: item, to: menu)
+        }
+        menu.popUp(positioning: nil, at: NSPoint(x: sender.bounds.maxX, y: sender.bounds.minY), in: sender)
+    }
+
+    private func addMenuItem(_ title: String, action: Selector, item: Item, to menu: NSMenu) {
+        let menuItem = NSMenuItem(title: title, action: action, keyEquivalent: "")
+        menuItem.target = self
+        menuItem.representedObject = item.id
+        if let manager = item.managerReference { menuItem.identifier = NSUserInterfaceItemIdentifier(manager) }
+        menu.addItem(menuItem)
+    }
+
+    private func perform(_ method: String, parameters: [String: GhostboxJSONValue]) {
+        Task { @MainActor in
+            do {
+                _ = try await invoke(method, parameters)
+                refresh()
+            } catch {
+                present(error)
+            }
+        }
+    }
+
+    @objc private func startContainer(_ sender: NSMenuItem) {
+        perform("container.start", parameters: ["container": .string(sender.representedObject as! String)])
+    }
+
+    @objc private func stopContainer(_ sender: NSMenuItem) {
+        perform("container.stop", parameters: ["container": .string(sender.representedObject as! String)])
+    }
+
+    @objc private func restartContainer(_ sender: NSMenuItem) {
+        let reference = sender.representedObject as! String
+        Task { @MainActor in
+            do {
+                _ = try await invoke("container.stop", ["container": .string(reference)])
+                _ = try await invoke("container.start", ["container": .string(reference)])
+                refresh()
+            } catch { present(error) }
+        }
+    }
+
+    @objc private func removeContainer(_ sender: NSMenuItem) {
+        guard confirmRemoval("container"), let manager = sender.identifier?.rawValue else { return }
+        perform("manager.delete", parameters: [
+            "manager": .string(manager),
+            "container": .string(sender.representedObject as! String),
+        ])
+    }
+
+    @objc private func removeImage(_ sender: NSMenuItem) {
+        guard confirmRemoval("image"), let store = imageStoreReference,
+              let item = items.first(where: { $0.id == sender.representedObject as? String }) else { return }
+        perform("imageStore.delete", parameters: [
+            "imageStore": .string(store),
+            "reference": .string(item.name),
+            "performCleanup": .boolean(true),
+        ])
+    }
+
+    @objc private func removeVolume(_ sender: NSMenuItem) {
+        guard confirmRemoval("volume") else { return }
+        perform("volume.delete", parameters: ["volume": .string(sender.representedObject as! String)])
+    }
+
+    @objc private func copyItemName(_ sender: NSMenuItem) {
+        guard let item = items.first(where: { $0.id == sender.representedObject as? String }) else { return }
+        NSPasteboard.general.clearContents()
+        NSPasteboard.general.setString(item.name, forType: .string)
+    }
+
+    @objc private func revealVolume(_ sender: NSMenuItem) {
+        let name = (sender.representedObject as! String).replacingOccurrences(of: "@volume/", with: "")
+        NSWorkspace.shared.selectFile(nil, inFileViewerRootedAtPath: layout.containerRuntimeVolumesURL.appendingPathComponent(name).path)
+    }
+
+    @objc private func openLog(_ sender: NSMenuItem) { NSWorkspace.shared.open(URL(fileURLWithPath: sender.representedObject as! String)) }
+    @objc private func revealLog(_ sender: NSMenuItem) { NSWorkspace.shared.activateFileViewerSelecting([URL(fileURLWithPath: sender.representedObject as! String)]) }
+
+    @objc private func addClicked() {
+        switch section {
+        case .images: promptForImage()
+        case .volumes: promptForVolume()
+        default: break
+        }
+    }
+
+    private func promptForImage() {
+        let field = NSTextField(string: "")
+        field.placeholderString = "registry.example/image:tag"
+        guard runPrompt(title: "Pull Image", message: "Enter an OCI image reference.", accessory: field), !field.stringValue.isEmpty else { return }
+        Task { @MainActor in
+            do {
+                let store = try await invoke("imageStore.default").referenceValue
+                guard let store else { return }
+                _ = try await invoke("imageStore.pull", ["imageStore": .string(store), "reference": .string(field.stringValue)])
+                refresh()
+            } catch { present(error) }
+        }
+    }
+
+    private func promptForVolume() {
+        let name = NSTextField(string: "")
+        name.placeholderString = "volume-name"
+        let size = NSTextField(string: "8")
+        let stack = NSStackView(views: [NSTextField(labelWithString: "Name"), name, NSTextField(labelWithString: "Size (GB)"), size])
+        stack.orientation = .vertical
+        stack.alignment = .leading
+        name.widthAnchor.constraint(equalToConstant: 280).isActive = true
+        size.widthAnchor.constraint(equalToConstant: 280).isActive = true
+        guard runPrompt(title: "Create Volume", message: "Create persistent storage in this VM bundle.", accessory: stack),
+              !name.stringValue.isEmpty, let gigabytes = UInt64(size.stringValue), gigabytes > 0 else { return }
+        perform("volume.create", parameters: ["volume": .string(name.stringValue), "size": .unsignedInteger(gigabytes * 1_073_741_824)])
+    }
+
+    private func runPrompt(title: String, message: String, accessory: NSView) -> Bool {
+        let alert = NSAlert()
+        alert.messageText = title
+        alert.informativeText = message
+        alert.accessoryView = accessory
+        alert.addButton(withTitle: title.components(separatedBy: " ").first ?? "OK")
+        alert.addButton(withTitle: "Cancel")
+        return alert.runModal() == .alertFirstButtonReturn
+    }
+
+    private func confirmRemoval(_ noun: String) -> Bool {
+        let alert = NSAlert()
+        alert.messageText = "Remove \(noun)?"
+        alert.informativeText = "This action cannot be undone."
+        alert.alertStyle = .warning
+        alert.addButton(withTitle: "Remove")
+        alert.addButton(withTitle: "Cancel")
+        return alert.runModal() == .alertFirstButtonReturn
+    }
+
+    private func present(_ error: Error) {
+        let alert = NSAlert(error: error)
+        if let window { alert.beginSheetModal(for: window) }
+    }
+
+    private func writeContainerCache(_ values: [Item]) throws {
+        try FileManager.default.createDirectory(at: layout.containerRuntimeDirectoryURL, withIntermediateDirectories: true)
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+        try encoder.encode(values).write(to: layout.containerRuntimeMetadataURL, options: .atomic)
+    }
+
+    private func readContainerCache() throws -> [Item] {
+        try JSONDecoder().decode([Item].self, from: Data(contentsOf: layout.containerRuntimeMetadataURL))
+    }
+
+    private func formatBytes(_ bytes: UInt64) -> String {
+        ByteCountFormatter.string(fromByteCount: Int64(clamping: bytes), countStyle: .file)
+    }
+}
+
+private extension Dictionary where Key == String, Value == GhostboxJSONValue {
+    func string(_ key: String) -> String? {
+        guard case .string(let value) = self[key] else { return nil }
+        return value
+    }
+
+    func integer(_ key: String) -> Int64? {
+        guard case .integer(let value) = self[key] else { return nil }
+        return value
+    }
+
+    func unsignedInteger(_ key: String) -> UInt64? {
+        switch self[key] {
+        case .unsignedInteger(let value): return value
+        case .integer(let value) where value >= 0: return UInt64(value)
+        default: return nil
+        }
+    }
+}
+
+private extension GhostboxJSONValue {
+    var stringValue: String? {
+        guard case .string(let value) = self else { return nil }
+        return value
+    }
+}
diff --git a/macOS/GhostVMHelper/HelperToolbar.swift b/macOS/GhostVMHelper/HelperToolbar.swift
index 1f0d505..58ebaab 100644
--- a/macOS/GhostVMHelper/HelperToolbar.swift
+++ b/macOS/GhostVMHelper/HelperToolbar.swift
@@ -59,6 +59,7 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
     private enum ItemID {
         static let guestToolsStatus = NSToolbarItem.Identifier("guestToolsStatus")
         static let portForwards = NSToolbarItem.Identifier("portForwards")
+        static let containers = NSToolbarItem.Identifier("containers")
         static let sharedFolders = NSToolbarItem.Identifier("sharedFolders")
         static let clipboardSync = NSToolbarItem.Identifier("clipboardSync")
         static let iconChooser = NSToolbarItem.Identifier("iconChooser")
@@ -99,6 +100,7 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
     private weak var guestToolsLabel: NSTextField?
     private var iconChooserItem: NSToolbarItem?
     private var portForwardsItem: NSToolbarItem?
+    private var containersItem: NSToolbarItem?
     private var sharedFoldersItem: NSMenuToolbarItem?
     private var clipboardSyncItem: NSToolbarItem?
     private var terminalItem: NSMenuToolbarItem?
@@ -171,6 +173,15 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
         toolbar.autosavesConfiguration = true
         window.toolbar = toolbar
         window.toolbarStyle = .unifiedCompact
+
+        let migrationKey = "HelperToolbarIncludesContainerManagement"
+        if !UserDefaults.standard.bool(forKey: migrationKey) {
+            if !toolbar.items.contains(where: { $0.itemIdentifier == ItemID.containers }) {
+                let portIndex = toolbar.items.firstIndex(where: { $0.itemIdentifier == ItemID.portForwards }) ?? 0
+                toolbar.insertItem(withItemIdentifier: ItemID.containers, at: min(portIndex + 1, toolbar.items.count))
+            }
+            UserDefaults.standard.set(true, forKey: migrationKey)
+        }
     }
 
     /// Returns the anchor view for a toolbar item identifier.
@@ -182,6 +193,7 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
         switch identifier {
         case ItemID.guestToolsStatus: item = guestToolsItem
         case ItemID.portForwards: item = portForwardsItem
+        case ItemID.containers: item = containersItem
         case ItemID.clipboardSync: item = clipboardSyncItem
         case ItemID.captureCommands: item = captureCommandsItem
         case ItemID.queuedFiles: item = queuedFilesItem
@@ -326,6 +338,7 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
         [
             ItemID.iconChooser,
             ItemID.portForwards,
+            ItemID.containers,
             ItemID.sharedFolders,
             ItemID.clipboardSync,
             ItemID.terminal,
@@ -342,6 +355,7 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
         [
             ItemID.iconChooser,
             ItemID.portForwards,
+            ItemID.containers,
             ItemID.sharedFolders,
             ItemID.clipboardSync,
             ItemID.terminal,
@@ -361,6 +375,8 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
             return makeIconChooserItem()
         case ItemID.portForwards:
             return makePortForwardsItem()
+        case ItemID.containers:
+            return makeContainersItem()
         case ItemID.sharedFolders:
             return makeSharedFoldersItem()
         case ItemID.clipboardSync:
@@ -461,6 +477,24 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
         return item
     }
 
+    private func makeContainersItem() -> NSToolbarItem {
+        let item = NSToolbarItem(itemIdentifier: ItemID.containers)
+        item.label = "Containers"
+        item.paletteLabel = "Container Management"
+        item.toolTip = "Manage containers, images, volumes, and logs"
+        item.minSize = NSSize(width: 36, height: 32)
+        item.maxSize = NSSize(width: 36, height: 32)
+
+        let image = NSImage(systemSymbolName: "server.rack", accessibilityDescription: "Containers")!
+            .withSymbolConfiguration(iconConfig)!
+        let button = NSButton(image: image, target: self, action: #selector(containersClicked))
+        button.bezelStyle = .toolbar
+        button.isBordered = true
+        item.view = button
+        containersItem = item
+        return item
+    }
+
     private func makeSharedFoldersItem() -> NSToolbarItem {
         let item = NSMenuToolbarItem(itemIdentifier: ItemID.sharedFolders)
         item.label = "Folders"
@@ -1135,6 +1169,10 @@ final class HelperToolbar: NSObject, NSToolbarDelegate, NSMenuDelegate, PortForw
         }
     }
 
+    @objc private func containersClicked() {
+        delegate?.toolbarDidRequestContainerManagement(self)
+    }
+
     @objc private func revealSharedFolder(_ sender: NSMenuItem) {
         guard let path = sender.representedObject as? String else { return }
         NSWorkspace.shared.selectFile(nil, inFileViewerRootedAtPath: path)
@@ -1569,5 +1607,6 @@ protocol HelperToolbarDelegate: AnyObject {
     func toolbar(_ toolbar: HelperToolbar, didUnblockPort port: UInt16)
     func toolbarDidUnblockAllPorts(_ toolbar: HelperToolbar)
     func toolbarDidRequestIconChooser(_ toolbar: HelperToolbar)
+    func toolbarDidRequestContainerManagement(_ toolbar: HelperToolbar)
     func toolbar(_ toolbar: HelperToolbar, didSelectIconMode mode: String?, icon: NSImage?)
 }
diff --git a/macOS/GhostVMHelper/main.swift b/macOS/GhostVMHelper/main.swift
index a60fbb4..088ce5d 100644
--- a/macOS/GhostVMHelper/main.swift
+++ b/macOS/GhostVMHelper/main.swift
@@ -39,6 +39,8 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
     private var virtualMachine: VZVirtualMachine?
     private var vmQueue: DispatchQueue?
     private var layout: VMFileLayout?
+    private var sharedVmnetNetwork: SharedVmnetNetwork?
+    private var hostContainersEnabled = false
     private var pendingWindowStateSaveWorkItem: DispatchWorkItem?
     private var shouldEnterFullScreenOnShow = false
     private let windowConfigQueue = DispatchQueue(label: "org.ghostvm.helper.windowConfig", qos: .utility)
@@ -49,6 +51,7 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
 
     private var ownsLock = false
     private var helperToolbar: HelperToolbar?
+    private var containerManagementWindowController: ContainerManagementWindowController?
     private var statusOverlay: StatusOverlay?
 
     // Services
@@ -61,6 +64,8 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
     private var healthCheckService: HealthCheckService?
     private var autoPortMapService: AutoPortMapService?
     private var hostAPIService: HostAPIService?
+    private var guestFileSystemBridgeService: GuestFileSystemBridgeService?
+    private var containerBridgeService: ContainerBridgeService?
     private var bridgeMonitorService: BridgeMonitorService?
     private var autoPortMapCancellable: AnyCancellable?
     private var fileTransferCancellable: AnyCancellable?
@@ -829,6 +834,18 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
         helperToolbar?.showIconChooserPopover(bundleURL: vmBundleURL)
     }
 
+    func toolbarDidRequestContainerManagement(_ toolbar: HelperToolbar) {
+        if containerManagementWindowController == nil {
+            containerManagementWindowController = ContainerManagementWindowController(
+                vmName: vmName,
+                layout: VMFileLayout(bundleURL: vmBundleURL),
+                runtime: { [weak self] in self?.containerBridgeService }
+            )
+        }
+        containerManagementWindowController?.showWindow(nil)
+        NSApp.activate(ignoringOtherApps: true)
+    }
+
     func toolbar(_ toolbar: HelperToolbar, didSelectIconMode mode: String?, icon: NSImage?) {
         // Update live icon mode so handleForegroundAppChange reacts immediately
         activeIconMode = mode
@@ -1333,9 +1350,44 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
                 try store.save(config)
             }
 
+            // Container-enabled NAT VMs own one vmnet network shared by the
+            // macOS guest and every container launched for this VM.
+            let networkConfig = config.networkConfig ?? NetworkConfig.defaultConfig
+            hostContainersEnabled = config.hostContainersEnabled && networkConfig.mode == .nat
+            if hostContainersEnabled {
+                guard let vmMACAddress = config.macAddress else {
+                    throw VMError.message("NAT networking requires a persistent VM MAC address.")
+                }
+                let networkIdentifier = String(vmBundleURL.path.stableHash)
+                let sharedNetwork = try SharedVmnetNetwork(
+                    networkIdentifier: networkIdentifier,
+                    vmMACAddress: vmMACAddress,
+                    preferredIPv4Subnet: networkConfig.vmnetIPv4Subnet
+                )
+                sharedVmnetNetwork = sharedNetwork
+                if networkConfig.vmnetIPv4Subnet != sharedNetwork.ipv4Subnet {
+                    var updatedNetworkConfig = networkConfig
+                    updatedNetworkConfig.vmnetIPv4Subnet = sharedNetwork.ipv4Subnet
+                    config.networkConfig = updatedNetworkConfig
+                    config.modifiedAt = Date()
+                    try store.save(config)
+                }
+                NSLog(
+                    "GhostVMHelper: Created shared vmnet network %@ (%@, gateway %@)",
+                    networkIdentifier,
+                    sharedNetwork.ipv4Subnet,
+                    sharedNetwork.ipv4Gateway
+                )
+            }
+
             // Build VM configuration
             let builder = VMConfigurationBuilder(layout: layout!, storedConfig: config)
-            let vmConfiguration = try builder.makeConfiguration(headless: false, connectSerialToStandardIO: false, runtimeSharedFolder: nil)
+            let vmConfiguration = try builder.makeConfiguration(
+                headless: false,
+                connectSerialToStandardIO: false,
+                runtimeSharedFolder: nil,
+                natNetworkAttachment: sharedVmnetNetwork?.attachment
+            )
 
             // Create VM
             vmQueue = DispatchQueue(label: "ghostvm.helper.\(vmName)")
@@ -1617,6 +1669,8 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
             ownsLock = false
         }
         vmView?.virtualMachine = nil
+        sharedVmnetNetwork?.close()
+        sharedVmnetNetwork = nil
     }
 
     // MARK: - Services
@@ -1633,6 +1687,47 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
         apiService.start(client: client, vmWindow: self.window)
         self.hostAPIService = apiService
 
+        // 1c. Container bridge: guest-initiated vsock control listener (port 5004).
+        if hostContainersEnabled {
+            NSLog("GhostVMHelper: host containers enabled — starting container bridge listener on vsock port \(ContainerBridgeConstants.port)")
+            let fileSystemBridge = GuestFileSystemBridgeService()
+            do {
+                try fileSystemBridge.start(client: client)
+                self.guestFileSystemBridgeService = fileSystemBridge
+                if let debugPath = UserDefaults.standard.string(forKey: "GuestFilesystemExportPath") {
+                    Task { @MainActor in
+                        do {
+                            let resource = try await fileSystemBridge.registerExport(guestPath: debugPath)
+                            NSLog(
+                                "GhostVMHelper: Debug guest filesystem export ready at %@:%d",
+                                resource.resourceURL.host ?? "loopback",
+                                resource.resourceURL.port ?? 0
+                            )
+                        } catch {
+                            NSLog("GhostVMHelper: Failed to start debug filesystem export: \(error.localizedDescription)")
+                        }
+                    }
+                }
+            } catch {
+                NSLog("GhostVMHelper: Failed to start guest filesystem bridge: \(error.localizedDescription)")
+            }
+            if sharedVmnetNetwork != nil {
+                let bridge = ContainerBridgeService(
+                    vm: vm,
+                    vmQueue: queue,
+                    vmHash: String(vmBundleURL.path.stableHash),
+                    sharedNetwork: sharedVmnetNetwork!,
+                    volumeRootURL: VMFileLayout(bundleURL: vmBundleURL).containerRuntimeVolumesURL,
+                    imageRootURL: VMFileLayout(bundleURL: vmBundleURL).containerRuntimeImagesURL,
+                    fileSystemBridge: fileSystemBridge
+                )
+                bridge.start()
+                self.containerBridgeService = bridge
+            } else {
+                NSLog("GhostVMHelper: Container bridge requires a shared vmnet network")
+            }
+        }
+
         // 2. Guest health polling via the unified HTTP server on vsock port 5000
         let hcService = HealthCheckService()
         hcService.start(client: client)
@@ -1839,6 +1934,12 @@ final class HelperAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate
         eventStreamService?.stop()
         eventStreamService = nil
 
+        containerBridgeService?.stop()
+        containerBridgeService = nil
+
+        guestFileSystemBridgeService?.stop()
+        guestFileSystemBridgeService = nil
+
         hostAPIService?.stop()
         hostAPIService = nil
 
@@ -2325,6 +2426,17 @@ private func formattedBuildDate(from version: String) -> String? {
 // which PortForwardListener handles gracefully.
 signal(SIGPIPE, SIG_IGN)
 
+if CommandLine.arguments.contains("--container-runtime-xpc-self-test") {
+    do {
+        try ContainerRuntimeXPCClient.ping()
+        print("GhostVMContainerRuntime XPC: ready")
+        exit(0)
+    } catch {
+        FileHandle.standardError.write(Data("GhostVMContainerRuntime XPC: \(error.localizedDescription)\n".utf8))
+        exit(1)
+    }
+}
+
 MainActor.assumeIsolated {
     let app = HelperApplication.shared
     let delegate = HelperAppDelegate()
diff --git a/macOS/GhostVMImageFetch/FetchMain.swift b/macOS/GhostVMImageFetch/FetchMain.swift
new file mode 100644
index 0000000..733eceb
--- /dev/null
+++ b/macOS/GhostVMImageFetch/FetchMain.swift
@@ -0,0 +1,194 @@
+import Containerization
+import ContainerizationArchive
+import ContainerizationError
+import ContainerizationExtras
+import ContainerizationOCI
+import CryptoKit
+import Foundation
+
+private let initfsReference = "ghcr.io/apple/containerization/vminit@sha256:a69ff331d77997042afc3c7389969be176dfb657ec9ed46366c0e057ec40a297"
+
+private func writeStatus(_ message: String) {
+    try? FileHandle.standardError.write(contentsOf: Data("ghostvm-image-fetch: \(message)\n".utf8))
+}
+
+private actor ImagePullProgress {
+    private static let reportInterval: Int64 = 4 * 1024 * 1024
+
+    private let reference: String
+    private var completedBytes: Int64 = 0
+    private var totalBytes: Int64 = 0
+    private var lastReportedBytes: Int64 = 0
+
+    init(reference: String) {
+        self.reference = reference
+    }
+
+    func update(_ events: [ProgressEvent]) {
+        for event in events {
+            switch event {
+            case .addSize(let value): completedBytes += value
+            case .addTotalSize(let value): totalBytes += value
+            case .addItems, .addTotalItems: break
+            }
+        }
+
+        if completedBytes - lastReportedBytes >= Self.reportInterval {
+            report()
+        }
+    }
+
+    func finish() {
+        report(force: true)
+    }
+
+    private func report(force: Bool = false) {
+        guard force || completedBytes != lastReportedBytes else { return }
+        lastReportedBytes = completedBytes
+        let completed = ByteCountFormatter.string(fromByteCount: completedBytes, countStyle: .file)
+        if totalBytes > 0 {
+            let total = ByteCountFormatter.string(fromByteCount: totalBytes, countStyle: .file)
+            let percent = min(100, Int((Double(completedBytes) / Double(totalBytes)) * 100))
+            writeStatus("Pulling \(reference): \(completed) / \(total) (\(percent)%)")
+        } else {
+            writeStatus("Pulling \(reference): \(completed)")
+        }
+    }
+}
+
+private struct FetchOptions {
+    let root: URL
+    let kernel: URL
+    let image: String
+
+    static func parse(_ arguments: [String]) throws -> FetchOptions {
+        guard arguments.first == "fetch" else { throw FetchError.usage }
+        var root: String?
+        var kernel: String?
+        var image: String?
+        var index = 1
+        while index < arguments.count {
+            guard index + 1 < arguments.count else { throw FetchError.usage }
+            switch arguments[index] {
+            case "--root": root = arguments[index + 1]
+            case "--kernel": kernel = arguments[index + 1]
+            case "--image": image = arguments[index + 1]
+            default: throw FetchError.usage
+            }
+            index += 2
+        }
+        guard let root, let kernel, let image else { throw FetchError.usage }
+        return FetchOptions(
+            root: URL(fileURLWithPath: root, isDirectory: true),
+            kernel: URL(fileURLWithPath: kernel),
+            image: image
+        )
+    }
+}
+
+private enum FetchError: Error, LocalizedError {
+    case usage
+    case unqualifiedImageReference(String)
+    case kernelDownloadFailed
+    case kernelDigestMismatch
+
+    var errorDescription: String? {
+        switch self {
+        case .usage:
+            return "usage: ghostvm-image-fetch fetch --root PATH --kernel PATH --image IMAGE"
+        case .unqualifiedImageReference(let reference):
+            return "image reference must include an explicit registry domain: \(reference)"
+        case .kernelDownloadFailed:
+            return "failed to download the container kernel"
+        case .kernelDigestMismatch:
+            return "downloaded container kernel archive failed SHA-256 verification"
+        }
+    }
+}
+
+@main
+private struct GhostVMImageFetch {
+    static func main() async {
+        do {
+            let options = try FetchOptions.parse(Array(CommandLine.arguments.dropFirst()))
+            let references = try [options.image, initfsReference].map(normalizeReference)
+            try await prepareKernel(at: options.kernel)
+            let store = try ImageStore(path: options.root)
+            for reference in references {
+                writeStatus("Resolving image \(reference)...")
+                do {
+                    _ = try await store.get(reference: reference)
+                    writeStatus("Image cached: \(reference)")
+                    continue
+                } catch let error as ContainerizationError where error.code == .notFound {
+                    let progress = ImagePullProgress(reference: reference)
+                    _ = try await store.pull(reference: reference, progress: { events in
+                        await progress.update(events)
+                    })
+                    await progress.finish()
+                }
+                writeStatus("Image ready: \(reference)")
+            }
+            writeStatus("Fetch complete.")
+        } catch {
+            let message = (error as? LocalizedError)?.errorDescription ?? String(describing: error)
+            try? FileHandle.standardError.write(contentsOf: Data("ghostvm-image-fetch: \(message)\n".utf8))
+            exit(125)
+        }
+    }
+
+    private static func prepareKernel(at destination: URL) async throws {
+        if FileManager.default.isReadableFile(atPath: destination.path) {
+            writeStatus("Kernel ready (cached): \(destination.path)")
+            return
+        }
+
+        let archiveURL = URL(string: "https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst")!
+        let expectedDigest = "f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91"
+        let kernelPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186"
+        writeStatus("Downloading container kernel...")
+        let (downloadURL, response) = try await URLSession.shared.download(from: archiveURL)
+        guard let response = response as? HTTPURLResponse, response.statusCode == 200 else {
+            throw FetchError.kernelDownloadFailed
+        }
+        writeStatus("Verifying container kernel...")
+        guard try sha256(of: downloadURL) == expectedDigest else {
+            throw FetchError.kernelDigestMismatch
+        }
+
+        var reader = try ArchiveReader(file: downloadURL)
+        var (entry, kernelData) = try reader.extractFile(path: kernelPath)
+        if entry.fileType == .symbolicLink, let link = entry.symlinkTarget {
+            let target = URL(filePath: kernelPath)
+                .deletingLastPathComponent()
+                .appending(path: link)
+                .standardized
+                .relativePath
+            reader = try ArchiveReader(file: downloadURL)
+            (entry, kernelData) = try reader.extractFile(path: target)
+        }
+        _ = entry
+        try FileManager.default.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)
+        try kernelData.write(to: destination, options: .atomic)
+        writeStatus("Kernel ready: \(destination.path)")
+    }
+
+    private static func normalizeReference(_ value: String) throws -> String {
+        let reference = try Reference.parse(value)
+        guard reference.domain != nil else {
+            throw FetchError.unqualifiedImageReference(value)
+        }
+        reference.normalize()
+        return reference.description
+    }
+
+    private static func sha256(of url: URL) throws -> String {
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+        var hasher = SHA256()
+        while let data = try handle.read(upToCount: 1024 * 1024), !data.isEmpty {
+            hasher.update(data: data)
+        }
+        return hasher.finalize().map { String(format: "%02x", $0) }.joined()
+    }
+}
diff --git a/macOS/GhostVMKit/Configuration/VMConfigurationBuilder.swift b/macOS/GhostVMKit/Configuration/VMConfigurationBuilder.swift
index a4fae99..b9db5d5 100644
--- a/macOS/GhostVMKit/Configuration/VMConfigurationBuilder.swift
+++ b/macOS/GhostVMKit/Configuration/VMConfigurationBuilder.swift
@@ -13,7 +13,12 @@ public final class VMConfigurationBuilder {
         self.storedConfig = storedConfig
     }
 
-    public func makeConfiguration(headless: Bool, connectSerialToStandardIO: Bool, runtimeSharedFolder: RuntimeSharedFolderOverride?) throws -> VZVirtualMachineConfiguration {
+    public func makeConfiguration(
+        headless: Bool,
+        connectSerialToStandardIO: Bool,
+        runtimeSharedFolder: RuntimeSharedFolderOverride?,
+        natNetworkAttachment: VZNetworkDeviceAttachment? = nil
+    ) throws -> VZVirtualMachineConfiguration {
         let config = VZVirtualMachineConfiguration()
 
         config.bootLoader = VZMacOSBootLoader()
@@ -63,7 +68,7 @@ public final class VMConfigurationBuilder {
         switch networkConfig.mode {
         case .nat:
             print("[VMConfigurationBuilder] Using NAT networking")
-            networkDevice.attachment = VZNATNetworkDeviceAttachment()
+            networkDevice.attachment = natNetworkAttachment ?? VZNATNetworkDeviceAttachment()
 
         case .bridged:
             print("[VMConfigurationBuilder] Attempting bridged networking with interface: \(networkConfig.bridgeInterfaceIdentifier ?? "nil")")
diff --git a/macOS/GhostVMKit/Containers/ContainerBridgeProtocol.swift b/macOS/GhostVMKit/Containers/ContainerBridgeProtocol.swift
new file mode 100644
index 0000000..a011eb8
--- /dev/null
+++ b/macOS/GhostVMKit/Containers/ContainerBridgeProtocol.swift
@@ -0,0 +1,28 @@
+import Foundation
+
+/// Constants for the guest-initiated direct Containerization API channel.
+public enum ContainerBridgeConstants {
+    public static let port: UInt32 = 5004
+    public static let protocolVersion = 5
+    public static let maxRequestLineBytes = 64 * 1024
+}
+
+public enum ContainerProtocolError: Error, LocalizedError, Equatable {
+    case emptyRequest
+    case requestTooLarge(limit: Int)
+    case malformedRequest(String)
+    case connectionClosed
+
+    public var errorDescription: String? {
+        switch self {
+        case .emptyRequest:
+            return "Empty direct API request."
+        case .requestTooLarge(let limit):
+            return "Request line exceeds the \(limit)-byte limit."
+        case .malformedRequest(let detail):
+            return "Malformed direct API request: \(detail)"
+        case .connectionClosed:
+            return "Connection closed by peer."
+        }
+    }
+}
diff --git a/macOS/GhostVMKit/Containers/ContainerRuntimeProtocol.swift b/macOS/GhostVMKit/Containers/ContainerRuntimeProtocol.swift
new file mode 100644
index 0000000..17b7b5f
--- /dev/null
+++ b/macOS/GhostVMKit/Containers/ContainerRuntimeProtocol.swift
@@ -0,0 +1,260 @@
+import Foundation
+
+/// Version of the backend-neutral container runtime API.
+public struct ContainerRuntimeVersion: Codable, Equatable, Sendable {
+    public static let current = ContainerRuntimeVersion(major: 1, minor: 0)
+
+    public var major: Int
+    public var minor: Int
+
+    public init(major: Int, minor: Int) {
+        self.major = major
+        self.minor = minor
+    }
+
+    public func isCompatible(with other: ContainerRuntimeVersion) -> Bool {
+        major == other.major
+    }
+}
+
+/// Extensible method name used by frontends and runtime backends.
+public struct ContainerRuntimeMethod: RawRepresentable, Codable, Hashable, Sendable {
+    public let rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        self.rawValue = try container.decode(String.self)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(rawValue)
+    }
+
+    public static let systemCapabilities = Self(rawValue: "system.capabilities")
+
+    public static let imagePull = Self(rawValue: "image.pull")
+    public static let imageList = Self(rawValue: "image.list")
+    public static let imageInspect = Self(rawValue: "image.inspect")
+    public static let imageDelete = Self(rawValue: "image.delete")
+    public static let imageUnpack = Self(rawValue: "image.unpack")
+
+    public static let filesystemCreate = Self(rawValue: "filesystem.create")
+    public static let filesystemDelete = Self(rawValue: "filesystem.delete")
+
+    public static let containerCreate = Self(rawValue: "container.create")
+    public static let containerStart = Self(rawValue: "container.start")
+    public static let containerStop = Self(rawValue: "container.stop")
+    public static let containerKill = Self(rawValue: "container.kill")
+    public static let containerWait = Self(rawValue: "container.wait")
+    public static let containerResize = Self(rawValue: "container.resize")
+    public static let containerState = Self(rawValue: "container.state")
+    public static let containerList = Self(rawValue: "container.list")
+    public static let containerDelete = Self(rawValue: "container.delete")
+    public static let containerCopyIn = Self(rawValue: "container.copyIn")
+    public static let containerCopyOut = Self(rawValue: "container.copyOut")
+    public static let containerDial = Self(rawValue: "container.dial")
+
+    public static let processCreate = Self(rawValue: "process.create")
+    public static let processStart = Self(rawValue: "process.start")
+    public static let processKill = Self(rawValue: "process.kill")
+    public static let processWait = Self(rawValue: "process.wait")
+    public static let processResize = Self(rawValue: "process.resize")
+    public static let processDelete = Self(rawValue: "process.delete")
+
+    public static let networkCreateInterface = Self(rawValue: "network.createInterface")
+    public static let networkReleaseInterface = Self(rawValue: "network.releaseInterface")
+
+    public static let buildCreate = Self(rawValue: "build.create")
+}
+
+/// Metadata decoded before selecting a method-specific parameter type.
+public struct ContainerRuntimeRequestEnvelope: Codable, Equatable, Sendable {
+    public var version: ContainerRuntimeVersion
+    public var id: String
+    public var method: ContainerRuntimeMethod
+
+    public init(
+        version: ContainerRuntimeVersion = .current,
+        id: String = UUID().uuidString.lowercased(),
+        method: ContainerRuntimeMethod
+    ) {
+        self.version = version
+        self.id = id
+        self.method = method
+    }
+}
+
+public struct ContainerRuntimeRequest: Codable, Equatable, Sendable {
+    public var version: ContainerRuntimeVersion
+    public var id: String
+    public var method: ContainerRuntimeMethod
+    public var parameters: Parameters
+
+    public init(
+        version: ContainerRuntimeVersion = .current,
+        id: String = UUID().uuidString.lowercased(),
+        method: ContainerRuntimeMethod,
+        parameters: Parameters
+    ) {
+        self.version = version
+        self.id = id
+        self.method = method
+        self.parameters = parameters
+    }
+}
+
+public struct ContainerRuntimeEmpty: Codable, Equatable, Sendable {
+    public init() {}
+}
+
+/// A directory exported by GhostTools and materialized as a host filesystem.
+public struct ContainerRuntimeFilesystemCreateParameters: Codable, Equatable, Sendable {
+    public var guestPath: String
+    public var readOnly: Bool
+
+    public init(guestPath: String, readOnly: Bool = true) {
+        self.guestPath = guestPath
+        self.readOnly = readOnly
+    }
+}
+
+public struct ContainerRuntimeFilesystem: Codable, Equatable, Sendable {
+    public var id: String
+
+    public init(id: String) {
+        self.id = id
+    }
+}
+
+public struct ContainerRuntimeFilesystemDeleteParameters: Codable, Equatable, Sendable {
+    public var id: String
+
+    public init(id: String) {
+        self.id = id
+    }
+}
+
+/// Metadata for `build.create`. The build context is carried by the bounded
+/// binary input stream associated with the request, never embedded in JSON.
+public struct ContainerRuntimeBuildCreateParameters: Codable, Equatable, Sendable {
+    public var tags: [String]
+    public var dockerfile: Data
+    public var buildArguments: [String]
+    public var target: String?
+    public var noCache: Bool
+    public var pull: Bool
+    public var contextMediaType: String
+
+    public init(
+        tags: [String],
+        dockerfile: Data,
+        buildArguments: [String] = [],
+        target: String? = nil,
+        noCache: Bool = false,
+        pull: Bool = false,
+        contextMediaType: String = "application/vnd.oci.image.layer.v1.tar"
+    ) {
+        self.tags = tags
+        self.dockerfile = dockerfile
+        self.buildArguments = buildArguments
+        self.target = target
+        self.noCache = noCache
+        self.pull = pull
+        self.contextMediaType = contextMediaType
+    }
+}
+
+public struct ContainerRuntimeBuildResult: Codable, Equatable, Sendable {
+    public var imageID: String
+    public var tags: [String]
+
+    public init(imageID: String, tags: [String]) {
+        self.imageID = imageID
+        self.tags = tags
+    }
+}
+
+/// Framework-shaped mount metadata. `source` is a host-owned filesystem ID,
+/// never an outer-host path supplied by the guest.
+public struct ContainerRuntimeMount: Codable, Equatable, Sendable {
+    public var type: String
+    public var source: String
+    public var destination: String
+    public var options: [String]
+    public var runtimeOptions: [String]
+
+    public init(
+        type: String,
+        source: String,
+        destination: String,
+        options: [String] = [],
+        runtimeOptions: [String] = []
+    ) {
+        self.type = type
+        self.source = source
+        self.destination = destination
+        self.options = options
+        self.runtimeOptions = runtimeOptions
+    }
+}
+
+public struct ContainerRuntimeErrorCode: RawRepresentable, Codable, Hashable, Sendable {
+    public let rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        self.rawValue = try container.decode(String.self)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(rawValue)
+    }
+
+    public static let invalidArgument = Self(rawValue: "invalid_argument")
+    public static let notFound = Self(rawValue: "not_found")
+    public static let alreadyExists = Self(rawValue: "already_exists")
+    public static let failedPrecondition = Self(rawValue: "failed_precondition")
+    public static let unavailable = Self(rawValue: "unavailable")
+    public static let unsupported = Self(rawValue: "unsupported")
+    public static let permissionDenied = Self(rawValue: "permission_denied")
+    public static let timeout = Self(rawValue: "timeout")
+    public static let cancelled = Self(rawValue: "cancelled")
+    public static let resourceExhausted = Self(rawValue: "resource_exhausted")
+    public static let internalError = Self(rawValue: "internal")
+}
+
+public struct ContainerRuntimeFailure: Codable, Equatable, Sendable {
+    public var code: ContainerRuntimeErrorCode
+    public var message: String
+
+    public init(code: ContainerRuntimeErrorCode, message: String) {
+        self.code = code
+        self.message = message
+    }
+}
+
+public struct ContainerRuntimeCapabilities: Codable, Equatable, Sendable {
+    public var version: ContainerRuntimeVersion
+    public var methods: [ContainerRuntimeMethod]
+    public var features: [String]
+
+    public init(
+        version: ContainerRuntimeVersion = .current,
+        methods: [ContainerRuntimeMethod],
+        features: [String] = []
+    ) {
+        self.version = version
+        self.methods = methods
+        self.features = features
+    }
+}
diff --git a/macOS/GhostVMKit/Containers/ContainerRuntimeXPCProtocol.swift b/macOS/GhostVMKit/Containers/ContainerRuntimeXPCProtocol.swift
new file mode 100644
index 0000000..0407b49
--- /dev/null
+++ b/macOS/GhostVMKit/Containers/ContainerRuntimeXPCProtocol.swift
@@ -0,0 +1,45 @@
+import Foundation
+
+/// Raw XPC protocol shared by GhostVMHelper and its embedded container runtime.
+public enum ContainerRuntimeXPCProtocol {
+    public static let serviceName = "org.ghostvm.ghostvm.helper"
+    public static let version: UInt64 = 5
+    public static let builderImage = "ghcr.io/apple/container-builder-shim/builder:0.13.0"
+
+    public enum Operation {
+        public static let ping = "ping"
+        public static let build = "build"
+        public static let cancel = "cancel"
+        public static let resize = "resize"
+        public static let invoke = "invoke"
+        public static let attach = "attach"
+        public static let shutdown = "shutdown"
+        public static let ready = "ready"
+        public static let exit = "exit"
+    }
+
+    public enum Key {
+        public static let operation = "operation"
+        public static let version = "version"
+        public static let runIdentifier = "runIdentifier"
+        public static let arguments = "arguments"
+        public static let payload = "payload"
+        public static let descriptor = "descriptor"
+        public static let networkSerialization = "networkSerialization"
+        public static let ipv4Subnet = "ipv4Subnet"
+        public static let volumeRoot = "volumeRoot"
+        public static let imageRoot = "imageRoot"
+        public static let ipv4Address = "ipv4Address"
+        public static let ipv4Gateway = "ipv4Gateway"
+        public static let macAddress = "macAddress"
+        public static let mtu = "mtu"
+        public static let columns = "columns"
+        public static let rows = "rows"
+        public static let stdin = "stdin"
+        public static let stdout = "stdout"
+        public static let stderr = "stderr"
+        public static let exitCode = "exitCode"
+        public static let error = "error"
+        public static let ok = "ok"
+    }
+}
diff --git a/macOS/GhostVMKit/Containers/GhostboxDirectProtocol.swift b/macOS/GhostVMKit/Containers/GhostboxDirectProtocol.swift
new file mode 100644
index 0000000..6869168
--- /dev/null
+++ b/macOS/GhostVMKit/Containers/GhostboxDirectProtocol.swift
@@ -0,0 +1,556 @@
+import Foundation
+
+public enum GhostboxDirectLimits {
+    public static let bytePayloadBytes = 1024 * 1024
+    public static let responseLineBytes = 2 * 1024 * 1024
+    public static let ioFrameDataBytes = 64 * 1024
+    public static let ioFrameLineBytes = 128 * 1024
+}
+
+public struct GhostboxDirectMethod: RawRepresentable, Codable, Hashable, Sendable {
+    public let rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+
+    public static let dnsCreate = Self(rawValue: "dns.create")
+    public static let dnsDefaultNameservers = Self(rawValue: "dns.defaultNameservers")
+    public static let dnsValidate = Self(rawValue: "dns.validate")
+    public static let dnsResolvConf = Self(rawValue: "dns.resolvConf")
+    public static let dnsNameservers = Self(rawValue: "dns.nameservers")
+    public static let dnsDomain = Self(rawValue: "dns.domain")
+    public static let dnsSearchDomains = Self(rawValue: "dns.searchDomains")
+    public static let dnsOptions = Self(rawValue: "dns.options")
+    public static let dnsDelete = Self(rawValue: "dns.delete")
+    public static let processConfigDefaultPath = Self(rawValue: "processConfig.defaultPath")
+    public static let processConfigDelete = Self(rawValue: "processConfig.delete")
+    public static let networkDelete = Self(rawValue: "network.delete")
+    public static let managerClose = Self(rawValue: "manager.close")
+    public static let mountGuestShare = Self(rawValue: "mount.guestShare")
+    public static let mountDelete = Self(rawValue: "mount.delete")
+    public static let volumeCreate = Self(rawValue: "volume.create")
+    public static let volumeList = Self(rawValue: "volume.list")
+    public static let volumeInspect = Self(rawValue: "volume.inspect")
+    public static let volumeMount = Self(rawValue: "volume.mount")
+    public static let volumeDelete = Self(rawValue: "volume.delete")
+    public static let containerDefaultMaskedPaths = Self(rawValue: "container.defaultMaskedPaths")
+    public static let containerDefaultReadonlyPaths = Self(rawValue: "container.defaultReadonlyPaths")
+    public static let containerDefaultCopyChunkSize = Self(rawValue: "container.defaultCopyChunkSize")
+    public static let containerMaxIDLength = Self(rawValue: "container.maxIDLength")
+    public static let kernelDefault = Self(rawValue: "kernel.default")
+    public static let kernelInstallRecommended = Self(rawValue: "kernel.installRecommended")
+    public static let readerStreamCreateProxy = Self(rawValue: "readerStream.createProxy")
+    public static let readerStreamAttachProxy = Self(rawValue: "readerStream.attachProxy")
+    public static let readerStreamCloseProxy = Self(rawValue: "readerStream.closeProxy")
+    public static let writerCreateProxy = Self(rawValue: "writer.createProxy")
+    public static let writerAttachProxy = Self(rawValue: "writer.attachProxy")
+    public static let writerCloseProxy = Self(rawValue: "writer.closeProxy")
+    public static let terminalCreateProxy = Self(rawValue: "terminal.createProxy")
+    public static let terminalAttachProxy = Self(rawValue: "terminal.attachProxy")
+    public static let terminalWaitAttachedProxy = Self(rawValue: "terminal.waitAttachedProxy")
+    public static let terminalCloseProxy = Self(rawValue: "terminal.closeProxy")
+}
+
+public enum GhostboxIOStream: String, Codable, Equatable, Sendable {
+    case input
+    case output
+    case terminal
+}
+
+public enum GhostboxIOFrameType: String, Codable, Equatable, Sendable {
+    case data
+    case eof
+    case resize
+    case error
+}
+
+public struct GhostboxIOFrame: Codable, Equatable, Sendable {
+    public var version: Int
+    public var type: GhostboxIOFrameType
+    public var stream: GhostboxIOStream?
+    public var data: Data?
+    public var columns: UInt16?
+    public var rows: UInt16?
+    public var message: String?
+
+    public init(
+        version: Int = ContainerBridgeConstants.protocolVersion,
+        type: GhostboxIOFrameType,
+        stream: GhostboxIOStream? = nil,
+        data: Data? = nil,
+        columns: UInt16? = nil,
+        rows: UInt16? = nil,
+        message: String? = nil
+    ) {
+        self.version = version
+        self.type = type
+        self.stream = stream
+        self.data = data
+        self.columns = columns
+        self.rows = rows
+        self.message = message
+    }
+
+    public static func data(_ data: Data, stream: GhostboxIOStream) -> Self {
+        Self(type: .data, stream: stream, data: data)
+    }
+
+    public static func eof(_ stream: GhostboxIOStream) -> Self {
+        Self(type: .eof, stream: stream)
+    }
+
+    public static func resize(columns: UInt16, rows: UInt16) -> Self {
+        Self(type: .resize, stream: .terminal, columns: columns, rows: rows)
+    }
+
+    public static func error(_ message: String) -> Self {
+        Self(type: .error, message: message)
+    }
+
+    public func validate() throws {
+        guard version == ContainerBridgeConstants.protocolVersion else {
+            throw ContainerProtocolError.malformedRequest("unsupported I/O frame version")
+        }
+        switch type {
+        case .data:
+            guard let stream, let data, !data.isEmpty,
+                  data.count <= GhostboxDirectLimits.ioFrameDataBytes,
+                  columns == nil, rows == nil, message == nil else {
+                throw ContainerProtocolError.malformedRequest("malformed I/O data frame")
+            }
+            _ = stream
+        case .eof:
+            guard stream != nil, data == nil, columns == nil, rows == nil, message == nil else {
+                throw ContainerProtocolError.malformedRequest("malformed I/O EOF frame")
+            }
+        case .resize:
+            guard stream == .terminal, data == nil, message == nil,
+                  let columns, columns > 0, let rows, rows > 0 else {
+                throw ContainerProtocolError.malformedRequest("malformed I/O resize frame")
+            }
+        case .error:
+            guard stream == nil, data == nil, columns == nil, rows == nil,
+                  let message, !message.isEmpty, message.utf8.count <= 4096 else {
+                throw ContainerProtocolError.malformedRequest("malformed I/O error frame")
+            }
+        }
+    }
+
+    public static func decode(line: Data) throws -> Self {
+        guard !line.isEmpty, line.count <= GhostboxDirectLimits.ioFrameLineBytes else {
+            throw ContainerProtocolError.malformedRequest("invalid I/O frame length")
+        }
+        do {
+            let frame = try JSONDecoder().decode(Self.self, from: line)
+            try frame.validate()
+            return frame
+        } catch let error as ContainerProtocolError {
+            throw error
+        } catch {
+            throw ContainerProtocolError.malformedRequest("invalid I/O frame: \(error)")
+        }
+    }
+
+    public func encodeLine() throws -> Data {
+        try validate()
+        var encoded = try JSONEncoder().encode(self)
+        guard encoded.count <= GhostboxDirectLimits.ioFrameLineBytes else {
+            throw ContainerProtocolError.requestTooLarge(limit: GhostboxDirectLimits.ioFrameLineBytes)
+        }
+        encoded.append(0x0A)
+        return encoded
+    }
+}
+
+public indirect enum GhostboxJSONValue: Codable, Equatable, Sendable {
+    case null
+    case boolean(Bool)
+    case string(String)
+    case integer(Int64)
+    case unsignedInteger(UInt64)
+    case array([GhostboxJSONValue])
+    case object([String: GhostboxJSONValue])
+
+    private static let unsignedIntegerTag = "$uint64"
+
+    public init(from decoder: Decoder) throws {
+        let single = try decoder.singleValueContainer()
+        if single.decodeNil() {
+            self = .null
+            return
+        }
+        if let value = try? single.decode(Bool.self) {
+            self = .boolean(value)
+            return
+        }
+        if let value = try? single.decode(String.self) {
+            self = .string(value)
+            return
+        }
+        if let value = try? single.decode(Int64.self) {
+            self = .integer(value)
+            return
+        }
+        if let value = try? single.decode(UInt64.self) {
+            self = .unsignedInteger(value)
+            return
+        }
+        if var container = try? decoder.unkeyedContainer() {
+            var values: [GhostboxJSONValue] = []
+            while !container.isAtEnd {
+                try values.append(container.decode(GhostboxJSONValue.self))
+            }
+            self = .array(values)
+            return
+        }
+
+        let container = try decoder.container(keyedBy: GhostboxJSONCodingKey.self)
+        if container.contains(GhostboxJSONCodingKey(Self.unsignedIntegerTag)) {
+            guard container.allKeys.count == 1 else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: GhostboxJSONCodingKey(Self.unsignedIntegerTag),
+                    in: container,
+                    debugDescription: "\(Self.unsignedIntegerTag) must be the only key in a tagged unsigned integer"
+                )
+            }
+            let encoded = try container.decode(String.self, forKey: GhostboxJSONCodingKey(Self.unsignedIntegerTag))
+            guard ghostboxIsCanonicalUnsignedInteger(encoded), let value = UInt64(encoded) else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: GhostboxJSONCodingKey(Self.unsignedIntegerTag),
+                    in: container,
+                    debugDescription: "\(Self.unsignedIntegerTag) must contain a canonical UInt64 decimal string"
+                )
+            }
+            self = .unsignedInteger(value)
+            return
+        }
+
+        self = .object(try Dictionary(uniqueKeysWithValues: container.allKeys.map { key in
+            (key.stringValue, try container.decode(GhostboxJSONValue.self, forKey: key))
+        }))
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        switch self {
+        case .null:
+            var container = encoder.singleValueContainer()
+            try container.encodeNil()
+        case .boolean(let value):
+            var container = encoder.singleValueContainer()
+            try container.encode(value)
+        case .string(let value):
+            var container = encoder.singleValueContainer()
+            try container.encode(value)
+        case .integer(let value):
+            var container = encoder.singleValueContainer()
+            try container.encode(value)
+        case .unsignedInteger(let value):
+            var container = encoder.container(keyedBy: GhostboxJSONCodingKey.self)
+            try container.encode(String(value), forKey: GhostboxJSONCodingKey(Self.unsignedIntegerTag))
+        case .array(let values):
+            var container = encoder.unkeyedContainer()
+            for value in values {
+                try container.encode(value)
+            }
+        case .object(let values):
+            var container = encoder.container(keyedBy: GhostboxJSONCodingKey.self)
+            for (key, value) in values {
+                try container.encode(value, forKey: GhostboxJSONCodingKey(key))
+            }
+        }
+    }
+}
+
+private struct GhostboxJSONCodingKey: CodingKey, Hashable {
+    let stringValue: String
+    let intValue: Int? = nil
+
+    init(_ stringValue: String) {
+        self.stringValue = stringValue
+    }
+
+    init?(stringValue: String) {
+        self.init(stringValue)
+    }
+
+    init?(intValue: Int) {
+        return nil
+    }
+}
+
+private func ghostboxIsCanonicalUnsignedInteger(_ value: String) -> Bool {
+    guard !value.isEmpty else { return false }
+    if value == "0" { return true }
+    guard value.first != "0" else { return false }
+    return value.utf8.allSatisfy { (0x30...0x39).contains($0) }
+}
+
+public struct GhostboxDirectRequest: Codable, Equatable, Sendable {
+    public var version: Int
+    public var operation: String
+    public var id: String
+    public var method: GhostboxDirectMethod
+    public var parameters: [String: GhostboxJSONValue]
+
+    public init(
+        version: Int = ContainerBridgeConstants.protocolVersion,
+        id: String = UUID().uuidString.lowercased(),
+        method: GhostboxDirectMethod,
+        parameters: [String: GhostboxJSONValue] = [:]
+    ) {
+        self.version = version
+        self.operation = "direct"
+        self.id = id
+        self.method = method
+        self.parameters = parameters
+    }
+
+    public static func decode(line: Data) throws -> GhostboxDirectRequest {
+        guard !line.isEmpty else { throw ContainerProtocolError.emptyRequest }
+        guard line.count <= ContainerBridgeConstants.maxRequestLineBytes else {
+            throw ContainerProtocolError.requestTooLarge(limit: ContainerBridgeConstants.maxRequestLineBytes)
+        }
+        do {
+            let request = try JSONDecoder().decode(GhostboxDirectRequest.self, from: line)
+            try request.validate()
+            return request
+        } catch let error as ContainerProtocolError {
+            throw error
+        } catch {
+            throw ContainerProtocolError.malformedRequest(String(describing: error))
+        }
+    }
+
+    public func validate() throws {
+        guard version == ContainerBridgeConstants.protocolVersion,
+              operation == "direct",
+              !id.isEmpty,
+              !method.rawValue.isEmpty else {
+            throw ContainerProtocolError.malformedRequest("invalid direct request envelope")
+        }
+    }
+}
+
+public struct GhostboxDirectRequestEnvelope: Codable, Equatable, Sendable {
+    public var version: Int
+    public var operation: String
+    public var id: String
+    public var method: GhostboxDirectMethod
+
+    public init(version: Int, operation: String, id: String, method: GhostboxDirectMethod) {
+        self.version = version
+        self.operation = operation
+        self.id = id
+        self.method = method
+    }
+}
+
+public struct GhostboxDirectValue: Codable, Equatable, Sendable {
+    private enum Storage: Equatable, Sendable {
+        case json(GhostboxJSONValue)
+        case reference(String)
+        case references([String])
+        case bytes(Data)
+        case void
+    }
+
+    private let storage: Storage
+
+    private init(storage: Storage) {
+        self.storage = storage
+    }
+
+    public var jsonValue: GhostboxJSONValue? {
+        guard case .json(let value) = storage else { return nil }
+        return value
+    }
+
+    public var referenceValue: String? {
+        guard case .reference(let value) = storage else { return nil }
+        return value
+    }
+
+    public var referencesValue: [String]? {
+        guard case .references(let value) = storage else { return nil }
+        return value
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case type
+        case value
+    }
+
+    private enum Kind: String, Codable {
+        case null
+        case boolean
+        case string
+        case integer
+        case unsignedInteger = "unsigned_integer"
+        case array
+        case object
+        case reference
+        case references
+        case bytes
+        case void
+    }
+
+    public static var null: Self { Self(storage: .json(.null)) }
+    public static func boolean(_ value: Bool) -> Self { Self(storage: .json(.boolean(value))) }
+    public static func string(_ value: String) -> Self { Self(storage: .json(.string(value))) }
+    public static func integer(_ value: Int64) -> Self { Self(storage: .json(.integer(value))) }
+    public static func unsignedInteger(_ value: UInt64) -> Self { Self(storage: .json(.unsignedInteger(value))) }
+    public static func array(_ value: [GhostboxDirectValue]) -> Self {
+        Self(storage: .json(.array(value.map(\.jsonRepresentation))))
+    }
+    public static func object(_ value: [String: GhostboxDirectValue]) -> Self {
+        Self(storage: .json(.object(value.mapValues(\.jsonRepresentation))))
+    }
+    public static func strings(_ value: [String]) -> Self {
+        Self(storage: .json(.array(value.map(GhostboxJSONValue.string))))
+    }
+    public static func reference(_ value: String) -> Self { Self(storage: .reference(value)) }
+    public static func references(_ value: [String]) -> Self { Self(storage: .references(value)) }
+    public static func bytes(_ value: Data) -> Self { Self(storage: .bytes(value)) }
+    public static var void: Self { Self(storage: .void) }
+
+    private var jsonRepresentation: GhostboxJSONValue {
+        switch storage {
+        case .json(let value): return value
+        case .reference(let value): return .string(value)
+        case .references(let values): return .array(values.map(GhostboxJSONValue.string))
+        case .bytes(let value): return .object(["$bytes": .string(value.base64EncodedString())])
+        case .void: return .null
+        }
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let kind = try container.decode(Kind.self, forKey: .type)
+        let requiresValue = kind != .null && kind != .void
+        let rawContainer = try decoder.container(keyedBy: GhostboxJSONCodingKey.self)
+        let expectedKeys: Set = requiresValue ? ["type", "value"] : ["type"]
+        guard Set(rawContainer.allKeys.map(\.stringValue)) == expectedKeys else {
+            throw DecodingError.dataCorruptedError(
+                forKey: .type,
+                in: container,
+                debugDescription: "malformed tagged direct value"
+            )
+        }
+
+        switch kind {
+        case .null: storage = .json(.null)
+        case .boolean: storage = .json(.boolean(try container.decode(Bool.self, forKey: .value)))
+        case .string: storage = .json(.string(try container.decode(String.self, forKey: .value)))
+        case .integer: storage = .json(.integer(try container.decode(Int64.self, forKey: .value)))
+        case .unsignedInteger:
+            let encoded = try container.decode(String.self, forKey: .value)
+            guard ghostboxIsCanonicalUnsignedInteger(encoded), let value = UInt64(encoded) else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: .value,
+                    in: container,
+                    debugDescription: "unsigned_integer must contain a canonical UInt64 decimal string"
+                )
+            }
+            storage = .json(.unsignedInteger(value))
+        case .array: storage = .json(.array(try container.decode([GhostboxJSONValue].self, forKey: .value)))
+        case .object: storage = .json(.object(try container.decode([String: GhostboxJSONValue].self, forKey: .value)))
+        case .reference: storage = .reference(try container.decode(String.self, forKey: .value))
+        case .references: storage = .references(try container.decode([String].self, forKey: .value))
+        case .bytes:
+            let value = try container.decode(Data.self, forKey: .value)
+            guard value.count <= GhostboxDirectLimits.bytePayloadBytes else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: .value,
+                    in: container,
+                    debugDescription: "byte payload exceeds the \(GhostboxDirectLimits.bytePayloadBytes)-byte limit"
+                )
+            }
+            storage = .bytes(value)
+        case .void: storage = .void
+        }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        switch storage {
+        case .json(.null):
+            try container.encode(Kind.null, forKey: .type)
+        case .json(.boolean(let value)):
+            try container.encode(Kind.boolean, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.string(let value)):
+            try container.encode(Kind.string, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.integer(let value)):
+            try container.encode(Kind.integer, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.unsignedInteger(let value)):
+            try container.encode(Kind.unsignedInteger, forKey: .type)
+            try container.encode(String(value), forKey: .value)
+        case .json(.array(let value)):
+            try container.encode(Kind.array, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .json(.object(let value)):
+            try container.encode(Kind.object, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .reference(let value):
+            try container.encode(Kind.reference, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .references(let value):
+            try container.encode(Kind.references, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .bytes(let value):
+            guard value.count <= GhostboxDirectLimits.bytePayloadBytes else {
+                throw EncodingError.invalidValue(
+                    value,
+                    EncodingError.Context(codingPath: encoder.codingPath, debugDescription: "byte payload exceeds the \(GhostboxDirectLimits.bytePayloadBytes)-byte limit")
+                )
+            }
+            try container.encode(Kind.bytes, forKey: .type)
+            try container.encode(value, forKey: .value)
+        case .void:
+            try container.encode(Kind.void, forKey: .type)
+        }
+    }
+}
+
+public struct GhostboxDirectResponse: Codable, Equatable, Sendable {
+    public var version: Int
+    public var id: String
+    public var result: GhostboxDirectValue?
+    public var error: ContainerRuntimeFailure?
+
+    public init(
+        version: Int = ContainerBridgeConstants.protocolVersion,
+        id: String,
+        result: GhostboxDirectValue? = nil,
+        error: ContainerRuntimeFailure? = nil
+    ) {
+        self.version = version
+        self.id = id
+        self.result = result
+        self.error = error
+    }
+
+    public static func success(id: String, value: GhostboxDirectValue) -> GhostboxDirectResponse {
+        GhostboxDirectResponse(id: id, result: value)
+    }
+
+    public static func failure(
+        id: String,
+        code: ContainerRuntimeErrorCode,
+        message: String
+    ) -> GhostboxDirectResponse {
+        GhostboxDirectResponse(id: id, error: ContainerRuntimeFailure(code: code, message: message))
+    }
+
+    public func encodeLine() throws -> Data {
+        var data = try JSONEncoder().encode(self)
+        guard data.count <= GhostboxDirectLimits.responseLineBytes else {
+            throw ContainerProtocolError.requestTooLarge(limit: GhostboxDirectLimits.responseLineBytes)
+        }
+        data.append(0x0A)
+        return data
+    }
+}
diff --git a/macOS/GhostVMKit/Content/ContentAddressedStore.swift b/macOS/GhostVMKit/Content/ContentAddressedStore.swift
new file mode 100644
index 0000000..6b20874
--- /dev/null
+++ b/macOS/GhostVMKit/Content/ContentAddressedStore.swift
@@ -0,0 +1,164 @@
+import CryptoKit
+import Foundation
+
+public enum ContentStoreError: Error, Equatable {
+    case unsupportedDigestAlgorithm(String)
+    case invalidDigest(String)
+    case digestMismatch(expected: ContentDigest, actual: ContentDigest)
+    case blobNotFound(ContentDigest)
+}
+
+/// OCI-style content digest, currently restricted to SHA-256.
+public struct ContentDigest: Codable, Hashable, Sendable, CustomStringConvertible {
+    public let algorithm: String
+    public let encoded: String
+
+    public init(algorithm: String, encoded: String) throws {
+        guard algorithm == "sha256" else {
+            throw ContentStoreError.unsupportedDigestAlgorithm(algorithm)
+        }
+        let lowercaseHex = CharacterSet(charactersIn: "0123456789abcdef")
+        guard encoded.count == 64, encoded.unicodeScalars.allSatisfy(lowercaseHex.contains) else {
+            throw ContentStoreError.invalidDigest("\(algorithm):\(encoded)")
+        }
+        self.algorithm = algorithm
+        self.encoded = encoded
+    }
+
+    public init(_ value: String) throws {
+        let parts = value.split(separator: ":", maxSplits: 1, omittingEmptySubsequences: false)
+        guard parts.count == 2 else {
+            throw ContentStoreError.invalidDigest(value)
+        }
+        try self.init(algorithm: String(parts[0]), encoded: String(parts[1]))
+    }
+
+    public var description: String {
+        "\(algorithm):\(encoded)"
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        try self.init(container.decode(String.self))
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(description)
+    }
+
+    public static func sha256(_ data: Data) -> ContentDigest {
+        let encoded = SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
+        return try! ContentDigest(algorithm: "sha256", encoded: encoded)
+    }
+}
+
+/// On-disk locations for immutable blobs and mutable image metadata.
+public struct ContentStoreLayout: Sendable {
+    public let rootURL: URL
+
+    public init(rootURL: URL) {
+        self.rootURL = rootURL
+    }
+
+    public var blobsURL: URL { rootURL.appendingPathComponent("blobs", isDirectory: true) }
+    public var ingestURL: URL { rootURL.appendingPathComponent("ingest", isDirectory: true) }
+    public var referencesURL: URL { rootURL.appendingPathComponent("refs", isDirectory: true) }
+    public var snapshotsURL: URL { rootURL.appendingPathComponent("snapshots", isDirectory: true) }
+
+    public func blobURL(for digest: ContentDigest) -> URL {
+        blobsURL
+            .appendingPathComponent(digest.algorithm, isDirectory: true)
+            .appendingPathComponent(digest.encoded, isDirectory: false)
+    }
+}
+
+/// Append-only content store. Publication is a same-volume rename from ingest
+/// into the digest path, so readers never observe a partial blob.
+public actor ContentAddressedStore {
+    public let layout: ContentStoreLayout
+
+    private let fileManager: FileManager
+
+    public init(rootURL: URL, fileManager: FileManager = .default) {
+        self.layout = ContentStoreLayout(rootURL: rootURL)
+        self.fileManager = fileManager
+    }
+
+    public func prepare() throws {
+        try fileManager.createDirectory(at: layout.blobsURL, withIntermediateDirectories: true)
+        try fileManager.createDirectory(at: layout.ingestURL, withIntermediateDirectories: true)
+        try fileManager.createDirectory(at: layout.referencesURL, withIntermediateDirectories: true)
+        try fileManager.createDirectory(at: layout.snapshotsURL, withIntermediateDirectories: true)
+    }
+
+    @discardableResult
+    public func put(_ data: Data) throws -> ContentDigest {
+        try prepare()
+        let digest = ContentDigest.sha256(data)
+        let temporaryURL = layout.ingestURL.appendingPathComponent(UUID().uuidString.lowercased())
+        try data.write(to: temporaryURL)
+        _ = try publish(temporaryURL: temporaryURL, expectedDigest: digest)
+        return digest
+    }
+
+    /// Copies an external download into ingest, verifies it, then publishes it.
+    @discardableResult
+    public func importBlob(at sourceURL: URL, expectedDigest: ContentDigest) throws -> URL {
+        try prepare()
+        let temporaryURL = layout.ingestURL.appendingPathComponent(UUID().uuidString.lowercased())
+        try fileManager.copyItem(at: sourceURL, to: temporaryURL)
+        return try publish(temporaryURL: temporaryURL, expectedDigest: expectedDigest)
+    }
+
+    public func contains(_ digest: ContentDigest) -> Bool {
+        fileManager.fileExists(atPath: layout.blobURL(for: digest).path)
+    }
+
+    public func blobURL(for digest: ContentDigest) throws -> URL {
+        let url = layout.blobURL(for: digest)
+        guard fileManager.fileExists(atPath: url.path) else {
+            throw ContentStoreError.blobNotFound(digest)
+        }
+        return url
+    }
+
+    private func publish(temporaryURL: URL, expectedDigest: ContentDigest) throws -> URL {
+        var shouldRemoveTemporary = true
+        defer {
+            if shouldRemoveTemporary {
+                try? fileManager.removeItem(at: temporaryURL)
+            }
+        }
+
+        let actualDigest = try Self.sha256(of: temporaryURL)
+        guard actualDigest == expectedDigest else {
+            throw ContentStoreError.digestMismatch(expected: expectedDigest, actual: actualDigest)
+        }
+
+        let destinationURL = layout.blobURL(for: actualDigest)
+        if fileManager.fileExists(atPath: destinationURL.path) {
+            return destinationURL
+        }
+
+        try fileManager.createDirectory(
+            at: destinationURL.deletingLastPathComponent(),
+            withIntermediateDirectories: true
+        )
+        try fileManager.moveItem(at: temporaryURL, to: destinationURL)
+        shouldRemoveTemporary = false
+        return destinationURL
+    }
+
+    private static func sha256(of url: URL) throws -> ContentDigest {
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+
+        var hasher = SHA256()
+        while let chunk = try handle.read(upToCount: 1024 * 1024), !chunk.isEmpty {
+            hasher.update(data: chunk)
+        }
+        let encoded = hasher.finalize().map { String(format: "%02x", $0) }.joined()
+        return try ContentDigest(algorithm: "sha256", encoded: encoded)
+    }
+}
diff --git a/macOS/GhostVMKit/Core/GhostClientProtocol.swift b/macOS/GhostVMKit/Core/GhostClientProtocol.swift
index 56f0f62..e009176 100644
--- a/macOS/GhostVMKit/Core/GhostClientProtocol.swift
+++ b/macOS/GhostVMKit/Core/GhostClientProtocol.swift
@@ -2,7 +2,7 @@ import Foundation
 
 /// Protocol for communicating with GhostTools running in the guest VM.
 /// Enables mock injection for testing services that depend on guest communication.
-public protocol GhostClientProtocol {
+public protocol GhostClientProtocol: AnyObject {
     func getClipboard() async throws -> ClipboardGetResponse
     func setClipboard(data: Data, type: String) async throws
     func sendFile(fileURL: URL, relativePath: String?, batchID: String?, isLastInBatch: Bool, permissions: Int?, progressHandler: ((Double) -> Void)?) async throws -> String
@@ -19,6 +19,16 @@ public protocol GhostClientProtocol {
 
     // File system
     func listDirectory(path: String) async throws -> FSListResponse
+    func fileMetadata(path: String) async throws -> GuestFileMetadata
+    func listDirectoryMetadata(path: String) async throws -> GuestDirectoryMetadata
+    func readFile(path: String, offset: UInt64, length: Int) async throws -> Data
+    func readSymbolicLink(path: String) async throws -> String
+    func createFileSystemItem(path: String, type: GuestFileCreateType, mode: UInt32) async throws -> GuestFileMetadata
+    func createSymbolicLink(path: String, destination: String) async throws -> GuestFileMetadata
+    func writeFile(path: String, offset: UInt64, data: Data) async throws -> GuestFileMetadata
+    func setFileAttributes(path: String, attributes: GuestFileAttributes) async throws -> GuestFileMetadata
+    func removeFileSystemItem(path: String) async throws
+    func renameFileSystemItem(path: String, destinationPath: String) async throws -> GuestFileMetadata
     func mkdir(path: String) async throws
     func deleteFile(path: String) async throws
     func moveFile(from: String, to: String) async throws
diff --git a/macOS/GhostVMKit/Core/GhostClientTypes.swift b/macOS/GhostVMKit/Core/GhostClientTypes.swift
index df9e5c9..186cd92 100644
--- a/macOS/GhostVMKit/Core/GhostClientTypes.swift
+++ b/macOS/GhostVMKit/Core/GhostClientTypes.swift
@@ -141,6 +141,121 @@ public struct FSListResponse: Codable {
     }
 }
 
+public enum GuestFileType: String, Codable, Equatable, Sendable {
+    case file
+    case directory
+    case symbolicLink
+    case other
+}
+
+public struct GuestFileMetadata: Codable, Equatable, Sendable {
+    public let name: String
+    public let type: GuestFileType
+    public let size: UInt64
+    public let mode: UInt32
+    public let uid: UInt32
+    public let gid: UInt32
+    public let inode: UInt64
+    public let device: UInt64
+    public let linkCount: UInt32
+    public let modifiedSeconds: Int
+    public let modifiedNanoseconds: Int32
+    public let accessedSeconds: Int?
+    public let accessedNanoseconds: Int32?
+    public let changedSeconds: Int?
+    public let changedNanoseconds: Int32?
+    public let birthSeconds: Int?
+    public let birthNanoseconds: Int32?
+
+    public init(
+        name: String,
+        type: GuestFileType,
+        size: UInt64,
+        mode: UInt32,
+        uid: UInt32,
+        gid: UInt32,
+        inode: UInt64,
+        device: UInt64,
+        linkCount: UInt32,
+        modifiedSeconds: Int,
+        modifiedNanoseconds: Int32,
+        accessedSeconds: Int? = nil,
+        accessedNanoseconds: Int32? = nil,
+        changedSeconds: Int? = nil,
+        changedNanoseconds: Int32? = nil,
+        birthSeconds: Int? = nil,
+        birthNanoseconds: Int32? = nil
+    ) {
+        self.name = name
+        self.type = type
+        self.size = size
+        self.mode = mode
+        self.uid = uid
+        self.gid = gid
+        self.inode = inode
+        self.device = device
+        self.linkCount = linkCount
+        self.modifiedSeconds = modifiedSeconds
+        self.modifiedNanoseconds = modifiedNanoseconds
+        self.accessedSeconds = accessedSeconds
+        self.accessedNanoseconds = accessedNanoseconds
+        self.changedSeconds = changedSeconds
+        self.changedNanoseconds = changedNanoseconds
+        self.birthSeconds = birthSeconds
+        self.birthNanoseconds = birthNanoseconds
+    }
+}
+
+public enum GuestFileCreateType: String, Codable, Equatable, Sendable {
+    case file
+    case directory
+}
+
+public struct GuestFileAttributes: Codable, Equatable, Sendable {
+    public let mode: UInt32?
+    public let size: UInt64?
+    public let modifiedSeconds: Int64?
+    public let modifiedNanoseconds: Int32?
+    public let accessedSeconds: Int64?
+    public let accessedNanoseconds: Int32?
+
+    public init(
+        mode: UInt32? = nil,
+        size: UInt64? = nil,
+        modifiedSeconds: Int64? = nil,
+        modifiedNanoseconds: Int32? = nil,
+        accessedSeconds: Int64? = nil,
+        accessedNanoseconds: Int32? = nil
+    ) {
+        self.mode = mode
+        self.size = size
+        self.modifiedSeconds = modifiedSeconds
+        self.modifiedNanoseconds = modifiedNanoseconds
+        self.accessedSeconds = accessedSeconds
+        self.accessedNanoseconds = accessedNanoseconds
+    }
+}
+
+public struct GuestFilesystemErrorPayload: Codable, Equatable, Sendable {
+    public let error: String
+    public let errno: Int32?
+
+    public init(error: String, errno: Int32? = nil) {
+        self.error = error
+        self.errno = errno
+    }
+}
+
+public struct GuestDirectoryMetadata: Codable, Equatable, Sendable {
+    public let path: String
+    public let entries: [GuestFileMetadata]
+
+    public init(path: String, entries: [GuestFileMetadata]) {
+        self.path = path
+        self.entries = entries
+    }
+}
+
 // MARK: - Accessibility Types
 
 /// Frame rectangle for accessibility elements
diff --git a/macOS/GhostVMKit/Core/NetworkConfig.swift b/macOS/GhostVMKit/Core/NetworkConfig.swift
index f63e9e6..46d6b25 100644
--- a/macOS/GhostVMKit/Core/NetworkConfig.swift
+++ b/macOS/GhostVMKit/Core/NetworkConfig.swift
@@ -8,10 +8,16 @@ public enum NetworkMode: String, Codable {
 public struct NetworkConfig: Codable, Equatable {
     public var mode: NetworkMode
     public var bridgeInterfaceIdentifier: String?
+    public var vmnetIPv4Subnet: String?
 
-    public init(mode: NetworkMode = .nat, bridgeInterfaceIdentifier: String? = nil) {
+    public init(
+        mode: NetworkMode = .nat,
+        bridgeInterfaceIdentifier: String? = nil,
+        vmnetIPv4Subnet: String? = nil
+    ) {
         self.mode = mode
         self.bridgeInterfaceIdentifier = bridgeInterfaceIdentifier
+        self.vmnetIPv4Subnet = vmnetIPv4Subnet
     }
 
     public static var defaultConfig: NetworkConfig {
diff --git a/macOS/GhostVMKit/Core/VMFileLayout.swift b/macOS/GhostVMKit/Core/VMFileLayout.swift
index 4bf5599..12847fc 100644
--- a/macOS/GhostVMKit/Core/VMFileLayout.swift
+++ b/macOS/GhostVMKit/Core/VMFileLayout.swift
@@ -17,6 +17,21 @@ public final class VMFileLayout {
     public var pidFileURL: URL { bundleURL.appendingPathComponent("vmctl.pid") }
     public var snapshotsDirectoryURL: URL { bundleURL.appendingPathComponent("Snapshots") }
     public var suspendStateURL: URL { bundleURL.appendingPathComponent("suspend.vzvmsave") }
+    public var containerRuntimeDirectoryURL: URL {
+        bundleURL.appendingPathComponent("Containers", isDirectory: true)
+    }
+    public var containerRuntimeMetadataURL: URL {
+        containerRuntimeDirectoryURL.appendingPathComponent("containers.json")
+    }
+    public var containerRuntimeImagesURL: URL {
+        containerRuntimeDirectoryURL.appendingPathComponent("images", isDirectory: true)
+    }
+    public var containerRuntimeLogsURL: URL {
+        containerRuntimeDirectoryURL.appendingPathComponent("logs", isDirectory: true)
+    }
+    public var containerRuntimeVolumesURL: URL {
+        containerRuntimeDirectoryURL.appendingPathComponent("volumes", isDirectory: true)
+    }
     // MARK: - Helper App Bundle
 
     /// Directory containing the helper app bundle
diff --git a/macOS/GhostVMKit/Core/VMStoredConfig.swift b/macOS/GhostVMKit/Core/VMStoredConfig.swift
index 31637c7..1366144 100644
--- a/macOS/GhostVMKit/Core/VMStoredConfig.swift
+++ b/macOS/GhostVMKit/Core/VMStoredConfig.swift
@@ -42,6 +42,8 @@ public struct VMStoredConfig: Codable {
     public var portForwards: [PortForwardConfig]
     // Network configuration (NAT vs bridged)
     public var networkConfig: NetworkConfig?
+    // Allows this VM to request host-backed containers.
+    public var hostContainersEnabled: Bool
     // Icon mode: nil = static (icon.png), "dynamic" = mirror guest foreground app
     public var iconMode: String?
     // Persisted VM window state
@@ -76,6 +78,7 @@ public struct VMStoredConfig: Codable {
         case macAddress
         case portForwards
         case networkConfig
+        case hostContainersEnabled
         case iconMode
         case windowWidth
         case windowHeight
@@ -109,6 +112,7 @@ public struct VMStoredConfig: Codable {
         macAddress: String? = nil,
         portForwards: [PortForwardConfig] = [],
         networkConfig: NetworkConfig? = nil,
+        hostContainersEnabled: Bool = false,
         iconMode: String? = nil,
         windowWidth: Double? = nil,
         windowHeight: Double? = nil,
@@ -140,6 +144,7 @@ public struct VMStoredConfig: Codable {
         self.macAddress = macAddress
         self.portForwards = portForwards
         self.networkConfig = networkConfig
+        self.hostContainersEnabled = hostContainersEnabled
         self.iconMode = iconMode
         self.windowWidth = windowWidth
         self.windowHeight = windowHeight
@@ -175,6 +180,7 @@ public struct VMStoredConfig: Codable {
         // Port forwards - defaults to empty for backwards compatibility
         portForwards = try container.decodeIfPresent([PortForwardConfig].self, forKey: .portForwards) ?? []
         networkConfig = try container.decodeIfPresent(NetworkConfig.self, forKey: .networkConfig)
+        hostContainersEnabled = try container.decodeIfPresent(Bool.self, forKey: .hostContainersEnabled) ?? false
         iconMode = try container.decodeIfPresent(String.self, forKey: .iconMode)
         windowWidth = try container.decodeIfPresent(Double.self, forKey: .windowWidth)
         windowHeight = try container.decodeIfPresent(Double.self, forKey: .windowHeight)
diff --git a/macOS/GhostVMKit/Networking/NetworkManager.swift b/macOS/GhostVMKit/Networking/NetworkManager.swift
new file mode 100644
index 0000000..a9e7162
--- /dev/null
+++ b/macOS/GhostVMKit/Networking/NetworkManager.swift
@@ -0,0 +1,140 @@
+import Foundation
+
+/// Identifies a network independently of the backend that implements it.
+public struct ManagedNetworkID: RawRepresentable, Codable, Hashable, Sendable {
+    public let rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
+}
+
+/// Host networking implementations available to VM and container workloads.
+public enum ManagedNetworkDriver: String, Codable, Sendable {
+    /// Virtualization.framework's per-VM NAT attachment.
+    case virtualizationNAT = "virtualization-nat"
+    /// A direct attachment to a host interface.
+    case bridged
+    /// A shared vmnet network with centrally managed addresses.
+    case vmnetShared = "vmnet-shared"
+}
+
+/// Backend-neutral network configuration owned by the runtime helper.
+public struct ManagedNetwork: Codable, Equatable, Sendable {
+    public var id: ManagedNetworkID
+    public var name: String
+    public var driver: ManagedNetworkDriver
+    public var ipv4Subnet: String?
+    public var gateway: String?
+    public var bridgeInterfaceIdentifier: String?
+
+    public init(
+        id: ManagedNetworkID,
+        name: String,
+        driver: ManagedNetworkDriver,
+        ipv4Subnet: String? = nil,
+        gateway: String? = nil,
+        bridgeInterfaceIdentifier: String? = nil
+    ) {
+        self.id = id
+        self.name = name
+        self.driver = driver
+        self.ipv4Subnet = ipv4Subnet
+        self.gateway = gateway
+        self.bridgeInterfaceIdentifier = bridgeInterfaceIdentifier
+    }
+}
+
+public enum NetworkWorkloadKind: String, Codable, Hashable, Sendable {
+    case virtualMachine = "virtual-machine"
+    case container
+}
+
+/// A VM NIC or container interface attached to a managed network.
+public struct ManagedNetworkEndpoint: Codable, Equatable, Sendable, Identifiable {
+    public var id: UUID
+    public var networkID: ManagedNetworkID
+    public var workloadKind: NetworkWorkloadKind
+    public var workloadID: String
+    public var interfaceName: String?
+    public var macAddress: String?
+    public var ipv4Address: String?
+
+    public init(
+        id: UUID = UUID(),
+        networkID: ManagedNetworkID,
+        workloadKind: NetworkWorkloadKind,
+        workloadID: String,
+        interfaceName: String? = nil,
+        macAddress: String? = nil,
+        ipv4Address: String? = nil
+    ) {
+        self.id = id
+        self.networkID = networkID
+        self.workloadKind = workloadKind
+        self.workloadID = workloadID
+        self.interfaceName = interfaceName
+        self.macAddress = macAddress
+        self.ipv4Address = ipv4Address
+    }
+}
+
+public enum NetworkManagerError: Error, Equatable {
+    case networkAlreadyExists(ManagedNetworkID)
+    case networkNotFound(ManagedNetworkID)
+    case endpointAlreadyExists(UUID)
+}
+
+/// Single-owner control plane for VM and container network definitions.
+/// Concrete backends translate endpoints into VZ or Containerization interfaces.
+public actor NetworkManager {
+    private var networksByID: [ManagedNetworkID: ManagedNetwork]
+    private var endpointsByID: [UUID: ManagedNetworkEndpoint]
+
+    public init(networks: [ManagedNetwork] = []) {
+        self.networksByID = Dictionary(uniqueKeysWithValues: networks.map { ($0.id, $0) })
+        self.endpointsByID = [:]
+    }
+
+    public func networks() -> [ManagedNetwork] {
+        networksByID.values.sorted { $0.name.localizedStandardCompare($1.name) == .orderedAscending }
+    }
+
+    public func network(id: ManagedNetworkID) -> ManagedNetwork? {
+        networksByID[id]
+    }
+
+    public func create(_ network: ManagedNetwork) throws {
+        guard networksByID[network.id] == nil else {
+            throw NetworkManagerError.networkAlreadyExists(network.id)
+        }
+        networksByID[network.id] = network
+    }
+
+    public func remove(id: ManagedNetworkID) throws {
+        guard networksByID.removeValue(forKey: id) != nil else {
+            throw NetworkManagerError.networkNotFound(id)
+        }
+        endpointsByID = endpointsByID.filter { $0.value.networkID != id }
+    }
+
+    public func attach(_ endpoint: ManagedNetworkEndpoint) throws {
+        guard networksByID[endpoint.networkID] != nil else {
+            throw NetworkManagerError.networkNotFound(endpoint.networkID)
+        }
+        guard endpointsByID[endpoint.id] == nil else {
+            throw NetworkManagerError.endpointAlreadyExists(endpoint.id)
+        }
+        endpointsByID[endpoint.id] = endpoint
+    }
+
+    public func detach(endpointID: UUID) {
+        endpointsByID.removeValue(forKey: endpointID)
+    }
+
+    public func endpoints(networkID: ManagedNetworkID? = nil) -> [ManagedNetworkEndpoint] {
+        endpointsByID.values
+            .filter { networkID == nil || $0.networkID == networkID }
+            .sorted { $0.id.uuidString < $1.id.uuidString }
+    }
+}
diff --git a/macOS/GhostVMKit/Networking/SharedVmnetIPv4Pool.swift b/macOS/GhostVMKit/Networking/SharedVmnetIPv4Pool.swift
new file mode 100644
index 0000000..339fb49
--- /dev/null
+++ b/macOS/GhostVMKit/Networking/SharedVmnetIPv4Pool.swift
@@ -0,0 +1,55 @@
+import Foundation
+
+public enum SharedVmnetIPv4PoolError: Error, Equatable {
+    case exhausted
+}
+
+/// Deterministic first-fit allocator for the static container range of a
+/// shared vmnet subnet. The gateway (.1) and macOS DHCP lease (.2) are skipped.
+public struct SharedVmnetIPv4Pool {
+    public let subnet: UInt32
+    public let mask: UInt32
+    public let prefixLength: UInt64
+    private var allocations: [String: UInt32] = [:]
+
+    public init(subnet: UInt32, mask: UInt32, prefixLength: UInt64) {
+        self.subnet = subnet & mask
+        self.mask = mask
+        self.prefixLength = prefixLength
+    }
+
+    public mutating func allocate(endpointIdentifier: String) throws -> UInt32 {
+        if let existing = allocations[endpointIdentifier] { return existing }
+        let broadcast = subnet | ~mask
+        let span = broadcast - subnet
+        guard span > 3 else { throw SharedVmnetIPv4PoolError.exhausted }
+
+        let used = Set(allocations.values)
+        // The upper half is reserved for direct Ghostbox container sessions,
+        // whose allocator lives in the runtime XPC process.
+        let upperBound = subnet + (span / 2) + (span % 2)
+        for address in (subnet + 3).. String {
+        "\((address >> 24) & 0xff).\((address >> 16) & 0xff).\((address >> 8) & 0xff).\(address & 0xff)"
+    }
+
+    public static func macAddress(for address: UInt32) -> String {
+        String(
+            format: "02:00:%02x:%02x:%02x:%02x",
+            (address >> 24) & 0xff,
+            (address >> 16) & 0xff,
+            (address >> 8) & 0xff,
+            address & 0xff
+        )
+    }
+}
diff --git a/macOS/GhostVMKit/Networking/SharedVmnetNetwork.swift b/macOS/GhostVMKit/Networking/SharedVmnetNetwork.swift
new file mode 100644
index 0000000..9ab304d
--- /dev/null
+++ b/macOS/GhostVMKit/Networking/SharedVmnetNetwork.swift
@@ -0,0 +1,264 @@
+import Foundation
+import Virtualization
+import XPC
+import vmnet
+
+public enum SharedVmnetError: Error, LocalizedError {
+    case invalidMACAddress(String)
+    case networkCreationFailed(vmnet_return_t)
+    case serializationFailed(vmnet_return_t)
+    case networkClosed
+
+    public var errorDescription: String? {
+        switch self {
+        case .invalidMACAddress(let address):
+            return "Invalid MAC address for shared vmnet network: \(address)"
+        case .networkCreationFailed(let status):
+            return "Failed to create shared vmnet network (status \(status.rawValue))."
+        case .serializationFailed(let status):
+            return "Failed to serialize shared vmnet network (status \(status.rawValue))."
+        case .networkClosed:
+            return "The shared vmnet network is closed."
+        }
+    }
+}
+
+/// Owns the shared-mode vmnet network used by one NAT macOS VM and allocates
+/// endpoint settings for container VMs hosted by the runtime XPC service.
+public final class SharedVmnetNetwork: @unchecked Sendable {
+    public let networkIdentifier: String
+    public let networkReference: vmnet_network_ref
+    public let serialization: xpc_object_t
+    public let ipv4Subnet: String
+    public let ipv4Gateway: String
+
+    private let lock = NSLock()
+    private var pool: SharedVmnetIPv4Pool
+    private var closed = false
+
+    public init(networkIdentifier: String, vmMACAddress: String, preferredIPv4Subnet: String? = nil) throws {
+        let macBytes = try Self.parseMACAddress(vmMACAddress)
+        let created = try Self.createNetwork(
+            vmMACAddress: macBytes,
+            preferredSubnetOctet: Self.subnetOctet(from: preferredIPv4Subnet)
+        )
+
+        var status: vmnet_return_t = .VMNET_FAILURE
+        guard let serialization = vmnet_network_copy_serialization(created.reference, &status), status == .VMNET_SUCCESS else {
+            Self.releaseVmnetReference(created.reference)
+            throw SharedVmnetError.serializationFailed(status)
+        }
+
+        self.networkIdentifier = networkIdentifier
+        self.networkReference = created.reference
+        self.serialization = serialization
+        self.ipv4Subnet = "\(created.subnetString)/\(created.prefixLength)"
+        self.ipv4Gateway = created.gateway
+        self.pool = SharedVmnetIPv4Pool(
+            subnet: created.subnet,
+            mask: created.mask,
+            prefixLength: created.prefixLength
+        )
+    }
+
+    public var attachment: VZVmnetNetworkDeviceAttachment {
+        VZVmnetNetworkDeviceAttachment(network: networkReference)
+    }
+
+    public func acquireEndpoint(identifier: String) throws -> SharedVmnetEndpointLease {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !closed else { throw SharedVmnetError.networkClosed }
+        let address = try pool.allocate(endpointIdentifier: identifier)
+        return SharedVmnetEndpointLease(
+            owner: self,
+            endpointIdentifier: identifier,
+            serialization: serialization,
+            ipv4Address: "\(SharedVmnetIPv4Pool.string(for: address))/\(pool.prefixLength)",
+            ipv4Gateway: ipv4Gateway,
+            macAddress: Self.macAddress(networkIdentifier: networkIdentifier, endpointIdentifier: identifier),
+            mtu: 1500
+        )
+    }
+
+    public func close() {
+        lock.lock()
+        guard !closed else {
+            lock.unlock()
+            return
+        }
+        closed = true
+        lock.unlock()
+        Self.releaseVmnetReference(networkReference)
+    }
+
+    deinit {
+        close()
+    }
+
+    private struct CreatedNetwork {
+        let reference: vmnet_network_ref
+        let subnet: UInt32
+        let mask: UInt32
+        let prefixLength: UInt64
+        let subnetString: String
+        let gateway: String
+    }
+
+    private static func createNetwork(vmMACAddress: [UInt8], preferredSubnetOctet: UInt8?) throws -> CreatedNetwork {
+        var lastStatus: vmnet_return_t = .VMNET_FAILURE
+        var candidates: [UInt8] = preferredSubnetOctet.map { [$0] } ?? []
+        while candidates.count < 64 {
+            let candidate = UInt8.random(in: 1...254)
+            if !candidates.contains(candidate) { candidates.append(candidate) }
+        }
+
+        // vmnet reserves the configured subnet atomically. Retry random /24s
+        // so concurrently running GhostVM instances cannot collide.
+        for octet in candidates {
+            var status: vmnet_return_t = .VMNET_FAILURE
+            guard let configuration = vmnet_network_configuration_create(.VMNET_SHARED_MODE, &status) else {
+                throw SharedVmnetError.networkCreationFailed(status)
+            }
+
+            let gatewayString = "192.168.\(octet).1"
+            let vmAddressString = "192.168.\(octet).2"
+            var gatewayAddress = in_addr()
+            var mask = in_addr()
+            var vmAddress = in_addr()
+            _ = gatewayString.withCString { inet_pton(AF_INET, $0, &gatewayAddress) }
+            _ = "255.255.255.0".withCString { inet_pton(AF_INET, $0, &mask) }
+            _ = vmAddressString.withCString { inet_pton(AF_INET, $0, &vmAddress) }
+
+            // Despite its parameter name, vmnet expects the first host address,
+            // which becomes the shared-mode gateway, rather than the network address.
+            let subnetStatus = vmnet_network_configuration_set_ipv4_subnet(configuration, &gatewayAddress, &mask)
+            var mac = ether_addr(octet: (
+                vmMACAddress[0], vmMACAddress[1], vmMACAddress[2],
+                vmMACAddress[3], vmMACAddress[4], vmMACAddress[5]
+            ))
+            let reservationStatus = vmnet_network_configuration_add_dhcp_reservation(configuration, &mac, &vmAddress)
+
+            if subnetStatus == .VMNET_SUCCESS, reservationStatus == .VMNET_SUCCESS,
+               let reference = vmnet_network_create(configuration, &status), status == .VMNET_SUCCESS {
+                releaseVmnetReference(configuration)
+                var actualSubnet = in_addr()
+                var actualMask = in_addr()
+                vmnet_network_get_ipv4_subnet(reference, &actualSubnet, &actualMask)
+                let subnet = UInt32(bigEndian: actualSubnet.s_addr) & UInt32(bigEndian: actualMask.s_addr)
+                let maskValue = UInt32(bigEndian: actualMask.s_addr)
+                return CreatedNetwork(
+                    reference: reference,
+                    subnet: subnet,
+                    mask: maskValue,
+                    prefixLength: UInt64(maskValue.nonzeroBitCount),
+                    subnetString: SharedVmnetIPv4Pool.string(for: subnet),
+                    gateway: SharedVmnetIPv4Pool.string(for: subnet + 1)
+                )
+            }
+
+            lastStatus = status
+            releaseVmnetReference(configuration)
+        }
+
+        throw SharedVmnetError.networkCreationFailed(lastStatus)
+    }
+
+    private static func parseMACAddress(_ address: String) throws -> [UInt8] {
+        let parts = address.split(separator: ":", omittingEmptySubsequences: false)
+        guard parts.count == 6 else { throw SharedVmnetError.invalidMACAddress(address) }
+        let bytes = parts.compactMap { UInt8($0, radix: 16) }
+        guard bytes.count == 6 else { throw SharedVmnetError.invalidMACAddress(address) }
+        return bytes
+    }
+
+    private static func subnetOctet(from subnet: String?) -> UInt8? {
+        guard let subnet else { return nil }
+        let components = subnet.split(separator: ".", omittingEmptySubsequences: false)
+        guard components.count == 4,
+              components[0] == "192",
+              components[1] == "168",
+              components[3] == "0/24",
+              let octet = UInt8(components[2]),
+              octet > 0,
+              octet < 255 else {
+            return nil
+        }
+        return octet
+    }
+
+    fileprivate func releaseEndpoint(identifier: String) {
+        lock.lock()
+        pool.release(endpointIdentifier: identifier)
+        lock.unlock()
+    }
+
+    private static func macAddress(networkIdentifier: String, endpointIdentifier: String) -> String {
+        var hash: UInt64 = 0xcbf29ce484222325
+        for byte in "\(networkIdentifier):\(endpointIdentifier)".utf8 {
+            hash ^= UInt64(byte)
+            hash &*= 0x100000001b3
+        }
+        let bytes: [UInt8] = [
+            0x02,
+            UInt8((hash >> 32) & 0xff),
+            UInt8((hash >> 24) & 0xff),
+            UInt8((hash >> 16) & 0xff),
+            UInt8((hash >> 8) & 0xff),
+            UInt8(hash & 0xff),
+        ]
+        return bytes.map { String(format: "%02x", $0) }.joined(separator: ":")
+    }
+
+    public static func releaseVmnetReference(_ reference: OpaquePointer) {
+        Unmanaged.fromOpaque(UnsafeRawPointer(reference)).release()
+    }
+}
+
+/// Helper-owned endpoint allocation. Its opaque network serialization is sent
+/// directly to the runtime service and the address is returned to IPAM on close.
+public final class SharedVmnetEndpointLease: @unchecked Sendable {
+    public let serialization: xpc_object_t
+    public let ipv4Address: String
+    public let ipv4Gateway: String
+    public let macAddress: String
+    public let mtu: UInt32
+
+    private let owner: SharedVmnetNetwork
+    private let endpointIdentifier: String
+    private let lock = NSLock()
+    private var closed = false
+
+    fileprivate init(
+        owner: SharedVmnetNetwork,
+        endpointIdentifier: String,
+        serialization: xpc_object_t,
+        ipv4Address: String,
+        ipv4Gateway: String,
+        macAddress: String,
+        mtu: UInt32
+    ) {
+        self.owner = owner
+        self.endpointIdentifier = endpointIdentifier
+        self.serialization = serialization
+        self.ipv4Address = ipv4Address
+        self.ipv4Gateway = ipv4Gateway
+        self.macAddress = macAddress
+        self.mtu = mtu
+    }
+
+    public func close() {
+        lock.lock()
+        guard !closed else {
+            lock.unlock()
+            return
+        }
+        closed = true
+        lock.unlock()
+        owner.releaseEndpoint(identifier: endpointIdentifier)
+    }
+
+    deinit {
+        close()
+    }
+}
diff --git a/macOS/GhostVMKit/Operations/InitOptions.swift b/macOS/GhostVMKit/Operations/InitOptions.swift
index 4701b4f..f1d5894 100644
--- a/macOS/GhostVMKit/Operations/InitOptions.swift
+++ b/macOS/GhostVMKit/Operations/InitOptions.swift
@@ -11,6 +11,7 @@ public struct InitOptions {
     public var sharedFolderWritable: Bool
     public var sharedFolders: [SharedFolderConfig]
     public var networkConfig: NetworkConfig?
+    public var hostContainersEnabled: Bool
 
     public init(
         cpus: Int = 4,
@@ -21,7 +22,8 @@ public struct InitOptions {
         sharedFolderPath: String? = nil,
         sharedFolderWritable: Bool = false,
         sharedFolders: [SharedFolderConfig] = [],
-        networkConfig: NetworkConfig? = nil
+        networkConfig: NetworkConfig? = nil,
+        hostContainersEnabled: Bool = false
     ) {
         self.cpus = cpus
         self.memoryGiB = memoryGiB
@@ -32,5 +34,6 @@ public struct InitOptions {
         self.sharedFolderWritable = sharedFolderWritable
         self.sharedFolders = sharedFolders
         self.networkConfig = networkConfig
+        self.hostContainersEnabled = hostContainersEnabled
     }
 }
diff --git a/macOS/GhostVMKit/Operations/VMController.swift b/macOS/GhostVMKit/Operations/VMController.swift
index c493e60..8e2b649 100644
--- a/macOS/GhostVMKit/Operations/VMController.swift
+++ b/macOS/GhostVMKit/Operations/VMController.swift
@@ -448,7 +448,8 @@ public final class VMController {
             lastInstallDate: nil,
             legacyName: nil,
             macAddress: macAddress.string,
-            networkConfig: options.networkConfig
+            networkConfig: options.networkConfig,
+            hostContainersEnabled: options.hostContainersEnabled
         )
 
         let store = VMConfigStore(layout: layout)
@@ -665,6 +666,7 @@ public final class VMController {
                 macAddress: macAddress.string,
                 portForwards: [],
                 networkConfig: sourceConfig.networkConfig,
+                hostContainersEnabled: false,
                 iconMode: nil
             )
 
diff --git a/macOS/GhostVMTests/ContainerBridgeProtocolTests.swift b/macOS/GhostVMTests/ContainerBridgeProtocolTests.swift
new file mode 100644
index 0000000..6651e3f
--- /dev/null
+++ b/macOS/GhostVMTests/ContainerBridgeProtocolTests.swift
@@ -0,0 +1,192 @@
+import XCTest
+@testable import GhostVMKit
+
+final class ContainerBridgeProtocolTests: XCTestCase {
+    func testGhostboxIOFramesRoundTrip() throws {
+        let frames: [GhostboxIOFrame] = [
+            .data(Data([0x00, 0x0A, 0xFF]), stream: .input),
+            .data(Data("output".utf8), stream: .output),
+            .eof(.terminal),
+            .resize(columns: 120, rows: 40),
+            .error("closed"),
+        ]
+        for frame in frames {
+            var line = try frame.encodeLine()
+            XCTAssertEqual(line.removeLast(), 0x0A)
+            XCTAssertEqual(try GhostboxIOFrame.decode(line: line), frame)
+        }
+    }
+
+    func testGhostboxIOFramesEnforceBounds() {
+        XCTAssertThrowsError(try GhostboxIOFrame.data(
+            Data(repeating: 0, count: GhostboxDirectLimits.ioFrameDataBytes + 1),
+            stream: .input
+        ).encodeLine())
+        XCTAssertThrowsError(try GhostboxIOFrame.resize(columns: 0, rows: 24).encodeLine())
+        XCTAssertThrowsError(try GhostboxIOFrame.decode(line: Data()))
+    }
+    func testMaximumGhostboxIOFrameFitsFrameLineLimit() throws {
+        let frame = GhostboxIOFrame.data(
+            Data(repeating: 0x5A, count: GhostboxDirectLimits.ioFrameDataBytes),
+            stream: .terminal
+        )
+        let line = try frame.encodeLine()
+        XCTAssertLessThanOrEqual(line.count - 1, GhostboxDirectLimits.ioFrameLineBytes)
+        XCTAssertEqual(try GhostboxIOFrame.decode(line: Data(line.dropLast())), frame)
+    }
+    func testRuntimeVersionsUseMajorCompatibility() {
+        XCTAssertTrue(ContainerRuntimeVersion.current.isCompatible(with: .init(major: 1, minor: 9)))
+        XCTAssertFalse(ContainerRuntimeVersion.current.isCompatible(with: .init(major: 2, minor: 0)))
+    }
+
+    func testRuntimeRequestEnvelopeRoundTrip() throws {
+        let request = ContainerRuntimeRequest(
+            id: "request-1",
+            method: .containerCreate,
+            parameters: ContainerRuntimeEmpty()
+        )
+        let encoded = try JSONEncoder().encode(request)
+        let envelope = try JSONDecoder().decode(ContainerRuntimeRequestEnvelope.self, from: encoded)
+        let decoded = try JSONDecoder().decode(ContainerRuntimeRequest.self, from: encoded)
+
+        XCTAssertEqual(decoded, request)
+        XCTAssertEqual(envelope.version, .current)
+        XCTAssertEqual(envelope.id, "request-1")
+        XCTAssertEqual(envelope.method.rawValue, "container.create")
+    }
+
+    func testRuntimeMethodsAllowForwardCompatibleValues() throws {
+        let method = ContainerRuntimeMethod(rawValue: "snapshot.prepare")
+        XCTAssertEqual(try JSONDecoder().decode(ContainerRuntimeMethod.self, from: JSONEncoder().encode(method)), method)
+    }
+
+    func testRuntimeCapabilitiesRoundTrip() throws {
+        let capabilities = ContainerRuntimeCapabilities(
+            methods: [.imagePull, .containerCreate, .containerStart],
+            features: ["build.stream.v1"]
+        )
+        XCTAssertEqual(
+            try JSONDecoder().decode(ContainerRuntimeCapabilities.self, from: JSONEncoder().encode(capabilities)),
+            capabilities
+        )
+    }
+
+    func testRuntimeFailureUsesStableCode() throws {
+        let failure = ContainerRuntimeFailure(code: .notFound, message: "container missing")
+        XCTAssertEqual(
+            try JSONDecoder().decode(ContainerRuntimeFailure.self, from: JSONEncoder().encode(failure)),
+            failure
+        )
+    }
+
+    func testRuntimeFilesystemRequestAndMountRoundTrip() throws {
+        let request = ContainerRuntimeRequest(
+            id: "request-fs",
+            method: .filesystemCreate,
+            parameters: ContainerRuntimeFilesystemCreateParameters(guestPath: "/Users/guest/project", readOnly: true)
+        )
+        let mount = ContainerRuntimeMount(
+            type: "virtiofs",
+            source: "filesystem-1",
+            destination: "/workspace",
+            options: ["ro"]
+        )
+        XCTAssertEqual(
+            try JSONDecoder().decode(
+                ContainerRuntimeRequest.self,
+                from: JSONEncoder().encode(request)
+            ),
+            request
+        )
+        XCTAssertEqual(try JSONDecoder().decode(ContainerRuntimeMount.self, from: JSONEncoder().encode(mount)), mount)
+    }
+
+    func testRuntimeBuildRequestCarriesMetadataNotContext() throws {
+        let parameters = ContainerRuntimeBuildCreateParameters(
+            tags: ["web:latest"],
+            dockerfile: Data("FROM scratch\n".utf8),
+            buildArguments: ["MODE=release"],
+            target: "server"
+        )
+        let request = ContainerRuntimeRequest(method: .buildCreate, parameters: parameters)
+        XCTAssertEqual(
+            try JSONDecoder().decode(
+                ContainerRuntimeRequest.self,
+                from: JSONEncoder().encode(request)
+            ),
+            request
+        )
+    }
+
+    func testGhostboxDirectRequestRoundTrip() throws {
+        let request = GhostboxDirectRequest(
+            id: "direct-1",
+            method: .dnsCreate,
+            parameters: [
+                "name": .string("dev"),
+                "nameservers": .array([.string("1.1.1.1")]),
+            ]
+        )
+        let data = try JSONEncoder().encode(request)
+        XCTAssertEqual(try GhostboxDirectRequest.decode(line: data), request)
+        let object = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        XCTAssertEqual(object["operation"] as? String, "direct")
+        XCTAssertEqual(object["method"] as? String, "dns.create")
+    }
+
+    func testGhostboxDirectResponseHasTypedResult() throws {
+        let response = GhostboxDirectResponse.success(id: "direct-1", value: .strings(["1.1.1.1"]))
+        XCTAssertEqual(
+            try JSONDecoder().decode(GhostboxDirectResponse.self, from: JSONEncoder().encode(response)),
+            response
+        )
+    }
+
+    func testGhostboxDirectValueAccessors() {
+        XCTAssertEqual(GhostboxDirectValue.reference("@container/web").referenceValue, "@container/web")
+        XCTAssertEqual(GhostboxDirectValue.references(["@volume/data"]).referencesValue, ["@volume/data"])
+        XCTAssertEqual(GhostboxDirectValue.string("running").jsonValue, .string("running"))
+        XCTAssertNil(GhostboxDirectValue.void.jsonValue)
+    }
+
+    func testMaximumGhostboxByteResponseFitsResponseLineLimit() throws {
+        let response = GhostboxDirectResponse.success(
+            id: "direct-1",
+            value: .bytes(Data(repeating: 0xA5, count: GhostboxDirectLimits.bytePayloadBytes))
+        )
+        let line = try response.encodeLine()
+        XCTAssertLessThanOrEqual(line.count - 1, GhostboxDirectLimits.responseLineBytes)
+        XCTAssertEqual(
+            try JSONDecoder().decode(GhostboxDirectResponse.self, from: Data(line.dropLast())),
+            response
+        )
+    }
+
+    func testGhostboxDirectFailureUsesStableRuntimeError() throws {
+        let response = GhostboxDirectResponse.failure(id: "direct-1", code: .notFound, message: "DNS object missing")
+        let decoded = try JSONDecoder().decode(GhostboxDirectResponse.self, from: JSONEncoder().encode(response))
+        XCTAssertEqual(decoded.error?.code, .notFound)
+        XCTAssertNil(decoded.result)
+    }
+
+    func testDirectDecodeRejectsEmptyAndMalformedRequests() {
+        XCTAssertThrowsError(try GhostboxDirectRequest.decode(line: Data())) { error in
+            XCTAssertEqual(error as? ContainerProtocolError, .emptyRequest)
+        }
+        XCTAssertThrowsError(try GhostboxDirectRequest.decode(line: Data("not json".utf8))) { error in
+            guard case .malformedRequest = error as? ContainerProtocolError else {
+                return XCTFail("Expected malformed request")
+            }
+        }
+    }
+
+    func testBridgeConstantsDescribeDirectChannel() {
+        XCTAssertEqual(ContainerBridgeConstants.port, 5004)
+        XCTAssertEqual(ContainerBridgeConstants.protocolVersion, 5)
+        XCTAssertEqual(ContainerBridgeConstants.maxRequestLineBytes, 64 * 1024)
+        XCTAssertEqual(ContainerRuntimeXPCProtocol.version, 5)
+        XCTAssertEqual(ContainerRuntimeXPCProtocol.Key.ipv4Subnet, "ipv4Subnet")
+        XCTAssertEqual(ContainerRuntimeXPCProtocol.Key.volumeRoot, "volumeRoot")
+        XCTAssertEqual(ContainerRuntimeXPCProtocol.Key.imageRoot, "imageRoot")
+    }
+}
diff --git a/macOS/GhostVMTests/ContentAddressedStoreTests.swift b/macOS/GhostVMTests/ContentAddressedStoreTests.swift
new file mode 100644
index 0000000..9fdcf2c
--- /dev/null
+++ b/macOS/GhostVMTests/ContentAddressedStoreTests.swift
@@ -0,0 +1,81 @@
+import Foundation
+import XCTest
+@testable import GhostVMKit
+
+final class ContentAddressedStoreTests: XCTestCase {
+    private var temporaryDirectory: URL!
+
+    override func setUpWithError() throws {
+        temporaryDirectory = FileManager.default.temporaryDirectory
+            .appendingPathComponent("GhostVM-ContentStoreTests-\(UUID().uuidString)", isDirectory: true)
+    }
+
+    override func tearDownWithError() throws {
+        try? FileManager.default.removeItem(at: temporaryDirectory)
+    }
+
+    func testPutPublishesAtDigestPath() async throws {
+        let store = ContentAddressedStore(rootURL: temporaryDirectory)
+        let data = Data("hello".utf8)
+
+        let digest = try await store.put(data)
+        let url = try await store.blobURL(for: digest)
+        let containsBlob = await store.contains(digest)
+
+        XCTAssertEqual(digest.description, "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824")
+        XCTAssertEqual(try Data(contentsOf: url), data)
+        XCTAssertTrue(containsBlob)
+    }
+
+    func testDuplicatePutReusesBlob() async throws {
+        let store = ContentAddressedStore(rootURL: temporaryDirectory)
+        let data = Data("same blob".utf8)
+
+        let first = try await store.put(data)
+        let second = try await store.put(data)
+
+        XCTAssertEqual(first, second)
+        let files = try FileManager.default.contentsOfDirectory(
+            at: temporaryDirectory.appendingPathComponent("blobs/sha256"),
+            includingPropertiesForKeys: nil
+        )
+        XCTAssertEqual(files.count, 1)
+    }
+
+    func testImportRejectsDigestMismatchAndCleansIngest() async throws {
+        let store = ContentAddressedStore(rootURL: temporaryDirectory)
+        let sourceURL = FileManager.default.temporaryDirectory
+            .appendingPathComponent("GhostVM-ContentSource-\(UUID().uuidString)")
+        try Data("actual".utf8).write(to: sourceURL)
+        defer { try? FileManager.default.removeItem(at: sourceURL) }
+
+        let expected = ContentDigest.sha256(Data("expected".utf8))
+        do {
+            try await store.importBlob(at: sourceURL, expectedDigest: expected)
+            XCTFail("Expected digest mismatch")
+        } catch let error as ContentStoreError {
+            guard case .digestMismatch(let reportedExpected, _) = error else {
+                return XCTFail("Unexpected error: \(error)")
+            }
+            XCTAssertEqual(reportedExpected, expected)
+        }
+
+        let ingest = temporaryDirectory.appendingPathComponent("ingest")
+        XCTAssertEqual(try FileManager.default.contentsOfDirectory(atPath: ingest.path), [])
+    }
+
+    func testDigestValidation() throws {
+        XCTAssertThrowsError(try ContentDigest("sha512:abcd"))
+        XCTAssertThrowsError(try ContentDigest("sha256:abcd"))
+        XCTAssertNoThrow(try ContentDigest("sha256:" + String(repeating: "a", count: 64)))
+    }
+
+    func testDigestCodableUsesOCIString() throws {
+        let digest = ContentDigest.sha256(Data("hello".utf8))
+        let encoded = try JSONEncoder().encode(digest)
+        let decoded = try JSONDecoder().decode(ContentDigest.self, from: encoded)
+
+        XCTAssertEqual(String(data: encoded, encoding: .utf8), #""sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824""#)
+        XCTAssertEqual(decoded, digest)
+    }
+}
diff --git a/macOS/GhostVMTests/GhostClientTypesTests.swift b/macOS/GhostVMTests/GhostClientTypesTests.swift
index 4cb01c1..f9a1497 100644
--- a/macOS/GhostVMTests/GhostClientTypesTests.swift
+++ b/macOS/GhostVMTests/GhostClientTypesTests.swift
@@ -48,6 +48,25 @@ final class GhostClientTypesTests: XCTestCase {
         XCTAssertTrue(response.files.isEmpty)
     }
 
+    func testGuestFileMetadataRoundTrip() throws {
+        let metadata = GuestFileMetadata(
+            name: "sample.txt",
+            type: .file,
+            size: 42,
+            mode: 0o100644,
+            uid: 501,
+            gid: 20,
+            inode: 123,
+            device: 4,
+            linkCount: 1,
+            modifiedSeconds: 1000,
+            modifiedNanoseconds: 500
+        )
+
+        let encoded = try JSONEncoder().encode(metadata)
+        XCTAssertEqual(try JSONDecoder().decode(GuestFileMetadata.self, from: encoded), metadata)
+    }
+
     func testClipboardGetResponseConvenienceContent() throws {
         // UTF-8 text data should produce non-nil content
         let response = ClipboardGetResponse(data: Data("test content".utf8), type: "public.utf8-plain-text")
diff --git a/macOS/GhostVMTests/GhostVMFSExtensionManagerTests.swift b/macOS/GhostVMTests/GhostVMFSExtensionManagerTests.swift
new file mode 100644
index 0000000..3057cda
--- /dev/null
+++ b/macOS/GhostVMTests/GhostVMFSExtensionManagerTests.swift
@@ -0,0 +1,82 @@
+import Foundation
+import XCTest
+
+final class GhostVMFSExtensionManagerTests: XCTestCase {
+    func testRegistrationURLsOnlyReturnsMatchingAbsolutePaths() {
+        let output = """
+        +    org.ghostvm.ghostvm.fs(1.0)\tUUID-1\t2026-08-05 00:00:00 +0000\t/Applications/GhostVM.app/Contents/Extensions/GhostVMFS.appex
+        +    org.example.other.fs(1.0)\tUUID-2\t2026-08-05 00:00:00 +0000\t/Applications/Other.app/Contents/Extensions/Other.appex
+        org.ghostvm.ghostvm.fs malformed relative/path
+        """
+
+        XCTAssertEqual(
+            GhostVMFSExtensionManager.registrationURLs(from: output).map(\.path),
+            ["/Applications/GhostVM.app/Contents/Extensions/GhostVMFS.appex"]
+        )
+    }
+
+    func testEnabledModuleIdentifiersReadsFSKitPreferenceArray() throws {
+        let data = try PropertyListSerialization.data(
+            fromPropertyList: ["com.apple.fskit.apfs", "org.ghostvm.ghostvm.fs"],
+            format: .binary,
+            options: 0
+        )
+
+        XCTAssertEqual(
+            GhostVMFSExtensionManager.enabledModuleIdentifiers(from: data),
+            ["com.apple.fskit.apfs", "org.ghostvm.ghostvm.fs"]
+        )
+    }
+
+    func testInvalidEnabledModulesPreferenceIsEmpty() {
+        XCTAssertTrue(
+            GhostVMFSExtensionManager.enabledModuleIdentifiers(from: Data("invalid".utf8)).isEmpty
+        )
+    }
+
+    func testGhostVMFSAdvertisesMountOperation() throws {
+        let macOSDirectory = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        let plistURL = macOSDirectory.appendingPathComponent("GhostVMFS/Info.template.plist")
+        let plist = try XCTUnwrap(
+            PropertyListSerialization.propertyList(from: Data(contentsOf: plistURL), format: nil)
+                as? [String: Any]
+        )
+        let attributes = try XCTUnwrap(plist["EXAppExtensionAttributes"] as? [String: Any])
+        let activateSyntax = try XCTUnwrap(attributes["FSActivateOptionSyntax"] as? [String: Any])
+
+        XCTAssertEqual(activateSyntax["shortOptions"] as? String, "g:m:o:u:")
+        XCTAssertEqual(
+            (attributes["FSCheckOptionSyntax"] as? [String: Any])?["shortOptions"] as? String,
+            "nqy"
+        )
+        XCTAssertEqual(
+            (attributes["FSFormatOptionSyntax"] as? [String: Any])?["shortOptions"] as? String,
+            "v"
+        )
+    }
+
+    func testGhostVMFSSigningIdentityMatchesBundleIdentifier() throws {
+        let macOSDirectory = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        let entitlementsURL = macOSDirectory.appendingPathComponent("GhostVMFS/entitlements.plist")
+        let entitlements = try XCTUnwrap(
+            PropertyListSerialization.propertyList(
+                from: Data(contentsOf: entitlementsURL),
+                format: nil
+            ) as? [String: Any]
+        )
+
+        XCTAssertEqual(
+            entitlements["com.apple.application-identifier"] as? String,
+            "3FGZQE8AW3.org.ghostvm.ghostvm.fs"
+        )
+        XCTAssertEqual(
+            entitlements["com.apple.developer.team-identifier"] as? String,
+            "3FGZQE8AW3"
+        )
+    }
+
+}
diff --git a/macOS/GhostVMTests/GhostboxSessionTests.swift b/macOS/GhostVMTests/GhostboxSessionTests.swift
new file mode 100644
index 0000000..096fc90
--- /dev/null
+++ b/macOS/GhostVMTests/GhostboxSessionTests.swift
@@ -0,0 +1,288 @@
+import XCTest
+
+final class GhostboxSessionTests: XCTestCase {
+    func testExplicitResourceLimitsUseVisibilityOrientedOverhead() {
+        XCTAssertEqual(GhostboxResourceOverheadPolicy.cpu(requested: 1, explicit: nil), 0)
+        XCTAssertEqual(
+            GhostboxResourceOverheadPolicy.memory(requested: 536_870_912, explicit: nil),
+            29_499_392
+        )
+        XCTAssertEqual(GhostboxResourceOverheadPolicy.cpu(requested: nil, explicit: nil), nil)
+        XCTAssertEqual(GhostboxResourceOverheadPolicy.memory(requested: nil, explicit: nil), nil)
+    }
+
+    func testExplicitOverheadRemainsAuthoritative() {
+        XCTAssertEqual(GhostboxResourceOverheadPolicy.cpu(requested: 1, explicit: 2), 2)
+        XCTAssertEqual(GhostboxResourceOverheadPolicy.memory(requested: 536_870_912, explicit: 134_217_728), 134_217_728)
+    }
+
+    func testSessionProvidesTypedRuntimeContext() {
+        let session = GhostboxSession(context: ["network": "shared"])
+
+        XCTAssertEqual(session.contextValue("network", as: String.self), "shared")
+        XCTAssertNil(session.contextValue("network", as: Int.self))
+        XCTAssertNil(session.contextValue("missing", as: String.self))
+    }
+
+    func testExactUnregisterFreesNameWithoutRunningCleanup() async throws {
+        let session = GhostboxSession()
+        let first = TestValue(1)
+        let cleanupCount = LockedCounter()
+        let reference = try session.register(
+            kind: "test",
+            name: "value",
+            value: first,
+            equivalent: { $0 === $1 },
+            cleanup: { _ in cleanupCount.increment() }
+        )
+
+        XCTAssertTrue(try session.unregister(reference, expectedKind: "test", matching: first))
+        XCTAssertEqual(session.count, 0)
+        XCTAssertEqual(
+            try session.register(
+                kind: "test",
+                name: "value",
+                value: TestValue(2),
+                equivalent: { $0 === $1 }
+            ),
+            reference
+        )
+        await session.close()
+        XCTAssertEqual(cleanupCount.value, 0)
+    }
+
+    func testUnregisterAndCleanupRunsCleanupExactlyOnce() async throws {
+        let session = GhostboxSession()
+        let value = TestValue(1)
+        let cleanupCount = LockedCounter()
+        let reference = try session.register(
+            kind: "mount",
+            name: "volume",
+            value: value,
+            equivalent: { $0 === $1 },
+            cleanup: { _ in cleanupCount.increment() }
+        )
+
+        let removed = try await session.unregisterAndCleanup(reference, expectedKind: "mount", matching: value)
+        XCTAssertTrue(removed)
+        XCTAssertEqual(cleanupCount.value, 1)
+        let removedAgain = try await session.unregisterAndCleanup(reference, expectedKind: "mount", matching: value)
+        XCTAssertFalse(removedAgain)
+        await session.close()
+        XCTAssertEqual(cleanupCount.value, 1)
+    }
+
+    func testUnregisterCannotRemoveReplacementOrSiblingAlias() throws {
+        let session = GhostboxSession()
+        let value = TestValue(1)
+        let other = TestValue(2)
+        let aliases = try session.registerAliases(
+            [(kind: "first", name: "value"), (kind: "second", name: "value")],
+            value: value,
+            equivalent: { $0 === $1 }
+        )
+
+        XCTAssertFalse(try session.unregister(aliases[0], expectedKind: "first", matching: other))
+        XCTAssertTrue(try session.unregister(aliases[0], expectedKind: "first", matching: value))
+        XCTAssertEqual(try session.value(for: aliases[1], expectedKind: "second", as: TestValue.self), value)
+        XCTAssertEqual(session.count, 1)
+    }
+
+    func testAttachmentReadinessWaitsForReadyAndFailsWhenClosedFirst() async throws {
+        let readiness = GhostboxAttachmentReadiness()
+        let resumeCount = LockedCounter()
+        let waiter = Task {
+            try await readiness.wait()
+            resumeCount.increment()
+        }
+        try await Task.sleep(for: .milliseconds(20))
+        XCTAssertEqual(resumeCount.value, 0)
+        readiness.markReady()
+        try await waiter.value
+        XCTAssertEqual(resumeCount.value, 1)
+        try await readiness.wait()
+
+        let closed = GhostboxAttachmentReadiness()
+        closed.close()
+        do {
+            try await closed.wait()
+            XCTFail("Expected closed readiness to fail")
+        } catch let error as DirectDispatchError {
+            XCTAssertEqual(error.code, .failedPrecondition)
+        }
+    }
+
+    func testMutableAggregateUpdatesRelatedStateThroughPublicReference() throws {
+        struct Aggregate: Sendable, Equatable {
+            var value: Int
+            var relatedReference: String?
+        }
+
+        let session = GhostboxSession()
+        let slot = GhostboxMutableSlot(Aggregate(value: 1, relatedReference: nil))
+        let reference = try session.register(
+            kind: "process-config",
+            name: "diagnostic",
+            value: slot,
+            equivalent: { $0.get() == $1.get() }
+        )
+        let stored: GhostboxMutableSlot = try session.value(
+            for: reference,
+            expectedKind: "process-config"
+        )
+        stored.update {
+            $0.value = 2
+            $0.relatedReference = "@terminal/diagnostic"
+        }
+
+        let updated: GhostboxMutableSlot = try session.value(
+            for: "@process-config/diagnostic",
+            expectedKind: "process-config"
+        )
+        XCTAssertEqual(updated.get(), Aggregate(value: 2, relatedReference: "@terminal/diagnostic"))
+        XCTAssertEqual(session.count, 1)
+    }
+
+    func testCloseDrainsActiveInvocationBeforeCleanup() async throws {
+        let session = GhostboxSession()
+        let cleanupCount = LockedCounter()
+        try session.beginInvocation()
+        _ = try session.register(
+            kind: "test",
+            name: "before-close",
+            value: TestValue(1),
+            equivalent: { $0 === $1 },
+            cleanup: { _ in cleanupCount.increment() }
+        )
+
+        let closeTask = Task { await session.close() }
+        try await Task.sleep(for: .milliseconds(20))
+
+        XCTAssertEqual(session.count, 1)
+        XCTAssertEqual(cleanupCount.value, 0)
+        _ = try session.register(
+            kind: "test",
+            name: "during-close",
+            value: TestValue(2),
+            equivalent: { $0 === $1 },
+            cleanup: { _ in cleanupCount.increment() }
+        )
+
+        session.endInvocation()
+        await closeTask.value
+        XCTAssertEqual(session.count, 0)
+        XCTAssertEqual(cleanupCount.value, 2)
+    }
+
+    func testCloseCancelsActiveInvocationBeforeWaitingForCleanup() async throws {
+        let session = GhostboxSession()
+        let cancellationCount = LockedCounter()
+        let cleanupCount = LockedCounter()
+        try session.beginInvocation()
+        _ = try session.register(
+            kind: "test",
+            name: "attachment",
+            value: TestValue(1),
+            equivalent: { $0 === $1 },
+            cancel: { _ in
+                cancellationCount.increment()
+                session.endInvocation()
+            },
+            cleanup: { _ in cleanupCount.increment() }
+        )
+
+        await session.close()
+
+        XCTAssertEqual(cancellationCount.value, 1)
+        XCTAssertEqual(cleanupCount.value, 1)
+        XCTAssertEqual(session.count, 0)
+    }
+
+    func testStoredRepresentationMismatchIsNotReportedAsMissing() throws {
+        let session = GhostboxSession()
+        let reference = try session.register(
+            kind: "test",
+            name: "value",
+            value: TestValue(1),
+            equivalent: { $0 === $1 }
+        )
+
+        XCTAssertThrowsError(
+            try session.value(
+                for: reference,
+                expectedKind: "test",
+                as: GhostboxMutableSlot.self
+            )
+        ) { error in
+            guard let error = error as? DirectDispatchError else {
+                return XCTFail("Expected DirectDispatchError")
+            }
+            XCTAssertEqual(error.code, .failedPrecondition)
+        }
+    }
+
+    func testMutableSlotSerializesConcurrentUpdates() async {
+        let slot = GhostboxMutableSlot(0)
+
+        await withTaskGroup(of: Void.self) { group in
+            for _ in 0..<1_000 {
+                group.addTask { slot.update { $0 += 1 } }
+            }
+        }
+
+        XCTAssertEqual(slot.get(), 1_000)
+    }
+
+    func testRegisterNewDoesNotConstructDuplicateValue() throws {
+        let session = GhostboxSession()
+        let constructionCount = LockedCounter()
+        _ = try session.registerNew(
+            kind: "test",
+            name: "value",
+            makeValue: {
+                constructionCount.increment()
+                return TestValue(1)
+            },
+            equivalent: { $0 === $1 }
+        )
+
+        XCTAssertThrowsError(
+            try session.registerNew(
+                kind: "test",
+                name: "value",
+                makeValue: {
+                    constructionCount.increment()
+                    return TestValue(2)
+                },
+                equivalent: { $0 === $1 }
+            )
+        )
+        XCTAssertEqual(constructionCount.value, 1)
+    }
+
+    func testTypedValueSnapshotsFilterSortAndPreserveReferences() throws {
+        let session = GhostboxSession()
+        _ = try session.register(kind: "container", name: "zeta", value: 2, equivalent: { $0 == $1 })
+        _ = try session.register(kind: "manager", name: "ignored", value: 3, equivalent: { $0 == $1 })
+        _ = try session.register(kind: "container", name: "alpha", value: 1, equivalent: { $0 == $1 })
+
+        let snapshots: [(reference: String, value: Int)] = try session.valueSnapshots(ofKind: "container")
+
+        XCTAssertEqual(snapshots.map(\.reference), ["@container/alpha", "@container/zeta"])
+        XCTAssertEqual(snapshots.map(\.value), [1, 2])
+    }
+
+}
+
+private final class TestValue: @unchecked Sendable, Equatable {
+    let id: Int
+    init(_ id: Int) { self.id = id }
+    static func == (lhs: TestValue, rhs: TestValue) -> Bool { lhs === rhs }
+}
+
+private final class LockedCounter: @unchecked Sendable {
+    private let lock = NSLock()
+    private var count = 0
+    var value: Int { lock.withLock { count } }
+    func increment() { lock.withLock { count += 1 } }
+}
diff --git a/macOS/GhostVMTests/GuestFileSystemBridgeServiceTests.swift b/macOS/GhostVMTests/GuestFileSystemBridgeServiceTests.swift
new file mode 100644
index 0000000..41aff8e
--- /dev/null
+++ b/macOS/GhostVMTests/GuestFileSystemBridgeServiceTests.swift
@@ -0,0 +1,86 @@
+import XCTest
+@testable import GhostFileKit
+
+@MainActor
+final class GuestFileSystemBridgeServiceTests: XCTestCase {
+    func testRegistrationCreatesAuthenticatedLoopbackGhostFileResource() async throws {
+        let client = MockGhostClient()
+        let bridge = GuestFileSystemBridgeService()
+        try bridge.start(client: client)
+        defer { bridge.stop() }
+
+        let export = try await bridge.registerExport(guestPath: "/tmp", readOnly: true)
+        let url = export.resourceURL
+        XCTAssertEqual(url.scheme, "ghostfile")
+        XCTAssertEqual(url.host, "127.0.0.1")
+        XCTAssertNotEqual(url.port, 0)
+
+        let items = try XCTUnwrap(URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems)
+        XCTAssertEqual(items.filter { $0.name == "pk" }.count, 1)
+        XCTAssertEqual(items.filter { $0.name == "access_key" }.count, 1)
+        XCTAssertEqual(
+            items.first { $0.name == GhostFileProtocol.cacheTTLQueryName }?.value,
+            String(GhostFileProtocol.defaultCacheTTLSeconds)
+        )
+        XCTAssertEqual(items.filter { $0.name == "mount_instance" }.count, 1)
+        XCTAssertFalse(try XCTUnwrap(items.first { $0.name == "access_key" }?.value).isEmpty)
+
+        bridge.unregisterExport(id: export.id)
+    }
+
+    @MainActor
+    func testRegisteredExportIncludesRequestedCacheTTL() async throws {
+        let bridge = GuestFileSystemBridgeService()
+        let client = MockGhostClient()
+        try bridge.start(client: client)
+        defer { bridge.stop() }
+
+        let export = try await bridge.registerExport(
+            guestPath: "/tmp",
+            readOnly: true,
+            cacheTTLSeconds: 0
+        )
+        let items = try XCTUnwrap(
+            URLComponents(url: export.resourceURL, resolvingAgainstBaseURL: false)?.queryItems
+        )
+        XCTAssertEqual(items.first { $0.name == GhostFileProtocol.cacheTTLQueryName }?.value, "0")
+        bridge.unregisterExport(id: export.id)
+    }
+
+    func testRegistrationAcceptsWritableExport() async throws {
+        let client = MockGhostClient()
+        let bridge = GuestFileSystemBridgeService()
+        try bridge.start(client: client)
+        defer { bridge.stop() }
+
+        let export = try await bridge.registerExport(guestPath: "/tmp", readOnly: false)
+        XCTAssertEqual(export.resourceURL.scheme, "ghostfile")
+        let mountClient = try GhostFileHTTP3Client(resourceURL: export.resourceURL)
+        let capabilities = try await mountClient.capabilities()
+        XCTAssertFalse(capabilities.readOnly)
+        _ = try await mountClient.create(path: "created", type: .file, mode: 0o600)
+        XCTAssertEqual(client.createdFileSystemItems.first?.path, "/tmp/created")
+        bridge.unregisterExport(id: export.id)
+    }
+
+    func testRegistrationRejectsInvalidGuestPaths() async throws {
+        let bridge = GuestFileSystemBridgeService()
+        try bridge.start(client: MockGhostClient())
+        defer { bridge.stop() }
+
+        await XCTAssertThrowsErrorAsync {
+            _ = try await bridge.registerExport(guestPath: "relative", readOnly: true)
+        }
+    }
+}
+
+private func XCTAssertThrowsErrorAsync(
+    _ expression: () async throws -> Void,
+    file: StaticString = #filePath,
+    line: UInt = #line
+) async {
+    do {
+        try await expression()
+        XCTFail("Expected an error", file: file, line: line)
+    } catch {}
+}
diff --git a/macOS/GhostVMTests/GuestMountRegistryTests.swift b/macOS/GhostVMTests/GuestMountRegistryTests.swift
new file mode 100644
index 0000000..3f2f0bf
--- /dev/null
+++ b/macOS/GhostVMTests/GuestMountRegistryTests.swift
@@ -0,0 +1,56 @@
+import XCTest
+
+final class GuestMountRegistryTests: XCTestCase {
+    func testGuestMountPolicyRejectsOuterHostPathMethods() {
+        for method in ["mount.create", "mount.block", "mount.share", "mount.any", "mount.clone", "mount.futureHostPath"] {
+            XCTAssertFalse(GuestMountAccessPolicy.allowsGuestInvocation(method), method)
+        }
+    }
+
+    func testGuestMountPolicyAllowsPrivateShareAndReferenceConsumers() {
+        for method in [
+            "mount.guestShare", "mount.sharedMount", "mount.source", "mount.delete",
+            "volume.create", "volume.list", "volume.inspect", "volume.mount", "volume.delete",
+            "container.configuration.withMounts",
+        ] {
+            XCTAssertTrue(GuestMountAccessPolicy.allowsGuestInvocation(method), method)
+        }
+    }
+
+    func testPrivateMountDirectoryIsUniqueTemporaryAndOwnerOnly() throws {
+        let first = try PrivateGuestMountDirectory.create()
+        let second = try PrivateGuestMountDirectory.create()
+        defer {
+            try? FileManager.default.removeItem(at: first)
+            try? FileManager.default.removeItem(at: second)
+        }
+
+        XCTAssertNotEqual(first, second)
+        XCTAssertEqual(first.deletingLastPathComponent(), PrivateGuestMountDirectory.rootURL)
+        XCTAssertEqual(second.deletingLastPathComponent(), PrivateGuestMountDirectory.rootURL)
+        let attributes = try FileManager.default.attributesOfItem(atPath: first.path)
+        XCTAssertEqual((attributes[.posixPermissions] as? NSNumber)?.intValue, 0o700)
+    }
+
+    func testDeleteDuringCreationPreventsRegistrationAndReleasesName() {
+        var registry = GuestMountRegistry()
+        let reference = "@mount/project"
+
+        XCTAssertTrue(registry.reserve(reference))
+        XCTAssertNil(registry.release(reference))
+        XCTAssertEqual(registry.complete(reference, value: 1), .deleted)
+        XCTAssertNil(registry[reference])
+        XCTAssertTrue(registry.reserve(reference))
+    }
+
+    func testCompletedMountCanBeReleased() {
+        var registry = GuestMountRegistry()
+        let reference = "@mount/project"
+
+        XCTAssertTrue(registry.reserve(reference))
+        XCTAssertEqual(registry.complete(reference, value: 1), .registered)
+        XCTAssertEqual(registry[reference], 1)
+        XCTAssertEqual(registry.release(reference), 1)
+        XCTAssertNil(registry[reference])
+    }
+}
diff --git a/macOS/GhostVMTests/GuestPathProviderTests.swift b/macOS/GhostVMTests/GuestPathProviderTests.swift
new file mode 100644
index 0000000..e6de6f0
--- /dev/null
+++ b/macOS/GhostVMTests/GuestPathProviderTests.swift
@@ -0,0 +1,48 @@
+import Foundation
+import XCTest
+import GhostFileKit
+@testable import GhostVMKit
+
+final class GuestPathProviderTests: XCTestCase {
+    func testForwardsAllMutationsToGuestClient() async throws {
+        let client = MockGhostClient()
+        let provider = GuestPathProvider(client: client, root: "/Users/guest/share")
+
+        _ = try await provider.create(path: "folder", type: .directory, mode: 0o750)
+        _ = try await provider.createSymbolicLink(path: "link", destination: "folder/file")
+        _ = try await provider.write(path: "folder/file", offset: 7, data: Data("data".utf8))
+        _ = try await provider.setAttributes(
+            path: "folder/file",
+            attributes: GhostFileProviderAttributes(mode: 0o600, size: 4)
+        )
+        _ = try await provider.rename(path: "folder/file", destinationPath: "folder/renamed")
+        try await provider.remove(path: "folder/renamed")
+
+        XCTAssertEqual(client.createdFileSystemItems.first?.path, "/Users/guest/share/folder")
+        XCTAssertEqual(client.createdFileSystemItems.first?.type, .directory)
+        XCTAssertEqual(client.createdFileSystemItems.first?.mode, 0o750)
+        XCTAssertEqual(client.createdSymbolicLinks.first?.path, "/Users/guest/share/link")
+        XCTAssertEqual(client.createdSymbolicLinks.first?.destination, "folder/file")
+        XCTAssertEqual(client.fileWrites.first?.path, "/Users/guest/share/folder/file")
+        XCTAssertEqual(client.fileWrites.first?.offset, 7)
+        XCTAssertEqual(client.fileAttributeChanges.first?.attributes.mode, 0o600)
+        XCTAssertEqual(client.fileAttributeChanges.first?.attributes.size, 4)
+        XCTAssertEqual(client.renamedFileSystemItems.first?.destinationPath, "/Users/guest/share/folder/renamed")
+        XCTAssertEqual(client.removedFileSystemItems, ["/Users/guest/share/folder/renamed"])
+    }
+
+    func testRejectsEscapingRelativePathsBeforeRPC() async {
+        let client = MockGhostClient()
+        let provider = GuestPathProvider(client: client, root: "/Users/guest/share")
+
+        do {
+            _ = try await provider.write(path: "../outside", offset: 0, data: Data())
+            XCTFail("Expected invalid path")
+        } catch let error as POSIXError {
+            XCTAssertEqual(error.code, .EINVAL)
+        } catch {
+            XCTFail("Expected POSIX EINVAL, got \(error)")
+        }
+        XCTAssertTrue(client.fileWrites.isEmpty)
+    }
+}
diff --git a/macOS/GhostVMTests/InitOptionsTests.swift b/macOS/GhostVMTests/InitOptionsTests.swift
index 9a48886..a61bbb3 100644
--- a/macOS/GhostVMTests/InitOptionsTests.swift
+++ b/macOS/GhostVMTests/InitOptionsTests.swift
@@ -12,6 +12,7 @@ final class InitOptionsTests: XCTestCase {
         XCTAssertNil(options.sharedFolderPath)
         XCTAssertFalse(options.sharedFolderWritable)
         XCTAssertTrue(options.sharedFolders.isEmpty)
+        XCTAssertFalse(options.hostContainersEnabled)
     }
 
     func testCustomValues() {
@@ -22,7 +23,8 @@ final class InitOptionsTests: XCTestCase {
             restoreImagePath: "/path/to/restore.ipsw",
             diskImageFormat: .sparseFile,
             sharedFolderPath: "/Users/test/shared",
-            sharedFolderWritable: true
+            sharedFolderWritable: true,
+            hostContainersEnabled: true
         )
         XCTAssertEqual(options.cpus, 8)
         XCTAssertEqual(options.memoryGiB, 16)
@@ -31,5 +33,6 @@ final class InitOptionsTests: XCTestCase {
         XCTAssertEqual(options.restoreImagePath, "/path/to/restore.ipsw")
         XCTAssertEqual(options.sharedFolderPath, "/Users/test/shared")
         XCTAssertTrue(options.sharedFolderWritable)
+        XCTAssertTrue(options.hostContainersEnabled)
     }
 }
diff --git a/macOS/GhostVMTests/MockGhostClient.swift b/macOS/GhostVMTests/MockGhostClient.swift
index 2d62b73..5902be1 100644
--- a/macOS/GhostVMTests/MockGhostClient.swift
+++ b/macOS/GhostVMTests/MockGhostClient.swift
@@ -16,6 +16,25 @@ final class MockGhostClient: GhostClientProtocol {
     var clearFileQueueCalled = false
     var getClipboardCallCount = 0
     var checkHealthCallCount = 0
+    var fileSystemMetadataResult = GuestFileMetadata(
+        name: "item",
+        type: .file,
+        size: 0,
+        mode: 0o100644,
+        uid: 501,
+        gid: 20,
+        inode: 1,
+        device: 1,
+        linkCount: 1,
+        modifiedSeconds: 0,
+        modifiedNanoseconds: 0
+    )
+    var createdFileSystemItems: [(path: String, type: GuestFileCreateType, mode: UInt32)] = []
+    var createdSymbolicLinks: [(path: String, destination: String)] = []
+    var fileWrites: [(path: String, offset: UInt64, data: Data)] = []
+    var fileAttributeChanges: [(path: String, attributes: GuestFileAttributes)] = []
+    var removedFileSystemItems: [String] = []
+    var renamedFileSystemItems: [(path: String, destinationPath: String)] = []
 
     func getClipboard() async throws -> ClipboardGetResponse {
         getClipboardCallCount += 1
@@ -65,6 +84,39 @@ final class MockGhostClient: GhostClientProtocol {
 
     // MARK: - File system stubs
     func listDirectory(path: String) async throws -> FSListResponse { throw MockError.notImplemented }
+    func fileMetadata(path: String) async throws -> GuestFileMetadata { throw MockError.notImplemented }
+    func listDirectoryMetadata(path: String) async throws -> GuestDirectoryMetadata { throw MockError.notImplemented }
+    func readFile(path: String, offset: UInt64, length: Int) async throws -> Data { throw MockError.notImplemented }
+    func readSymbolicLink(path: String) async throws -> String { throw MockError.notImplemented }
+    func createFileSystemItem(path: String, type: GuestFileCreateType, mode: UInt32) async throws -> GuestFileMetadata {
+        if let error = shouldThrow { throw error }
+        createdFileSystemItems.append((path, type, mode))
+        return fileSystemMetadataResult
+    }
+    func createSymbolicLink(path: String, destination: String) async throws -> GuestFileMetadata {
+        if let error = shouldThrow { throw error }
+        createdSymbolicLinks.append((path, destination))
+        return fileSystemMetadataResult
+    }
+    func writeFile(path: String, offset: UInt64, data: Data) async throws -> GuestFileMetadata {
+        if let error = shouldThrow { throw error }
+        fileWrites.append((path, offset, data))
+        return fileSystemMetadataResult
+    }
+    func setFileAttributes(path: String, attributes: GuestFileAttributes) async throws -> GuestFileMetadata {
+        if let error = shouldThrow { throw error }
+        fileAttributeChanges.append((path, attributes))
+        return fileSystemMetadataResult
+    }
+    func removeFileSystemItem(path: String) async throws {
+        if let error = shouldThrow { throw error }
+        removedFileSystemItems.append(path)
+    }
+    func renameFileSystemItem(path: String, destinationPath: String) async throws -> GuestFileMetadata {
+        if let error = shouldThrow { throw error }
+        renamedFileSystemItems.append((path, destinationPath))
+        return fileSystemMetadataResult
+    }
     func mkdir(path: String) async throws {}
     func deleteFile(path: String) async throws {}
     func moveFile(from: String, to: String) async throws {}
diff --git a/macOS/GhostVMTests/NetworkManagerTests.swift b/macOS/GhostVMTests/NetworkManagerTests.swift
new file mode 100644
index 0000000..f9d27b6
--- /dev/null
+++ b/macOS/GhostVMTests/NetworkManagerTests.swift
@@ -0,0 +1,68 @@
+import XCTest
+@testable import GhostVMKit
+
+final class NetworkManagerTests: XCTestCase {
+    func testVMAndContainerEndpointsShareNetworkControlPlane() async throws {
+        let networkID = ManagedNetworkID(rawValue: "development")
+        let network = ManagedNetwork(
+            id: networkID,
+            name: "Development",
+            driver: .vmnetShared,
+            ipv4Subnet: "192.168.127.0/24",
+            gateway: "192.168.127.1"
+        )
+        let manager = NetworkManager(networks: [network])
+
+        try await manager.attach(ManagedNetworkEndpoint(
+            networkID: networkID,
+            workloadKind: .virtualMachine,
+            workloadID: "macos-dev"
+        ))
+        try await manager.attach(ManagedNetworkEndpoint(
+            networkID: networkID,
+            workloadKind: .container,
+            workloadID: "web"
+        ))
+
+        let endpoints = await manager.endpoints(networkID: networkID)
+        XCTAssertEqual(Set(endpoints.map(\.workloadKind)), [.virtualMachine, .container])
+    }
+
+    func testAttachRequiresKnownNetwork() async {
+        let manager = NetworkManager()
+        let networkID = ManagedNetworkID(rawValue: "missing")
+        let endpoint = ManagedNetworkEndpoint(
+            networkID: networkID,
+            workloadKind: .container,
+            workloadID: "web"
+        )
+
+        do {
+            try await manager.attach(endpoint)
+            XCTFail("Expected missing network error")
+        } catch let error as NetworkManagerError {
+            XCTAssertEqual(error, .networkNotFound(networkID))
+        } catch {
+            XCTFail("Unexpected error: \(error)")
+        }
+    }
+
+    func testRemovingNetworkRemovesItsEndpoints() async throws {
+        let networkID = ManagedNetworkID(rawValue: "temporary")
+        let manager = NetworkManager(networks: [
+            ManagedNetwork(id: networkID, name: "Temporary", driver: .virtualizationNAT)
+        ])
+        try await manager.attach(ManagedNetworkEndpoint(
+            networkID: networkID,
+            workloadKind: .virtualMachine,
+            workloadID: "test-vm"
+        ))
+
+        try await manager.remove(id: networkID)
+
+        let endpoints = await manager.endpoints()
+        let network = await manager.network(id: networkID)
+        XCTAssertTrue(endpoints.isEmpty)
+        XCTAssertNil(network)
+    }
+}
diff --git a/macOS/GhostVMTests/SharedVmnetIPv4PoolTests.swift b/macOS/GhostVMTests/SharedVmnetIPv4PoolTests.swift
new file mode 100644
index 0000000..81c67e2
--- /dev/null
+++ b/macOS/GhostVMTests/SharedVmnetIPv4PoolTests.swift
@@ -0,0 +1,92 @@
+import XCTest
+@testable import GhostVMKit
+
+final class SharedVmnetIPv4PoolTests: XCTestCase {
+    func testAllocatesContainersAfterGatewayAndVMLease() throws {
+        var pool = SharedVmnetIPv4Pool(
+            subnet: 0xc0a85000,
+            mask: 0xffffff00,
+            prefixLength: 24
+        )
+
+        XCTAssertEqual(try pool.allocate(endpointIdentifier: "one"), 0xc0a85003)
+        XCTAssertEqual(try pool.allocate(endpointIdentifier: "two"), 0xc0a85004)
+        XCTAssertEqual(SharedVmnetIPv4Pool.string(for: 0xc0a85003), "192.168.80.3")
+    }
+
+    func testAllocationIsIdempotentAndReleasedAddressIsReused() throws {
+        var pool = SharedVmnetIPv4Pool(
+            subnet: 0xc0a85000,
+            mask: 0xfffffff8,
+            prefixLength: 29
+        )
+
+        let firstAddress = try pool.allocate(endpointIdentifier: "one")
+        let firstMAC = SharedVmnetIPv4Pool.macAddress(for: firstAddress)
+        XCTAssertEqual(firstAddress, 0xc0a85003)
+        XCTAssertEqual(try pool.allocate(endpointIdentifier: "one"), 0xc0a85003)
+        pool.release(endpointIdentifier: "one")
+        let reusedAddress = try pool.allocate(endpointIdentifier: "two")
+        XCTAssertEqual(reusedAddress, 0xc0a85003)
+        XCTAssertEqual(SharedVmnetIPv4Pool.macAddress(for: reusedAddress), firstMAC)
+    }
+
+    func testDifferentAddressesHaveDifferentMACAddresses() throws {
+        var pool = SharedVmnetIPv4Pool(subnet: 0xc0a85000, mask: 0xffffff00, prefixLength: 24)
+        let firstAddress = try pool.allocate(endpointIdentifier: "one")
+        let secondAddress = try pool.allocate(endpointIdentifier: "two")
+
+        XCTAssertNotEqual(
+            SharedVmnetIPv4Pool.macAddress(for: firstAddress),
+            SharedVmnetIPv4Pool.macAddress(for: secondAddress)
+        )
+    }
+
+    func testMACAddressIsStableAcrossPoolRecreation() throws {
+        var firstPool = SharedVmnetIPv4Pool(subnet: 0xc0a87100, mask: 0xffffff00, prefixLength: 24)
+        var recreatedPool = SharedVmnetIPv4Pool(subnet: 0xc0a87100, mask: 0xffffff00, prefixLength: 24)
+        let firstAddress = try firstPool.allocate(endpointIdentifier: "first-container")
+        let recreatedAddress = try recreatedPool.allocate(endpointIdentifier: "replacement-container")
+
+        XCTAssertEqual(recreatedAddress, firstAddress)
+        XCTAssertEqual(
+            SharedVmnetIPv4Pool.macAddress(for: recreatedAddress),
+            SharedVmnetIPv4Pool.macAddress(for: firstAddress)
+        )
+        XCTAssertEqual(SharedVmnetIPv4Pool.macAddress(for: 0xc0a87180), "02:00:c0:a8:71:80")
+    }
+
+    func testRejectsSubnetWithoutContainerAddresses() {
+        var pool = SharedVmnetIPv4Pool(
+            subnet: 0xc0a85000,
+            mask: 0xfffffffc,
+            prefixLength: 30
+        )
+
+        XCTAssertThrowsError(try pool.allocate(endpointIdentifier: "one")) { error in
+            XCTAssertEqual(error as? SharedVmnetIPv4PoolError, .exhausted)
+        }
+    }
+
+    func testReservesUpperHalfForDirectContainerSessions() throws {
+        var pool = SharedVmnetIPv4Pool(
+            subnet: 0xc0a85000,
+            mask: 0xffffff00,
+            prefixLength: 24
+        )
+
+        var addresses: [UInt32] = []
+        while let address = try? pool.allocate(endpointIdentifier: "endpoint-\(addresses.count)") {
+            addresses.append(address)
+        }
+        XCTAssertEqual(addresses.first, 0xc0a85003)
+        XCTAssertEqual(addresses.last, 0xc0a8507f)
+        XCTAssertEqual(addresses.count, 125)
+    }
+
+    func testFullIPv4RangeDoesNotOverflow() throws {
+        var pool = SharedVmnetIPv4Pool(subnet: 0, mask: 0, prefixLength: 0)
+
+        XCTAssertEqual(try pool.allocate(endpointIdentifier: "one"), 3)
+    }
+}
diff --git a/macOS/GhostVMTests/VMConfigStoreTests.swift b/macOS/GhostVMTests/VMConfigStoreTests.swift
index e10c39e..c52e771 100644
--- a/macOS/GhostVMTests/VMConfigStoreTests.swift
+++ b/macOS/GhostVMTests/VMConfigStoreTests.swift
@@ -54,6 +54,7 @@ final class VMConfigStoreTests: XCTestCase {
         XCTAssertEqual(loaded.diskBytes, config.diskBytes)
         XCTAssertEqual(loaded.installed, config.installed)
         XCTAssertEqual(loaded.lastInstallBuild, config.lastInstallBuild)
+        XCTAssertFalse(loaded.hostContainersEnabled)
         XCTAssertNil(loaded.windowWidth)
         XCTAssertNil(loaded.windowHeight)
     }
diff --git a/macOS/GhostVMTests/VMCtlTests.swift b/macOS/GhostVMTests/VMCtlTests.swift
index f880b97..02a5287 100644
--- a/macOS/GhostVMTests/VMCtlTests.swift
+++ b/macOS/GhostVMTests/VMCtlTests.swift
@@ -130,6 +130,7 @@ final class VMStoredConfigTests: XCTestCase {
         XCTAssertEqual(decoded.restoreImagePath, config.restoreImagePath)
         XCTAssertEqual(decoded.installed, config.installed)
         XCTAssertEqual(decoded.lastInstallBuild, config.lastInstallBuild)
+        XCTAssertFalse(decoded.hostContainersEnabled)
         XCTAssertNil(decoded.windowWidth)
         XCTAssertNil(decoded.windowHeight)
     }
@@ -185,6 +186,34 @@ final class VMStoredConfigTests: XCTestCase {
         XCTAssertFalse(config.isSuspended)
     }
 
+    func testHostContainersDefaultsToFalseAndRoundTrips() throws {
+        let json = """
+        {
+            "version": 1,
+            "createdAt": 0,
+            "modifiedAt": 0,
+            "cpus": 2,
+            "memoryBytes": 4294967296,
+            "diskBytes": 34359738368,
+            "restoreImagePath": "/restore.ipsw",
+            "hardwareModelPath": "HardwareModel.bin",
+            "machineIdentifierPath": "MachineIdentifier.bin",
+            "auxiliaryStoragePath": "AuxiliaryStorage.bin",
+            "diskPath": "disk.img",
+            "sharedFolderReadOnly": true,
+            "installed": false
+        }
+        """
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .secondsSince1970
+        var config = try decoder.decode(VMStoredConfig.self, from: json.data(using: .utf8)!)
+        XCTAssertFalse(config.hostContainersEnabled)
+
+        config.hostContainersEnabled = true
+        let data = try JSONEncoder().encode(config)
+        XCTAssertTrue(try decoder.decode(VMStoredConfig.self, from: data).hostContainersEnabled)
+    }
+
     func testIsSuspendedEncodeDecode() throws {
         // JSON with isSuspended = true should decode correctly
         let json = """
@@ -289,6 +318,11 @@ final class VMFileLayoutTests: XCTestCase {
         XCTAssertEqual(layout.auxiliaryStorageURL.path, "/Users/test/VMs/MyVM.GhostVM/AuxiliaryStorage.bin")
         XCTAssertEqual(layout.pidFileURL.path, "/Users/test/VMs/MyVM.GhostVM/vmctl.pid")
         XCTAssertEqual(layout.snapshotsDirectoryURL.path, "/Users/test/VMs/MyVM.GhostVM/Snapshots")
+        XCTAssertEqual(layout.containerRuntimeDirectoryURL.path, "/Users/test/VMs/MyVM.GhostVM/Containers")
+        XCTAssertEqual(layout.containerRuntimeMetadataURL.path, "/Users/test/VMs/MyVM.GhostVM/Containers/containers.json")
+        XCTAssertEqual(layout.containerRuntimeImagesURL.path, "/Users/test/VMs/MyVM.GhostVM/Containers/images")
+        XCTAssertEqual(layout.containerRuntimeLogsURL.path, "/Users/test/VMs/MyVM.GhostVM/Containers/logs")
+        XCTAssertEqual(layout.containerRuntimeVolumesURL.path, "/Users/test/VMs/MyVM.GhostVM/Containers/volumes")
     }
 
     func testSuspendStateURL() {
diff --git a/macOS/GhostVMUITests/AppSettingsUITests.swift b/macOS/GhostVMUITests/AppSettingsUITests.swift
index 0323caf..6949462 100644
--- a/macOS/GhostVMUITests/AppSettingsUITests.swift
+++ b/macOS/GhostVMUITests/AppSettingsUITests.swift
@@ -35,6 +35,7 @@ final class AppSettingsUITests: XCTestCase {
             XCTAssertTrue(app.textFields["settings.ipswPathField"].waitForExistence(timeout: 3), "IPSW cache field should exist")
             XCTAssertTrue(app.textFields["settings.feedURLField"].waitForExistence(timeout: 3), "Feed URL field should exist")
             XCTAssertTrue(app.buttons["settings.verifyButton"].waitForExistence(timeout: 3), "Verify button should exist")
+            XCTAssertTrue(app.buttons["settings.fileSystemExtensionButton"].waitForExistence(timeout: 3), "File system extension setup button should exist")
         }
 
         XCTContext.runActivity(named: "App icon picker exists") { _ in
diff --git a/macOS/GhostVMUITests/CreateVMUITests.swift b/macOS/GhostVMUITests/CreateVMUITests.swift
index 079ebe6..e1712de 100644
--- a/macOS/GhostVMUITests/CreateVMUITests.swift
+++ b/macOS/GhostVMUITests/CreateVMUITests.swift
@@ -26,6 +26,8 @@ final class CreateVMUITests: XCTestCase {
         XCTAssertTrue(cpuField.waitForExistence(timeout: 3), "CPU field should exist")
         XCTAssertTrue(memoryField.exists, "Memory field should exist")
         XCTAssertTrue(diskField.exists, "Disk field should exist")
+        XCTAssertTrue(app.checkBoxes["createVM.hostContainersToggle"].exists,
+                      "Host containers setting should exist")
     }
 
     func testCancelDismissesSheet() {
diff --git a/macOS/GhostVMUITests/EditVMUITests.swift b/macOS/GhostVMUITests/EditVMUITests.swift
index 1f7c76a..0e5f27b 100644
--- a/macOS/GhostVMUITests/EditVMUITests.swift
+++ b/macOS/GhostVMUITests/EditVMUITests.swift
@@ -71,6 +71,8 @@ final class EditVMUITests: XCTestCase {
             XCTAssertEqual(memoryField.value as? String, "16", "Memory field should have mock value of 16")
             XCTAssertEqual(diskField.value as? String, "128", "Disk field should have mock value of 128")
             XCTAssertFalse(diskField.isEnabled, "Disk field should be read-only after VM creation")
+            XCTAssertTrue(app.checkBoxes["editVM.hostContainersToggle"].exists,
+                          "Host containers setting should exist")
         }
 
         XCTContext.runActivity(named: "Units and info banner") { _ in
diff --git a/macOS/GhostboxRuntimeTests/GhostboxContainerAPICommandsTests.swift b/macOS/GhostboxRuntimeTests/GhostboxContainerAPICommandsTests.swift
new file mode 100644
index 0000000..b457d27
--- /dev/null
+++ b/macOS/GhostboxRuntimeTests/GhostboxContainerAPICommandsTests.swift
@@ -0,0 +1,130 @@
+import Containerization
+import XCTest
+
+final class GhostboxContainerAPICommandsTests: XCTestCase {
+    func testMemorySizeLifecycleAndDuplicateName() async throws {
+        let session = GhostboxSession()
+        let commands = GhostboxContainerMemorySizeCommands()
+
+        let created = try await commands.handle(
+            method: .init(rawValue: "crMemorySize.create"),
+            parameters: ["memorySize": .string("limit"), "value": .string("512mb")],
+            session: session
+        )
+        XCTAssertEqual(created, .reference("@memory-size/limit"))
+        let formatted = try await commands.handle(
+            method: .init(rawValue: "crMemorySize.formatted"),
+            parameters: ["memorySize": .string("@memory-size/limit")],
+            session: session
+        )
+        XCTAssertEqual(formatted, .string("512mb"))
+        let bytes = try await commands.handle(
+            method: .init(rawValue: "crMemorySize.toUInt64"),
+            parameters: [
+                "memorySize": .string("@memory-size/limit"),
+                "unit": .string("bytes"),
+            ],
+            session: session
+        )
+        XCTAssertEqual(bytes, .unsignedInteger(536_870_912))
+
+        do {
+            _ = try await commands.handle(
+                method: .init(rawValue: "crMemorySize.create"),
+                parameters: ["memorySize": .string("limit"), "value": .string("1gb")],
+                session: session
+            )
+            XCTFail("Expected duplicate creation to fail")
+        } catch let error as DirectDispatchError {
+            XCTAssertEqual(error.code, .alreadyExists)
+        }
+    }
+
+    func testResourceLabelsAndParserUtilities() async throws {
+        let session = GhostboxSession()
+        let labels = GhostboxContainerResourceLabelsCommands()
+        let parser = GhostboxContainerParserCommands()
+
+        let created = try await labels.handle(
+            method: .init(rawValue: "crResourceLabels.create"),
+            parameters: [
+                "resourceLabels": .string("web"),
+                "label": .array([.string("app=ghost"), .string("tier=frontend")]),
+            ],
+            session: session
+        )
+        XCTAssertEqual(created, .reference("@resource-labels/web"))
+        let dictionary = try await labels.handle(
+            method: .init(rawValue: "crResourceLabels.dictionary"),
+            parameters: ["resourceLabels": .string("@resource-labels/web")],
+            session: session
+        )
+        XCTAssertEqual(dictionary, .object(["app": .string("ghost"), "tier": .string("frontend")]))
+        let missing = try await labels.handle(
+            method: .init(rawValue: "crResourceLabels.value"),
+            parameters: ["resourceLabels": .string("@resource-labels/web"), "key": .string("missing")],
+            session: session
+        )
+        XCTAssertEqual(missing, .null)
+        let memory = try await parser.handle(
+            method: .init(rawValue: "crParser.memoryAsMiB"),
+            parameters: ["memory": .string("2gb")],
+            session: session
+        )
+        XCTAssertEqual(memory, .integer(2_048))
+        let parsedLabels = try await parser.handle(
+            method: .init(rawValue: "crParser.labels"),
+            parameters: ["label": .array([.string("one=1"), .string("two=2")])],
+            session: session
+        )
+        XCTAssertEqual(parsedLabels, .object(["one": .string("1"), "two": .string("2")]))
+        let parsedBool = try await parser.handle(
+            method: .init(rawValue: "crParser.parseBool"),
+            parameters: ["value": .string("invalid")],
+            session: session
+        )
+        XCTAssertEqual(parsedBool, .null)
+    }
+
+    func testPersistentVolumeMountUsesContainerCachingPolicy() async throws {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ghostbox-volume-tests-\(UUID().uuidString)", isDirectory: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+        let store = GhostboxVolumeStore(rootURL: root)
+
+        let metadata = try await store.create(name: "data", sizeInBytes: GhostboxVolumeStore.minimumSize)
+        XCTAssertEqual(metadata.name, "data")
+        let listed = try await store.list()
+        XCTAssertEqual(listed.map(\.name), ["data"])
+        let inspected = try await store.inspect(name: "data")
+        XCTAssertEqual(inspected.sizeInBytes, GhostboxVolumeStore.minimumSize)
+
+        let mount = try await store.makeMount(
+            volumeName: "data",
+            mountReference: "@mount/data",
+            destination: "/var/lib/data",
+            readOnly: true
+        )
+        XCTAssertEqual(mount.options, ["ro"])
+        guard case .virtioblk(let options) = mount.runtimeOptions else {
+            return XCTFail("Expected a virtio block mount")
+        }
+        XCTAssertEqual(Set(options), [
+            "vzDiskImageCachingMode=cached",
+            "vzDiskImageSynchronizationMode=fsync",
+        ])
+        let redactedSource = await store.redactedSource(for: "@mount/data")
+        XCTAssertEqual(redactedSource, "@volume/data")
+
+        do {
+            try await store.delete(name: "data")
+            XCTFail("Expected a leased volume to reject deletion")
+        } catch let error as DirectDispatchError {
+            XCTAssertEqual(error.code, .failedPrecondition)
+        }
+        await store.releaseMount("@mount/data")
+        try await store.delete(name: "data")
+        let remaining = try await store.list()
+        XCTAssertTrue(remaining.isEmpty)
+    }
+}
diff --git a/macOS/project.yml b/macOS/project.yml
index d402b51..f9680e6 100644
--- a/macOS/project.yml
+++ b/macOS/project.yml
@@ -2,8 +2,8 @@ name: GhostVM
 options:
   bundleIdPrefix: org.ghostvm
   deploymentTarget:
-    macOS: "15.0"
-  xcodeVersion: "15.4"
+    macOS: "26.0"
+  xcodeVersion: "26.0"
 
 packages:
   Sparkle:
@@ -11,6 +11,18 @@ packages:
     from: "2.6.0"
   GhostHTTP:
     path: ../Packages/GhostHTTP
+  SwiftCertificates:
+    url: https://github.com/apple/swift-certificates.git
+    from: "1.19.4"
+  SwiftCrypto:
+    url: https://github.com/apple/swift-crypto.git
+    from: "3.15.1"
+  Containerization:
+    url: https://github.com/apple/containerization.git
+    exactVersion: "0.40.1"
+  AppleContainer:
+    url: https://github.com/apple/container.git
+    exactVersion: "1.2.0"
 
 settings:
   base:
@@ -32,8 +44,203 @@ schemes:
     test:
       targets:
         - GhostVMTests
+  GhostboxRuntimeTests:
+    build:
+      targets:
+        GhostboxRuntimeTests: test
+    test:
+      targets:
+        - GhostboxRuntimeTests
+  GhostFile:
+    build:
+      targets:
+        GhostFile: all
+    run:
+      config: Debug
+  GhostFileTests:
+    build:
+      targets:
+        GhostFileTests: test
+    test:
+      targets:
+        - GhostFileTests
+
+aggregateTargets:
+  GhostHTTP3Framework:
+    settings:
+      base:
+        PRODUCT_NAME: GhostHTTP3Framework
+    buildScripts:
+      - name: Build GhostHTTP3 arm64 framework
+        runOnlyWhenInstalling: false
+        showEnvVars: false
+        outputFiles:
+          - $(SRCROOT)/GhostHTTP3/.build/artifacts/GhostHTTP3.framework/Versions/A/GhostHTTP3
+        script: |
+          set -euo pipefail
+          "${SRCROOT}/GhostHTTP3/scripts/ensure-framework.sh"
 
 targets:
+  GhostFileKit:
+    type: framework
+    platform: macOS
+    deploymentTarget: "26.0"
+    sources:
+      - path: GhostFileKit
+    dependencies:
+      - package: GhostHTTP
+      - package: SwiftCertificates
+        product: X509
+      - package: SwiftCrypto
+        product: Crypto
+      - sdk: Network.framework
+      - sdk: Security.framework
+      - sdk: FSKit.framework
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        link: true
+        embed: false
+    settings:
+      base:
+        PRODUCT_NAME: GhostFileKit
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostfilekit
+        SKIP_INSTALL: YES
+        GENERATE_INFOPLIST_FILE: YES
+        DEFINES_MODULE: YES
+        SWIFT_ACTIVE_COMPILATION_CONDITIONS: "$(inherited) GHOSTFILEKIT_BUILD"
+        SWIFT_VERSION: "5.0"
+        DYLIB_INSTALL_NAME_BASE: "@rpath"
+        CODE_SIGN_STYLE: Automatic
+        CODE_SIGN_IDENTITY: "Apple Development"
+        DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
+        ENABLE_HARDENED_RUNTIME: YES
+
+  GhostFileFS:
+    type: extensionkit-extension
+    platform: macOS
+    deploymentTarget: "26.0"
+    sources:
+      - path: GhostFileFS/FileSystemExtension.swift
+    dependencies:
+      - target: GhostFileKit
+        embed: true
+      - package: GhostHTTP
+        embed: true
+      - sdk: FSKit.framework
+      - sdk: ExtensionFoundation.framework
+      - sdk: Network.framework
+      - sdk: Security.framework
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        embed: true
+        codeSign: true
+    settings:
+      base:
+        PRODUCT_NAME: GhostFileFS
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostfile.fs
+        SKIP_INSTALL: YES
+        INFOPLIST_FILE: GhostFileFS/Info.plist
+        GENERATE_INFOPLIST_FILE: NO
+        CODE_SIGN_ENTITLEMENTS: GhostFileFS/entitlements.plist
+        CODE_SIGN_STYLE: Automatic
+        CODE_SIGN_IDENTITY: "Apple Development"
+        DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
+        MARKETING_VERSION: 1.0.20260801211105
+        CURRENT_PROJECT_VERSION: 18
+        ENABLE_APP_SANDBOX: YES
+        ENABLE_HARDENED_RUNTIME: YES
+        SWIFT_VERSION: "5.0"
+        LD_RUNPATH_SEARCH_PATHS:
+          - "$(inherited)"
+          - "@executable_path/../Frameworks"
+
+  GhostFile:
+    type: application
+    platform: macOS
+    deploymentTarget: "26.0"
+    sources:
+      - path: GhostFile
+        excludes:
+          - "*.plist"
+    dependencies:
+      - target: GhostFileKit
+        embed: true
+      - sdk: FSKit.framework
+      - sdk: Network.framework
+      - sdk: Security.framework
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        embed: true
+        codeSign: true
+      - target: GhostFileFS
+        embed: true
+        codeSign: true
+    settings:
+      base:
+        PRODUCT_NAME: GhostFile
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostfile
+        MARKETING_VERSION: 1.0.20260801211105
+        CURRENT_PROJECT_VERSION: 18
+        SKIP_INSTALL: NO
+        INFOPLIST_FILE: GhostFile/Info.plist
+        GENERATE_INFOPLIST_FILE: NO
+        CODE_SIGN_ENTITLEMENTS: GhostFile/entitlements.plist
+        CODE_SIGN_STYLE: Automatic
+        CODE_SIGN_IDENTITY: "Apple Development"
+        DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
+        ASSETCATALOG_COMPILER_APPICON_NAME: GhostFile
+        ENABLE_APP_SANDBOX: NO
+        ENABLE_HARDENED_RUNTIME: YES
+        SWIFT_VERSION: "5.0"
+        SWIFT_EMIT_LOC_STRINGS: NO
+        LD_RUNPATH_SEARCH_PATHS:
+          - "$(inherited)"
+          - "@executable_path/../Frameworks"
+      configs:
+        Debug:
+          ONLY_ACTIVE_ARCH: YES
+    postBuildScripts:
+      - name: Build Complete Legacy App Icon
+        basedOnDependencyAnalysis: false
+        showEnvVars: false
+        script: |
+          set -euo pipefail
+          RESOURCES="${TARGET_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}"
+          ASSET_CATALOG="${RESOURCES}/Assets.car"
+          LEGACY_ICON="${RESOURCES}/GhostFile.icns"
+          test -f "${ASSET_CATALOG}"
+          ICON_WORK_DIR="$(mktemp -d "${TMPDIR%/}/ghostfile-icon.XXXXXX")"
+          trap 'rm -r "${ICON_WORK_DIR}"' EXIT
+          /usr/bin/iconutil -c iconset \
+            -o "${ICON_WORK_DIR}/GhostFile.iconset" \
+            "${ASSET_CATALOG}" GhostFile
+          /usr/bin/iconutil -c icns \
+            -o "${LEGACY_ICON}" \
+            "${ICON_WORK_DIR}/GhostFile.iconset"
+
+  GhostFileTests:
+    type: bundle.unit-test
+    platform: macOS
+    sources:
+      - path: GhostFileTests
+    dependencies:
+      - target: GhostFile
+      - target: GhostFileKit
+      - package: GhostHTTP
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        link: true
+        embed: false
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostfile.tests
+        GENERATE_INFOPLIST_FILE: YES
+        SWIFT_VERSION: "5.0"
+        LD_RUNPATH_SEARCH_PATHS:
+          - "$(inherited)"
+          - "@loader_path/../../../../../Frameworks"
+          - "@loader_path/Frameworks"
+
   GhostVMKit:
     type: framework
     platform: macOS
@@ -45,6 +252,7 @@ targets:
       base:
         PRODUCT_NAME: GhostVMKit
         PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostvmkit
+        SKIP_INSTALL: YES
         GENERATE_INFOPLIST_FILE: YES
         DEFINES_MODULE: YES
         SWIFT_VERSION: "5.0"
@@ -74,6 +282,7 @@ targets:
       base:
         PRODUCT_NAME: vmctl
         PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.vmctl
+        SKIP_INSTALL: YES
         GENERATE_INFOPLIST_FILE: YES
         INFOPLIST_KEY_LSBackgroundOnly: YES
         SWIFT_VERSION: "5.0"
@@ -104,13 +313,28 @@ targets:
         type: resource
         buildPhase: resources
     dependencies:
+      - target: GhostFileKit
+        embed: true
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        embed: true
+        codeSign: true
       - target: GhostVMKit
         embed: true
       - package: GhostHTTP
+      - target: GhostVMContainerRuntime
+        embed: true
+        codeSign: true
+      - target: GhostVMImageFetch
+        codeSign: true
+        copy:
+          destination: wrapper
+          subpath: Contents/Helpers
     settings:
       base:
         PRODUCT_NAME: GhostVMHelper
         PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostvm.helper
+        SKIP_INSTALL: YES
         INFOPLIST_FILE: ../build/generated-plists/GhostVMHelper-Info.plist
         GENERATE_INFOPLIST_FILE: NO
         SWIFT_VERSION: "5.0"
@@ -119,8 +343,152 @@ targets:
         CODE_SIGN_IDENTITY: "Apple Development"
         DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
         ENABLE_HARDENED_RUNTIME: YES
+        EMBEDDED_CONTENT_CONTAINS_SWIFT: YES
         LD_RUNPATH_SEARCH_PATHS:
           - "@executable_path/../Frameworks"
+    postBuildScripts:
+      - name: Embed Container Helper Swift Libraries
+        basedOnDependencyAnalysis: false
+        script: |
+          SWIFT_STDLIB_TOOL="${TOOLCHAIN_DIR}/usr/bin/swift-stdlib-tool"
+          RUNTIME="${TARGET_BUILD_DIR}/${CONTENTS_FOLDER_PATH}/XPCServices/ghostvm-container-runtime.xpc/Contents/MacOS/ghostvm-container-runtime"
+          FETCHER="${TARGET_BUILD_DIR}/${CONTENTS_FOLDER_PATH}/Helpers/ghostvm-image-fetch"
+          FRAMEWORKS="${TARGET_BUILD_DIR}/${CONTENTS_FOLDER_PATH}/Frameworks"
+          mkdir -p "${FRAMEWORKS}"
+          for CANDIDATE in "${TOOLCHAIN_DIR}"/usr/lib/swift-*/macosx; do
+            if [ -f "${CANDIDATE}/libswiftCompatibilitySpan.dylib" ]; then
+              SWIFT_LIBS="${CANDIDATE}"
+            fi
+          done
+          test -n "${SWIFT_LIBS:-}"
+          if [ -n "${EXPANDED_CODE_SIGN_IDENTITY:-}" ]; then
+            "${SWIFT_STDLIB_TOOL}" --copy --scan-executable "${RUNTIME}" --scan-executable "${FETCHER}" --platform "${PLATFORM_NAME}" --source-libraries "${SWIFT_LIBS}" --destination "${FRAMEWORKS}" --sign "${EXPANDED_CODE_SIGN_IDENTITY}"
+          else
+            "${SWIFT_STDLIB_TOOL}" --copy --scan-executable "${RUNTIME}" --scan-executable "${FETCHER}" --platform "${PLATFORM_NAME}" --source-libraries "${SWIFT_LIBS}" --destination "${FRAMEWORKS}"
+          fi
+          rm -f "${FRAMEWORKS}/libswiftCompatibilitySpan.dylib.original"
+
+  GhostVMContainerRuntime:
+    type: xpc-service
+    platform: macOS
+    sources:
+      - path: GhostVMContainerRuntime
+        excludes:
+          - "Info.plist"
+          - "entitlements.plist"
+    dependencies:
+      - target: GhostVMKit
+        link: true
+        embed: false
+      - package: AppleContainer
+        product: ContainerBuild
+      - package: AppleContainer
+        product: ContainerAPIClient
+      - package: AppleContainer
+        product: ContainerAPIService
+      - package: AppleContainer
+        product: ContainerPlugin
+      - package: AppleContainer
+        product: ContainerPersistence
+      - package: AppleContainer
+        product: ContainerResource
+      - package: Containerization
+        product: Containerization
+      - package: Containerization
+        product: ContainerizationArchive
+      - package: Containerization
+        product: ContainerizationOCI
+      - package: Containerization
+        product: ContainerizationOS
+      - package: Containerization
+        product: ContainerizationExtras
+      - package: Containerization
+        product: ContainerizationEXT4
+    settings:
+      base:
+        PRODUCT_NAME: ghostvm-container-runtime
+        # Provisioning constraint: the runtime reuses the helper's
+        # org.ghostvm.ghostvm.helper application identifier / vmnet Developer ID
+        # provisioning profile (already authorized) as a deliberate duplicate
+        # identity for this testable DMG. Do not change without a new profile.
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostvm.helper
+        SKIP_INSTALL: YES
+        INFOPLIST_FILE: GhostVMContainerRuntime/Info.plist
+        GENERATE_INFOPLIST_FILE: NO
+        SWIFT_VERSION: "6.0"
+        CODE_SIGN_ENTITLEMENTS: GhostVMContainerRuntime/entitlements.plist
+        CODE_SIGN_STYLE: Automatic
+        CODE_SIGN_IDENTITY: "Apple Development"
+        DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
+        ENABLE_HARDENED_RUNTIME: YES
+        LD_RUNPATH_SEARCH_PATHS:
+          - "@executable_path/../Frameworks"
+          - "@executable_path/../../../../Frameworks"
+
+  GhostVMImageFetch:
+    type: tool
+    platform: macOS
+    sources:
+      - path: GhostVMImageFetch
+    dependencies:
+      - package: Containerization
+        product: Containerization
+      - package: Containerization
+        product: ContainerizationArchive
+      - package: Containerization
+        product: ContainerizationExtras
+      - package: Containerization
+        product: ContainerizationOCI
+    settings:
+      base:
+        PRODUCT_NAME: ghostvm-image-fetch
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.image-fetch
+        SKIP_INSTALL: YES
+        SWIFT_VERSION: "6.0"
+        CODE_SIGN_STYLE: Automatic
+        CODE_SIGN_IDENTITY: "Apple Development"
+        DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
+        ENABLE_HARDENED_RUNTIME: YES
+        LD_RUNPATH_SEARCH_PATHS:
+          - "@executable_path/Frameworks"
+          - "@executable_path/../Frameworks"
+
+  GhostVMFS:
+    type: extensionkit-extension
+    platform: macOS
+    deploymentTarget: "26.0"
+    sources:
+      - path: GhostVMFS/FileSystemExtension.swift
+    dependencies:
+      - target: GhostFileKit
+        embed: true
+      - package: GhostHTTP
+        embed: true
+      - sdk: FSKit.framework
+      - sdk: ExtensionFoundation.framework
+      - sdk: Network.framework
+      - sdk: Security.framework
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        embed: true
+        codeSign: true
+    settings:
+      base:
+        PRODUCT_NAME: GhostVMFS
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostvm.fs
+        SKIP_INSTALL: YES
+        INFOPLIST_FILE: ../build/generated-plists/GhostVMFS-Info.plist
+        GENERATE_INFOPLIST_FILE: NO
+        CODE_SIGN_ENTITLEMENTS: GhostVMFS/entitlements.plist
+        CODE_SIGN_STYLE: Automatic
+        CODE_SIGN_IDENTITY: "Apple Development"
+        DEVELOPMENT_TEAM: ${DEVELOPMENT_TEAM}
+        ENABLE_APP_SANDBOX: YES
+        ENABLE_HARDENED_RUNTIME: YES
+        SWIFT_VERSION: "5.0"
+        LD_RUNPATH_SEARCH_PATHS:
+          - "$(inherited)"
+          - "@executable_path/../Frameworks"
 
   GhostVM:
     type: application
@@ -135,6 +503,12 @@ targets:
       - path: build/xcode/GhostTools.dmg
         optional: true
     dependencies:
+      - target: GhostFileKit
+        embed: true
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        embed: true
+        codeSign: true
       - target: GhostVMKit
         embed: true
       - package: GhostHTTP
@@ -150,11 +524,15 @@ targets:
         copy:
           destination: plugins
           subpath: Helpers
+      - target: GhostVMFS
+        embed: true
+        codeSign: true
       - package: Sparkle
     settings:
       base:
         PRODUCT_NAME: GhostVM
         PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostvm
+        SKIP_INSTALL: NO
         INFOPLIST_FILE: ../build/generated-plists/GhostVM-Info.plist
         CODE_SIGN_ENTITLEMENTS: GhostVM/entitlements.plist
         CODE_SIGN_STYLE: Automatic
@@ -174,7 +552,20 @@ targets:
     platform: macOS
     sources:
       - path: GhostVMTests
+      - path: GhostVM/Services/GuestFileSystemBridgeService.swift
+      - path: GhostVM/Services/GuestMountRegistry.swift
+      - path: GhostVM/Services/GuestPathProvider.swift
+      - path: GhostVM/Services/GhostVMFSExtensionManager.swift
+      - path: GhostVMContainerRuntime/GhostboxCoreArguments.swift
+      - path: GhostVMContainerRuntime/GhostboxCoreSession.swift
+      - path: GhostVMContainerRuntime/GhostboxAttachmentReadiness.swift
     dependencies:
+      - target: GhostFileKit
+        embed: true
+      - target: GhostHTTP3Framework
+      - framework: GhostHTTP3/.build/artifacts/GhostHTTP3.framework
+        embed: true
+        codeSign: false
       - target: GhostVMKit
     settings:
       base:
@@ -182,6 +573,35 @@ targets:
         GENERATE_INFOPLIST_FILE: YES
         SWIFT_VERSION: "5.0"
 
+  GhostboxRuntimeTests:
+    type: bundle.unit-test
+    platform: macOS
+    sources:
+      - path: GhostboxRuntimeTests
+      - path: GhostVMContainerRuntime/GhostboxCoreArguments.swift
+      - path: GhostVMContainerRuntime/GhostboxCoreSession.swift
+      - path: GhostVMContainerRuntime/Ghostbox/GhostboxSupport.swift
+      - path: GhostVMContainerRuntime/Ghostbox/GhostboxParameters.swift
+      - path: GhostVMContainerRuntime/Ghostbox/GhostboxContainerAPICommands.swift
+      - path: GhostVMContainerRuntime/Ghostbox/GhostboxVolumeCommands.swift
+    dependencies:
+      - target: GhostVMKit
+      - package: AppleContainer
+        product: ContainerAPIClient
+      - package: AppleContainer
+        product: ContainerPersistence
+      - package: AppleContainer
+        product: ContainerResource
+      - package: Containerization
+        product: Containerization
+      - package: Containerization
+        product: ContainerizationEXT4
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: org.ghostvm.ghostbox-runtime.tests
+        GENERATE_INFOPLIST_FILE: YES
+        SWIFT_VERSION: "6.0"
+
   GhostVMUITests:
     type: bundle.ui-testing
     platform: macOS
diff --git a/scripts/benchmark-ghostfile-tree.py b/scripts/benchmark-ghostfile-tree.py
new file mode 100755
index 0000000..2b0f6d6
--- /dev/null
+++ b/scripts/benchmark-ghostfile-tree.py
@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+
+import argparse
+import os
+import statistics
+import time
+
+
+def inventory(root):
+    files = []
+    directories = []
+    for current, directory_names, file_names in os.walk(root):
+        relative_directory = os.path.relpath(current, root)
+        directories.append(relative_directory)
+        files.extend(
+            os.path.join(relative_directory, name) if relative_directory != "." else name
+            for name in file_names
+        )
+        directory_names.sort()
+        file_names.sort()
+    return sorted(files), sorted(directories)
+
+
+def timed(operation):
+    started = time.perf_counter()
+    result = operation()
+    return time.perf_counter() - started, result
+
+
+def benchmark_pair(native_operation, mounted_operation, samples):
+    durations = {"native": [], "fskit": []}
+    results = {"native": [], "fskit": []}
+    operations = {"native": native_operation, "fskit": mounted_operation}
+    for sample in range(samples):
+        order = ("native", "fskit") if sample % 2 == 0 else ("fskit", "native")
+        for label in order:
+            duration, result = timed(operations[label])
+            durations[label].append(duration)
+            results[label].append(result)
+    return durations, results
+
+
+def print_rate(label, durations, operation_count, unit="ops/s"):
+    native_rate = operation_count / statistics.median(durations["native"])
+    fskit_rate = operation_count / statistics.median(durations["fskit"])
+    print(
+        f"{label}: native={native_rate:.1f} {unit} "
+        f"fskit={fskit_rate:.1f} {unit} ratio={fskit_rate / native_rate:.3f}x"
+    )
+
+
+def read_files(root, relative_paths):
+    byte_count = 0
+    checksum = 0
+    for relative_path in relative_paths:
+        with open(os.path.join(root, relative_path), "rb", buffering=0) as stream:
+            contents = stream.read()
+        byte_count += len(contents)
+        checksum = (checksum + sum(contents)) & 0xFFFFFFFF
+    return byte_count, checksum
+
+
+def stat_files(root, relative_paths):
+    return sum(os.stat(os.path.join(root, path)).st_size for path in relative_paths)
+
+
+def list_directories(root, relative_paths):
+    entry_count = 0
+    for relative_path in relative_paths:
+        path = root if relative_path == "." else os.path.join(root, relative_path)
+        with os.scandir(path) as entries:
+            entry_count += sum(1 for _ in entries)
+    return entry_count
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Compare native and GhostFile FSKit file-tree operation rates"
+    )
+    parser.add_argument("native_root")
+    parser.add_argument("mounted_root")
+    parser.add_argument("--samples", type=int, default=3)
+    parser.add_argument("--small-file-ops", type=int, default=2048)
+    parser.add_argument("--stat-ops", type=int, default=8192)
+    parser.add_argument("--directory-ops", type=int, default=2048)
+    args = parser.parse_args()
+
+    native_files, native_directories = inventory(args.native_root)
+    mounted_files, mounted_directories = inventory(args.mounted_root)
+    if native_files != mounted_files or native_directories != mounted_directories:
+        raise SystemExit("native and mounted tree inventories differ")
+
+    print(f"tree_files={len(native_files)} tree_directories={len(native_directories)}")
+    entry_count = len(native_files) + len(native_directories)
+    walk_durations, walk_results = benchmark_pair(
+        lambda: inventory(args.native_root),
+        lambda: inventory(args.mounted_root),
+        args.samples,
+    )
+    if any(result != walk_results["native"][0] for values in walk_results.values() for result in values):
+        raise SystemExit("tree inventory changed during benchmark")
+    print_rate("recursive tree enumeration", walk_durations, entry_count, "entries/s")
+
+    stat_paths = [native_files[index % len(native_files)] for index in range(args.stat_ops)]
+    stat_durations, stat_results = benchmark_pair(
+        lambda: stat_files(args.native_root, stat_paths),
+        lambda: stat_files(args.mounted_root, stat_paths),
+        args.samples,
+    )
+    if len(set(stat_results["native"] + stat_results["fskit"])) != 1:
+        raise SystemExit("stat size totals differ")
+    print_rate("small-file stat", stat_durations, len(stat_paths), "IOPS")
+
+    read_paths = native_files[: min(args.small_file_ops, len(native_files))]
+    read_durations, read_results = benchmark_pair(
+        lambda: read_files(args.native_root, read_paths),
+        lambda: read_files(args.mounted_root, read_paths),
+        args.samples,
+    )
+    if len(set(read_results["native"] + read_results["fskit"])) != 1:
+        raise SystemExit("small-file contents differ")
+    print_rate("open + read small files", read_durations, len(read_paths), "IOPS")
+    byte_count = read_results["native"][0][0]
+    native_mib = byte_count / statistics.median(read_durations["native"]) / (1024 * 1024)
+    fskit_mib = byte_count / statistics.median(read_durations["fskit"]) / (1024 * 1024)
+    print(
+        f"small-file payload throughput: native={native_mib:.2f} MiB/s "
+        f"fskit={fskit_mib:.2f} MiB/s ratio={fskit_mib / native_mib:.3f}x"
+    )
+
+    directory_paths = [
+        native_directories[index % len(native_directories)] for index in range(args.directory_ops)
+    ]
+    directory_durations, directory_results = benchmark_pair(
+        lambda: list_directories(args.native_root, directory_paths),
+        lambda: list_directories(args.mounted_root, directory_paths),
+        args.samples,
+    )
+    if len(set(directory_results["native"] + directory_results["fskit"])) != 1:
+        raise SystemExit("directory entry totals differ")
+    print_rate("directory listing", directory_durations, len(directory_paths), "IOPS")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/benchmark-ghostfile.py b/scripts/benchmark-ghostfile.py
new file mode 100755
index 0000000..7ec272c
--- /dev/null
+++ b/scripts/benchmark-ghostfile.py
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+
+import argparse
+import fcntl
+import hashlib
+import os
+import random
+import statistics
+import time
+
+
+F_NOCACHE = getattr(fcntl, "F_NOCACHE", 48)
+CHUNK_SIZE = 1024 * 1024
+
+
+def timed(operation):
+    started = time.perf_counter()
+    result = operation()
+    return time.perf_counter() - started, result
+
+
+def read_sequential(path, uncached):
+    total = 0
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        if uncached:
+            fcntl.fcntl(descriptor, F_NOCACHE, 1)
+        while True:
+            chunk = os.read(descriptor, CHUNK_SIZE)
+            if not chunk:
+                break
+            total += len(chunk)
+    finally:
+        os.close(descriptor)
+    return total
+
+
+def read_random(path, offsets, uncached):
+    digest = hashlib.sha256()
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        if uncached:
+            fcntl.fcntl(descriptor, F_NOCACHE, 1)
+        for offset in offsets:
+            digest.update(os.pread(descriptor, 4096, offset))
+    finally:
+        os.close(descriptor)
+    return digest.digest()
+
+
+def benchmark_pair(source_path, mount_path, samples, operation):
+    durations = {"regular": [], "fskit": []}
+    results = {"regular": [], "fskit": []}
+    paths = {"regular": source_path, "fskit": mount_path}
+    for sample in range(samples):
+        order = ("regular", "fskit") if sample % 2 == 0 else ("fskit", "regular")
+        for label in order:
+            duration, result = timed(lambda label=label: operation(paths[label]))
+            durations[label].append(duration)
+            results[label].append(result)
+    return durations, results
+
+
+def print_throughput(label, durations, byte_count):
+    source_seconds = statistics.median(durations["regular"])
+    mount_seconds = statistics.median(durations["fskit"])
+    mib = byte_count / (1024 * 1024)
+    source_rate = mib / source_seconds
+    mount_rate = mib / mount_seconds
+    print(
+        f"{label}: regular={source_rate:.1f} MiB/s "
+        f"fskit={mount_rate:.1f} MiB/s ratio={mount_rate / source_rate:.3f}x"
+    )
+
+
+def print_latency(label, durations, operations_per_sample):
+    source_us = statistics.median(durations["regular"]) * 1_000_000 / operations_per_sample
+    mount_us = statistics.median(durations["fskit"]) * 1_000_000 / operations_per_sample
+    print(
+        f"{label}: regular={source_us:.1f} us/op "
+        f"fskit={mount_us:.1f} us/op ratio={mount_us / source_us:.2f}x"
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Compare regular file I/O with a GhostFile FSKit mount")
+    parser.add_argument("source_file")
+    parser.add_argument("mounted_file")
+    parser.add_argument("--samples", type=int, default=5)
+    parser.add_argument("--random-reads", type=int, default=1000)
+    parser.add_argument("--metadata-ops", type=int, default=5000)
+    parser.add_argument("--directory-ops", type=int, default=2000)
+    parser.add_argument(
+        "--sequential-only",
+        action="store_true",
+        help="time only the first F_NOCACHE sequential read (useful with a fresh file identity)",
+    )
+    args = parser.parse_args()
+
+    source_size = os.path.getsize(args.source_file)
+    mount_size = os.path.getsize(args.mounted_file)
+    if source_size != mount_size:
+        raise SystemExit(f"size mismatch: regular={source_size} fskit={mount_size}")
+
+    print(f"file_size={source_size / (1024 * 1024):.1f} MiB samples={args.samples}")
+
+    if not args.sequential_only:
+        randomizer = random.Random(0x47484F535446494C)
+        max_offset = max(0, source_size - 4096)
+        offsets = [randomizer.randrange(0, max_offset + 1) for _ in range(args.random_reads)]
+        random_durations, random_results = benchmark_pair(
+            args.source_file,
+            args.mounted_file,
+            args.samples,
+            lambda path: read_random(path, offsets, True),
+        )
+        if len(set(random_results["regular"] + random_results["fskit"])) != 1:
+            raise SystemExit("random-read digest mismatch")
+        print_latency("random 4 KiB reads (F_NOCACHE)", random_durations, args.random_reads)
+
+    sequential_durations, sequential_results = benchmark_pair(
+        args.source_file,
+        args.mounted_file,
+        args.samples,
+        lambda path: read_sequential(path, True),
+    )
+    sequential_totals = sequential_results["regular"] + sequential_results["fskit"]
+    if set(sequential_totals) != {source_size}:
+        raise SystemExit("sequential-read length mismatch")
+    print_throughput("sequential reads (F_NOCACHE)", sequential_durations, source_size)
+
+    if args.sequential_only:
+        return
+
+    cached_durations, cached_results = benchmark_pair(
+        args.source_file,
+        args.mounted_file,
+        args.samples,
+        lambda path: read_sequential(path, False),
+    )
+    cached_totals = cached_results["regular"] + cached_results["fskit"]
+    if set(cached_totals) != {source_size}:
+        raise SystemExit("cached sequential-read length mismatch")
+    print_throughput("sequential reads (warm cache)", cached_durations, source_size)
+
+    source_directory = os.path.dirname(args.source_file)
+    mount_directory = os.path.dirname(args.mounted_file)
+    metadata_durations, _ = benchmark_pair(
+        args.source_file,
+        args.mounted_file,
+        args.samples,
+        lambda path: [os.stat(path) for _ in range(args.metadata_ops)],
+    )
+    print_latency("stat", metadata_durations, args.metadata_ops)
+
+    directory_durations, directory_results = benchmark_pair(
+        source_directory,
+        mount_directory,
+        args.samples,
+        lambda path: [tuple(sorted(entry.name for entry in os.scandir(path))) for _ in range(args.directory_ops)],
+    )
+    if directory_results["regular"][-1][-1] != directory_results["fskit"][-1][-1]:
+        raise SystemExit("directory listing mismatch")
+    print_latency("readdir", directory_durations, args.directory_ops)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/enable-ghostfile-fskit.sh b/scripts/enable-ghostfile-fskit.sh
new file mode 100755
index 0000000..acffcbd
--- /dev/null
+++ b/scripts/enable-ghostfile-fskit.sh
@@ -0,0 +1,50 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+readonly app_path="${1:-/Applications/GhostFile.app}"
+readonly extension_path="$app_path/Contents/Extensions/GhostFileFS.appex"
+readonly settings_path="$HOME/Library/Group Containers/group.com.apple.fskit.settings/enabledModules.plist"
+readonly lsregister_path="/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister"
+
+if [[ ! -d "$extension_path" ]]; then
+    print -u2 "GhostFile FSKit extension not found at: $extension_path"
+    exit 66
+fi
+
+readonly bundle_id="$(/usr/bin/plutil -extract CFBundleIdentifier raw "$extension_path/Contents/Info.plist")"
+if [[ "$bundle_id" != "org.ghostvm.ghostfile.fs" ]]; then
+    print -u2 "Unexpected FSKit bundle identifier: $bundle_id"
+    exit 65
+fi
+
+echo "Verifying GhostFile signature…"
+/usr/bin/codesign --verify --deep --strict "$app_path"
+
+echo "Registering and selecting $bundle_id…"
+"$lsregister_path" -f "$app_path"
+/usr/bin/pluginkit -e use -i "$bundle_id"
+
+if [[ ! -f "$settings_path" ]]; then
+    /bin/mkdir -p "${settings_path:h}"
+    /usr/libexec/PlistBuddy -c "Add : array" "$settings_path"
+fi
+
+if ! /usr/bin/plutil -p "$settings_path" | /usr/bin/grep -Fq "\"$bundle_id\""; then
+    readonly module_count="$(/usr/bin/plutil -p "$settings_path" | /usr/bin/awk '/^[[:space:]]+[0-9]+ => / { count++ } END { print count + 0 }')"
+    /usr/bin/plutil -insert "$module_count" -string "$bundle_id" "$settings_path"
+fi
+
+echo "Restarting the stale FSKit daemon (administrator password required)…"
+/usr/bin/sudo /usr/bin/killall fskitd 2>/dev/null || true
+/usr/bin/killall fskit_agent 2>/dev/null || true
+/bin/sleep 2
+
+echo
+echo "FSKit registration:"
+/usr/bin/pluginkit -v -m -A -D -p com.apple.fskit.fsmodule | /usr/bin/grep -F "$bundle_id" || true
+echo
+echo "Enabled module list:"
+/usr/bin/plutil -p "$settings_path"
+echo
+echo "GhostFile FSKit recovery complete. Reopen GhostFile and switch to Mount."
diff --git a/scripts/generate-ghostbox-command-catalog.py b/scripts/generate-ghostbox-command-catalog.py
new file mode 100755
index 0000000..42523c6
--- /dev/null
+++ b/scripts/generate-ghostbox-command-catalog.py
@@ -0,0 +1,1084 @@
+#!/usr/bin/env python3
+
+"""Validate the Ghostbox command catalog and generate its Swift representation."""
+
+import argparse
+import copy
+import html
+import json
+import re
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent.parent
+CN_TEMPLATE_PATH = ROOT / "GHOSTBOX_CLI_TEMPLATE.md"
+CR_TEMPLATE_PATH = ROOT / "GHOSTBOX_CR_CLI_TEMPLATE.md"
+CATALOG_PATH = ROOT / "GHOSTBOX_CLI_COMMANDS.json"
+API_DOCS_DIR = ROOT / "docs/ghostbox-api"
+GENERATED_DIR = ROOT / "macOS/GhostTools/Sources/ghostbox/Generated"
+GENERATED_CATALOG_PATH = GENERATED_DIR / "GhostboxCommandCatalog.generated.swift"
+GENERATED_FIXTURES_PATH = GENERATED_DIR / "GhostboxCommandFixtures.generated.swift"
+RUNTIME_HANDLER_DIR = ROOT / "macOS/GhostVMContainerRuntime/Ghostbox"
+RUNTIME_METHOD_PATH = ROOT / "macOS/GhostVMKit/Containers/GhostboxDirectProtocol.swift"
+EXPECTED_ENTRY_COUNT = 282
+EXPECTED_RESOURCE_COUNT = 39
+OVERRIDE_GROUP = "containerConfigOverride"
+ACRONYMS = {
+    "id": "ID",
+    "oci": "OCI",
+    "vmm": "VMM",
+    "dns": "DNS",
+    "cpus": "CPUs",
+    "mib": "MiB",
+    "uint64": "UInt64",
+}
+METHOD_ID_RE = re.compile(r"^[a-z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*$")
+COMMAND_ID_RE = re.compile(
+    r"^(?Pcn|cr):(?P[a-z][a-z0-9-]*):(?P[a-z][a-z0-9-]*)$"
+)
+NAMESPACES = {
+    "cn": {
+        "name": "containerization",
+        "aliases": ["containerization"],
+        "source": CN_TEMPLATE_PATH.name,
+        "repository": "https://github.com/apple/containerization",
+        "version": "0.40.1",
+        "revision": "7800b4642171561c95b5f55500b19e5dce5acd45",
+    },
+    "cr": {
+        "name": "container",
+        "aliases": ["container"],
+        "source": CR_TEMPLATE_PATH.name,
+        "repository": "https://github.com/apple/container",
+        "version": "1.2.0",
+        "revision": "6e65319fe476ffe8db8ddaf828a537ed36fe2859",
+    },
+}
+TEMPLATE_PATHS = {
+    "cn": CN_TEMPLATE_PATH,
+    "cr": CR_TEMPLATE_PATH,
+}
+APPLE_DOC_ROW_RE = re.compile(
+    r"^\| 
    (?P.+)
     \| "
+    r"\[`(?P.+)`\]\((?Phttps://apple\.github\.io/containerization/.+)\) \|$"
+)
+COMPATIBILITY_REFERENCE_METHODS = {
+    "dns.validate",
+    "dns.resolvConf",
+    "dns.nameservers",
+    "dns.domain",
+    "dns.searchDomains",
+    "dns.options",
+}
+GHOSTVM_EXTENSION_METHODS = {
+    "container.list",
+    "dns.delete",
+    "kernel.default",
+    "kernel.installRecommended",
+    "manager.close",
+    "mount.delete",
+    "mount.guestShare",
+    "network.delete",
+    "processConfig.delete",
+    "readerStream.createProxy",
+    "readerStream.attachProxy",
+    "readerStream.closeProxy",
+    "writer.createProxy",
+    "writer.attachProxy",
+    "writer.closeProxy",
+    "terminal.createProxy",
+    "terminal.attachProxy",
+    "terminal.waitAttachedProxy",
+    "terminal.closeProxy",
+    "volume.create",
+    "volume.list",
+    "volume.inspect",
+    "volume.mount",
+    "volume.delete",
+}
+DEFAULT_OPTION_TYPE_OVERRIDES = {
+    ("container", "copy-in", "--mode"): "file-permissions",
+    ("interface", "nat-create", "--mtu"): "uint32",
+    ("network", "vmnet-create", "--mode"): "network-mode",
+    ("volume", "create", "--size"): "uint64",
+    ("*", "*", "--memory"): "uint64",
+    ("*", "*", "--memory-overhead"): "uint64",
+    ("*", "*", "--rootfs-size"): "uint64",
+}
+
+
+class CatalogError(Exception):
+    pass
+
+
+def scan_atoms(text):
+    atoms = []
+    start = 0
+    bracket_depth = 0
+    for index, character in enumerate(text):
+        if character == "[":
+            bracket_depth += 1
+        elif character == "]":
+            bracket_depth -= 1
+            if bracket_depth < 0:
+                raise CatalogError(f"unbalanced brackets in {text!r}")
+        elif character.isspace() and bracket_depth == 0:
+            if start < index:
+                atoms.append(text[start:index])
+            start = index + 1
+    if bracket_depth:
+        raise CatalogError(f"unbalanced brackets in {text!r}")
+    if start < len(text):
+        atoms.append(text[start:])
+    return atoms
+
+
+def split_result(text):
+    if " -> " in text:
+        return text.split(" -> ", 1)
+    if text.startswith("-> "):
+        return "", text[3:]
+    return text, None
+
+
+def parse_value(expression):
+    repeatable = expression.endswith("...")
+    if repeatable:
+        expression = expression[:-3]
+    nullable = expression.endswith("|null")
+    if nullable:
+        expression = expression[:-5]
+
+    if "=" in expression and not expression.startswith("="):
+        left, right = expression.split("=", 1)
+        left_value = parse_value(left)
+        right_value = parse_value(right)
+        name = f"{left_value['name']}={right_value['name']}"
+        value_type = f"{left_value['type']}={right_value['type']}"
+    else:
+        reference = re.fullmatch(r"@<([^:>]+):([^>]+)>", expression)
+        literal = re.fullmatch(r"<([^:>]+):([^>]+)>", expression)
+        if reference:
+            name = reference.group(1)
+            value_type = f"reference:{name}"
+        elif literal:
+            name = literal.group(1)
+            value_type = literal.group(2)
+        else:
+            raise CatalogError(f"unsupported value expression {expression!r}")
+
+    if nullable:
+        value_type += "?"
+    return {"name": name, "type": value_type, "repeatable": repeatable}
+
+
+def inferred_default_type(value):
+    if value in ("true", "false"):
+        return "bool"
+    if re.fullmatch(r"(?:0|[1-9][0-9]*)", value):
+        return "int"
+    return "string"
+
+
+def parsed_default(value, value_type):
+    if value_type == "bool":
+        return value == "true"
+    if value_type == "int":
+        return int(value)
+    return value
+
+
+def parse_option(atoms, index, required, outer_repeatable=False, group=None):
+    option_atom = atoms[index]
+    if "=" in option_atom:
+        name, default = option_atom.split("=", 1)
+        value_type = inferred_default_type(default)
+        value = {"name": name[2:], "type": value_type, "repeatable": False}
+        default = parsed_default(default, value_type)
+        consumed = 1
+    else:
+        name = option_atom
+        default = None
+        if index + 1 >= len(atoms):
+            raise CatalogError(f"option {name!r} has no value")
+        value = parse_value(atoms[index + 1])
+        consumed = 2
+    option = {
+        "names": [name],
+        "type": value["type"],
+        "required": required,
+        "repeatable": outer_repeatable or value["repeatable"],
+        "default": default,
+    }
+    if group:
+        option["group"] = group
+    return option, consumed
+
+
+def parse_arguments(atoms, allow_override=False):
+    positionals = []
+    options = []
+    option_groups = []
+    index = 0
+    while index < len(atoms):
+        atom = atoms[index]
+        if atom.startswith("["):
+            outer_repeatable = atom.endswith("...")
+            inner = atom[1:-4] if outer_repeatable else atom[1:-1]
+            inner_atoms = scan_atoms(inner)
+            if inner_atoms and inner_atoms[0].startswith("--"):
+                option, consumed = parse_option(inner_atoms, 0, False, outer_repeatable)
+                if consumed != len(inner_atoms):
+                    raise CatalogError(f"unexpected optional argument content in {atom!r}")
+                options.append(option)
+            elif allow_override and inner == "":
+                option_groups.append(OVERRIDE_GROUP)
+            else:
+                value = parse_value(inner + ("..." if outer_repeatable else ""))
+                positionals.append({
+                    "name": value["name"],
+                    "type": value["type"],
+                    "required": False,
+                    "repeatable": value["repeatable"],
+                })
+            index += 1
+        elif atom.startswith("--"):
+            option, consumed = parse_option(atoms, index, True)
+            options.append(option)
+            index += consumed
+        else:
+            value = parse_value(atom)
+            positionals.append({
+                "name": value["name"],
+                "type": value["type"],
+                "required": True,
+                "repeatable": value["repeatable"],
+            })
+            index += 1
+    return positionals, options, option_groups
+
+
+def lower_camel(value, operation=False):
+    parts = value.split("-")
+    result = parts[0]
+    for part in parts[1:]:
+        result += ACRONYMS.get(part, part[:1].upper() + part[1:])
+    if operation and len(parts) > 1 and parts[0] in ACRONYMS:
+        result = parts[0] + result[len(parts[0]):]
+    return result
+
+
+def method_id(resource, operation):
+    return f"{lower_camel(resource)}.{lower_camel(operation, operation=True)}"
+
+
+def wire_method_id(namespace, resource, operation):
+    if namespace == "cn" or resource == "volume":
+        return method_id(resource, operation)
+    resource_name = lower_camel(resource)
+    return f"cr{resource_name[:1].upper()}{resource_name[1:]}.{lower_camel(operation, operation=True)}"
+
+
+def result_type(expression):
+    if expression is None:
+        return "void"
+    value = parse_value(expression)
+    suffix = "[]" if value["repeatable"] else ""
+    return value["type"] + suffix
+
+
+def sample_for_type(value_type, name):
+    base_type = value_type.removesuffix("?")
+    if "=" in base_type:
+        left_type, right_type = base_type.split("=", 1)
+        left_name, right_name = name.split("=", 1)
+        return f"{sample_for_type(left_type, left_name)}={sample_for_type(right_type, right_name)}"
+    if base_type.startswith("reference:"):
+        return f"@{base_type.removeprefix('reference:')}/example"
+    if "|" in base_type:
+        return base_type.split("|", 1)[0]
+    if base_type == "bool":
+        return "true"
+    if base_type in {"int", "int32", "int64", "uint16", "uint32", "uint64"}:
+        return "1"
+    if base_type in {"host-url", "host-path"}:
+        return "/tmp/example"
+    if base_type in {"container-path", "container-url"}:
+        return "/example"
+    if base_type == "cidrv4":
+        return "192.0.2.2/24"
+    if base_type == "cidrv6":
+        return "2001:db8::2/64"
+    if base_type == "ipv4-address":
+        return "192.0.2.1"
+    if base_type == "ipv6-address":
+        return "2001:db8::1"
+    if base_type == "mac-address":
+        return "02:00:00:00:00:01"
+    if base_type == "file-permissions":
+        return "0644"
+    if base_type == "logger-level":
+        return "info"
+    if base_type == "linux-signal":
+        return "SIGTERM"
+    if base_type == "linux-capability":
+        return "CAP_CHOWN"
+    if base_type in {"oci-platform", "system-platform"}:
+        return "linux/arm64"
+    if base_type == "oci-descriptor-json":
+        return '{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"sha256:' + ("0" * 64) + '","size":0}'
+    if base_type.startswith("oci-") or base_type in {
+        "attached-filesystem-map",
+        "container-statistics",
+        "mount-runtime-options",
+        "pod-volume-source",
+        "virtiofs-layout",
+    }:
+        return "{}"
+    if name in {"assignment", "key-value"}:
+        return "key=value"
+    return "example"
+
+
+def minimal_argv(entry):
+    argv = [entry["commandID"]]
+    if entry["commandShape"] == "reference":
+        receiver = entry["positionals"][0]
+        argv.append(sample_for_type(receiver["type"], receiver["name"]))
+        positionals = entry["positionals"][1:]
+    else:
+        positionals = entry["positionals"]
+    for positional in positionals:
+        if positional["required"]:
+            argv.append(sample_for_type(positional["type"], positional["name"]))
+    for option in entry["options"]:
+        if option["required"]:
+            argv.extend([option["names"][0], sample_for_type(option["type"], option["names"][0][2:])])
+    return argv
+
+
+def markdown_signatures(lines):
+    signatures = []
+    index = 0
+    while index < len(lines):
+        if not lines[index].startswith("ghostbox "):
+            index += 1
+            continue
+        source_line = index + 1
+        first = lines[index].strip()
+        syntax_lines = [first]
+        index += 1
+        while index < len(lines):
+            stripped = lines[index].strip()
+            if not lines[index].startswith("    ") or not stripped:
+                break
+            if stripped.startswith(("--", "[--", "<", "@<", "[<", "->")):
+                syntax_lines.append(stripped)
+                index += 1
+                continue
+            break
+        signatures.append((source_line, syntax_lines))
+    return signatures
+
+
+def source_signatures():
+    signatures = {}
+    for path in TEMPLATE_PATHS.values():
+        lines = path.read_text(encoding="utf-8").splitlines()
+        for _, syntax_lines in markdown_signatures(lines):
+            command_start = normalized_markdown_start(syntax_lines[0])
+            if command_start in signatures:
+                raise CatalogError(f"duplicate source signature for {command_start!r}")
+            signatures[command_start] = "\n".join(syntax_lines)
+    return signatures
+
+
+def apple_api_documentation():
+    documentation = {}
+    for path in sorted(API_DOCS_DIR.glob("*.md")):
+        if path.name == "README.md":
+            continue
+        for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            match = APPLE_DOC_ROW_RE.fullmatch(line)
+            if not match:
+                continue
+            signature = html.unescape(match.group("signature"))
+            command_start = normalized_markdown_start(signature.splitlines()[0])
+            if command_start in documentation:
+                previous = documentation[command_start]
+                raise CatalogError(
+                    f"duplicate Apple API documentation for {command_start!r} in "
+                    f"{previous['source']} and {path.relative_to(ROOT)}:{line_number}"
+                )
+            documentation[command_start] = {
+                "symbol": html.unescape(match.group("symbol")),
+                "url": html.unescape(match.group("url")),
+                "source": f"{path.relative_to(ROOT)}:{line_number}",
+            }
+    return documentation
+
+
+def enrich_catalog_help(catalog):
+    enriched = copy.deepcopy(catalog)
+    signatures = source_signatures()
+    documentation = apple_api_documentation()
+    command_starts = {command["commandStart"] for command in enriched["commands"]}
+
+    missing_signatures = sorted(command_starts - signatures.keys())
+    cn_command_starts = {
+        command["commandStart"] for command in enriched["commands"] if command["namespace"] == "cn"
+    }
+    missing_documentation = sorted(cn_command_starts - documentation.keys())
+    extra_documentation = sorted(documentation.keys() - command_starts)
+    errors = [f"source signature is missing for {command}" for command in missing_signatures]
+    errors.extend(f"Apple API documentation is missing for {command}" for command in missing_documentation)
+    errors.extend(f"Apple API documentation has no catalog command for {command}" for command in extra_documentation)
+    if errors:
+        raise CatalogError("help metadata validation failed:\n" + "\n".join(f"- {error}" for error in errors))
+
+    for command in enriched["commands"]:
+        command_start = command["commandStart"]
+        command["signature"] = signatures[command_start]
+        if command["namespace"] == "cn":
+            command["appleAPISymbol"] = documentation[command_start]["symbol"]
+            command["appleDocumentationURL"] = documentation[command_start]["url"]
+        else:
+            command["appleAPISymbol"] = command["swiftSymbol"]
+            command["appleDocumentationURL"] = command["documentationURL"]
+    return enriched
+
+
+def normalized_markdown_start(line):
+    command_text, _ = split_result(line.removeprefix("ghostbox "))
+    atoms = scan_atoms(command_text)
+    if not atoms or not COMMAND_ID_RE.fullmatch(atoms[0]):
+        raise CatalogError(f"invalid command signature {line!r}")
+    return atoms[0]
+
+
+def parse_override_options(lines):
+    try:
+        heading = lines.index("## Manager Container Allocation")
+    except ValueError as error:
+        raise CatalogError("manager allocation section is missing") from error
+    options = []
+    in_group = False
+    for line in lines[heading + 1:]:
+        stripped = line.strip()
+        if stripped == "```text":
+            in_group = True
+            continue
+        if in_group and stripped == "```":
+            break
+        if in_group and stripped.startswith("--"):
+            atoms = scan_atoms(stripped)
+            option, consumed = parse_option(atoms, 0, False, group=OVERRIDE_GROUP)
+            if consumed != len(atoms):
+                raise CatalogError(f"unexpected manager override syntax {stripped!r}")
+            options.append(option)
+    if not options:
+        raise CatalogError("manager override option group is empty")
+    return options
+
+
+def cr_source_metadata():
+    text = CR_TEMPLATE_PATH.read_text(encoding="utf-8")
+    match = re.search(r"", text, re.DOTALL)
+    if not match:
+        raise CatalogError("CR catalog metadata block is missing")
+    try:
+        values = json.loads(match.group("json"))
+    except json.JSONDecodeError as error:
+        raise CatalogError(f"CR catalog metadata is invalid: {error}") from error
+    if not isinstance(values, list):
+        raise CatalogError("CR catalog metadata must be an array")
+    metadata = {}
+    for value in values:
+        if not isinstance(value, dict) or not isinstance(value.get("commandID"), str):
+            raise CatalogError("CR catalog metadata contains an invalid entry")
+        command_id = value["commandID"]
+        if command_id in metadata:
+            raise CatalogError(f"duplicate CR catalog metadata for {command_id}")
+        metadata[command_id] = value
+    return metadata
+
+
+def build_catalog():
+    cn_lines = CN_TEMPLATE_PATH.read_text(encoding="utf-8").splitlines()
+    override_options = parse_override_options(cn_lines)
+    cr_metadata = cr_source_metadata()
+    commands = []
+    for expected_namespace, path in TEMPLATE_PATHS.items():
+        lines = path.read_text(encoding="utf-8").splitlines()
+        for source_line, syntax_lines in markdown_signatures(lines):
+            first_without_result, inline_result = split_result(syntax_lines[0])
+            atoms = scan_atoms(first_without_result)
+            if len(atoms) < 2 or atoms[0] != "ghostbox":
+                raise CatalogError(f"invalid signature at {path.name}:{source_line}")
+            command_id = atoms[1]
+            command_match = COMMAND_ID_RE.fullmatch(command_id)
+            if not command_match or command_match.group("namespace") != expected_namespace:
+                raise CatalogError(f"invalid command ID at {path.name}:{source_line}")
+            namespace = command_match.group("namespace")
+            resource = command_match.group("resource")
+            operation = command_match.group("operation")
+            argument_atoms = atoms[2:]
+            if argument_atoms and argument_atoms[0].startswith("@<"):
+                receiver = parse_value(argument_atoms.pop(0))
+                shape = "reference"
+                receiver_positional = {
+                    "name": receiver["name"],
+                    "type": receiver["type"],
+                    "required": True,
+                    "repeatable": False,
+                }
+            else:
+                shape = "static"
+                receiver_positional = None
+
+            result_expression = inline_result
+            for continuation in syntax_lines[1:]:
+                arguments, continuation_result = split_result(continuation)
+                if arguments:
+                    argument_atoms.extend(scan_atoms(arguments))
+                if continuation_result is not None:
+                    if result_expression is not None:
+                        raise CatalogError(f"multiple results at {path.name}:{source_line}")
+                    result_expression = continuation_result
+
+            positionals, options, option_groups = parse_arguments(
+                argument_atoms,
+                allow_override=namespace == "cn",
+            )
+            for option in options:
+                if option["default"] is not None:
+                    option_name = option["names"][0]
+                    option["type"] = DEFAULT_OPTION_TYPE_OVERRIDES.get(
+                        (resource, operation, option_name),
+                        DEFAULT_OPTION_TYPE_OVERRIDES.get(("*", "*", option_name), option["type"]),
+                    )
+            if receiver_positional:
+                positionals.insert(0, receiver_positional)
+            if option_groups:
+                options.extend(dict(option) for option in override_options)
+            if shape == "static" and positionals and positionals[0]["type"] == "name" and result_expression and result_expression.startswith("@<"):
+                shape = "create"
+
+            namespace_metadata = NAMESPACES[namespace]
+            command = {
+                "commandID": command_id,
+                "methodID": wire_method_id(namespace, resource, operation),
+                "namespace": namespace,
+                "sourceKind": "direct",
+                "aliases": [
+                    f"{alias}:{resource}:{operation}" for alias in namespace_metadata["aliases"]
+                ],
+                "resource": resource,
+                "operation": operation,
+                "commandStart": normalized_markdown_start(syntax_lines[0]),
+                "commandShape": shape,
+                "positionals": positionals,
+                "options": options,
+                "resultType": result_type(result_expression),
+                "minimalArgv": [],
+                "source": path.name,
+                "sourceLine": source_line,
+            }
+            if namespace == "cr":
+                metadata = cr_metadata.get(command_id)
+                if metadata is None:
+                    raise CatalogError(f"CR source metadata is missing for {command_id}")
+                for field in (
+                    "sourceKind",
+                    "swiftModule",
+                    "swiftSymbol",
+                    "swiftSource",
+                    "documentationURL",
+                ):
+                    if not isinstance(metadata.get(field), str) or not metadata[field]:
+                        raise CatalogError(f"CR source metadata field {field} is missing for {command_id}")
+                    command[field] = metadata[field]
+                if "methodID" in metadata:
+                    command["methodID"] = metadata["methodID"]
+            if option_groups:
+                command["optionGroups"] = option_groups
+            command["minimalArgv"] = minimal_argv(command)
+            commands.append(command)
+
+    extra_cr_metadata = sorted(cr_metadata.keys() - {command["commandID"] for command in commands})
+    if extra_cr_metadata:
+        raise CatalogError(f"CR source metadata has no command definitions: {extra_cr_metadata}")
+
+    resources = sorted({command["resource"] for command in commands})
+    return {
+        "schemaVersion": 2,
+        "sources": [path.name for path in TEMPLATE_PATHS.values()],
+        "namespaces": NAMESPACES,
+        "entryCount": len(commands),
+        "resourceCount": len(resources),
+        "resources": resources,
+        "sharedOptionGroups": {OVERRIDE_GROUP: override_options},
+        "commands": commands,
+    }
+
+
+def require(condition, message, errors):
+    if not condition:
+        errors.append(message)
+
+
+def validate_metadata_list(values, label, errors, options=False):
+    require(isinstance(values, list), f"{label} must be an array", errors)
+    if not isinstance(values, list):
+        return
+    for index, value in enumerate(values):
+        item_label = f"{label}[{index}]"
+        require(isinstance(value, dict), f"{item_label} must be an object", errors)
+        if not isinstance(value, dict):
+            continue
+        require(isinstance(value.get("type"), str) and bool(value.get("type")), f"{item_label}.type is invalid", errors)
+        require(isinstance(value.get("required"), bool), f"{item_label}.required is invalid", errors)
+        require(isinstance(value.get("repeatable"), bool), f"{item_label}.repeatable is invalid", errors)
+        if options:
+            names = value.get("names")
+            require(isinstance(names, list) and bool(names), f"{item_label}.names is invalid", errors)
+            if isinstance(names, list):
+                require(all(isinstance(name, str) and name.startswith("--") for name in names), f"{item_label}.names contains an invalid option", errors)
+            require("default" in value, f"{item_label}.default is missing", errors)
+        else:
+            require(isinstance(value.get("name"), str) and bool(value.get("name")), f"{item_label}.name is invalid", errors)
+
+
+def validate_catalog(catalog):
+    errors = []
+    require(isinstance(catalog, dict), "catalog root must be an object", errors)
+    if not isinstance(catalog, dict):
+        return errors
+    commands = catalog.get("commands")
+    require(isinstance(commands, list), "commands must be an array", errors)
+    if not isinstance(commands, list):
+        return errors
+
+    require(catalog.get("schemaVersion") == 2, "schemaVersion must be 2", errors)
+    require(catalog.get("sources") == [path.name for path in TEMPLATE_PATHS.values()], "sources do not match the authoritative templates", errors)
+    require(catalog.get("namespaces") == NAMESPACES, "namespaces metadata is invalid", errors)
+    resources = {command.get("resource") for command in commands if isinstance(command, dict)}
+    command_ids = [command.get("commandID") for command in commands if isinstance(command, dict)]
+    method_ids = [command.get("methodID") for command in commands if isinstance(command, dict)]
+    command_starts = [command.get("commandStart") for command in commands if isinstance(command, dict)]
+    require(len(commands) == EXPECTED_ENTRY_COUNT, f"expected {EXPECTED_ENTRY_COUNT} commands, found {len(commands)}", errors)
+    require(len(resources) == EXPECTED_RESOURCE_COUNT, f"expected {EXPECTED_RESOURCE_COUNT} resources, found {len(resources)}", errors)
+    require(catalog.get("entryCount") == len(commands), "entryCount does not match commands", errors)
+    require(catalog.get("resourceCount") == len(resources), "resourceCount does not match commands", errors)
+    require(catalog.get("resources") == sorted(resources), "resources does not match the sorted command resources", errors)
+    require(len(command_ids) == len(set(command_ids)), "command IDs are not unique", errors)
+    require(len(method_ids) == len(set(method_ids)), "method IDs are not unique", errors)
+    require(len(command_starts) == len(set(command_starts)), "command starts are not unique", errors)
+
+    shared_groups = catalog.get("sharedOptionGroups")
+    require(isinstance(shared_groups, dict), "sharedOptionGroups must be an object", errors)
+    override_options = shared_groups.get(OVERRIDE_GROUP) if isinstance(shared_groups, dict) else None
+    validate_metadata_list(override_options, f"sharedOptionGroups.{OVERRIDE_GROUP}", errors, options=True)
+
+    for index, command in enumerate(commands):
+        label = f"commands[{index}]"
+        require(isinstance(command, dict), f"{label} must be an object", errors)
+        if not isinstance(command, dict):
+            continue
+        method = command.get("methodID")
+        command_id = command.get("commandID")
+        namespace = command.get("namespace")
+        resource = command.get("resource")
+        operation = command.get("operation")
+        shape = command.get("commandShape")
+        argv = command.get("minimalArgv")
+        command_match = COMMAND_ID_RE.fullmatch(command_id) if isinstance(command_id, str) else None
+        require(command_match is not None, f"{label}.commandID is invalid", errors)
+        require(namespace in NAMESPACES, f"{label}.namespace is invalid", errors)
+        if command_match:
+            require(command_match.group("namespace") == namespace, f"{label}.commandID namespace does not match", errors)
+            require(command_match.group("resource") == resource, f"{label}.commandID resource does not match", errors)
+            require(command_match.group("operation") == operation, f"{label}.commandID operation does not match", errors)
+        require(isinstance(method, str) and bool(METHOD_ID_RE.fullmatch(method)), f"{label}.methodID is invalid", errors)
+        require(isinstance(resource, str) and bool(resource), f"{label}.resource is invalid", errors)
+        require(isinstance(operation, str) and bool(operation), f"{label}.operation is invalid", errors)
+        if isinstance(method, str) and isinstance(namespace, str) and isinstance(resource, str) and isinstance(operation, str):
+            require(method == wire_method_id(namespace, resource, operation), f"{label}.methodID does not match its namespace, resource, and operation", errors)
+        require(command.get("sourceKind") in {"direct", "ghostvm-adapter"}, f"{label}.sourceKind is invalid", errors)
+        aliases = command.get("aliases")
+        require(isinstance(aliases, list) and bool(aliases), f"{label}.aliases is invalid", errors)
+        if isinstance(aliases, list) and isinstance(namespace, str) and isinstance(resource, str) and isinstance(operation, str) and namespace in NAMESPACES:
+            expected_aliases = [f"{alias}:{resource}:{operation}" for alias in NAMESPACES[namespace]["aliases"]]
+            require(aliases == expected_aliases, f"{label}.aliases does not match its namespace", errors)
+        require(command.get("source") == NAMESPACES.get(namespace, {}).get("source"), f"{label}.source is invalid", errors)
+        if namespace == "cr":
+            for field in ("swiftModule", "swiftSymbol", "swiftSource", "documentationURL"):
+                require(isinstance(command.get(field), str) and bool(command.get(field)), f"{label}.{field} is invalid", errors)
+        require(shape in {"static", "reference", "create"}, f"{label}.commandShape is invalid", errors)
+        require(isinstance(command.get("resultType"), str) and bool(command.get("resultType")), f"{label}.resultType is invalid", errors)
+        require(isinstance(command.get("sourceLine"), int) and command.get("sourceLine", 0) > 0, f"{label}.sourceLine is invalid", errors)
+        validate_metadata_list(command.get("positionals"), f"{label}.positionals", errors)
+        validate_metadata_list(command.get("options"), f"{label}.options", errors, options=True)
+        require(isinstance(argv, list) and bool(argv), f"{label}.minimalArgv is invalid", errors)
+        if isinstance(argv, list) and argv:
+            require(argv[0] == command_id, f"{label}.minimalArgv does not start with its qualified command ID", errors)
+            try:
+                require(argv == minimal_argv(command), f"{label}.minimalArgv does not match required metadata", errors)
+            except (CatalogError, KeyError, TypeError, ValueError) as error:
+                errors.append(f"{label}.minimalArgv could not be validated: {error}")
+        option_names = [name for option in command.get("options", []) if isinstance(option, dict) for name in option.get("names", [])]
+        require(len(option_names) == len(set(option_names)), f"{label}.options contains duplicate names", errors)
+
+        groups = command.get("optionGroups", [])
+        require(isinstance(groups, list), f"{label}.optionGroups must be an array", errors)
+        if OVERRIDE_GROUP in groups and isinstance(override_options, list):
+            grouped = [option for option in command.get("options", []) if option.get("group") == OVERRIDE_GROUP]
+            require(grouped == override_options, f"{label} does not contain the shared manager override options", errors)
+
+    override_methods = {
+        command.get("methodID")
+        for command in commands
+        if isinstance(command, dict) and OVERRIDE_GROUP in command.get("optionGroups", [])
+    }
+    require(
+        override_methods == {
+            "manager.createContainer",
+            "manager.createContainerFromImage",
+            "manager.createContainerFromMounts",
+        },
+        "shared manager overrides are not attached to exactly the three allocation commands",
+        errors,
+    )
+
+    try:
+        template_lines = {
+            path.name: path.read_text(encoding="utf-8").splitlines()
+            for path in TEMPLATE_PATHS.values()
+        }
+        markdown_commands = set()
+        for lines in template_lines.values():
+            markdown_commands.update(
+                normalized_markdown_start(lines[source_line - 1])
+                for source_line, _ in markdown_signatures(lines)
+            )
+        catalog_commands = set(command_starts)
+        missing = sorted(markdown_commands - catalog_commands)
+        extra = sorted(catalog_commands - markdown_commands)
+        require(not missing, f"catalog is missing Markdown commands: {missing}", errors)
+        require(not extra, f"catalog has commands absent from Markdown: {extra}", errors)
+        for index, command in enumerate(commands):
+            source = command.get("source") if isinstance(command, dict) else None
+            source_line = command.get("sourceLine") if isinstance(command, dict) else None
+            lines = template_lines.get(source, [])
+            if isinstance(source_line, int) and 0 < source_line <= len(lines):
+                require(lines[source_line - 1].startswith("ghostbox "), f"commands[{index}].sourceLine is not a signature", errors)
+                if lines[source_line - 1].startswith("ghostbox "):
+                    require(normalized_markdown_start(lines[source_line - 1]) == command.get("commandStart"), f"commands[{index}].sourceLine points to a different command", errors)
+    except (CatalogError, OSError) as error:
+        errors.append(f"could not compare Markdown command starts: {error}")
+    return errors
+
+
+def write_catalog(catalog):
+    CATALOG_PATH.write_text(json.dumps(catalog, indent=2) + "\n", encoding="utf-8")
+
+
+def swift_string(value):
+    if not isinstance(value, str) or not value.isascii():
+        raise CatalogError(f"generated Swift string is not ASCII: {value!r}")
+    return json.dumps(value)
+
+
+def swift_json_value(value, value_type):
+    if isinstance(value, bool):
+        return f".boolean({str(value).lower()})"
+    if isinstance(value, int):
+        if value_type.removesuffix("?").startswith("uint"):
+            return f".unsignedInteger({value})"
+        return f".integer({value})"
+    if isinstance(value, str):
+        return f".string({swift_string(value)})"
+    raise CatalogError(f"unsupported generated default {value!r}")
+
+
+def positional_parameter_name(command, index, positional):
+    method = command["methodID"]
+    if method == "dns.create" and index == 0:
+        return "name"
+    if method in COMPATIBILITY_REFERENCE_METHODS and index == 0:
+        return "reference"
+    return lower_camel(positional["name"])
+
+
+def render_swift_argument(command, index, argument):
+    return (
+        ".init("
+        f"name: {swift_string(argument['name'])}, "
+        f"parameterName: {swift_string(positional_parameter_name(command, index, argument))}, "
+        f"type: {swift_string(argument['type'])}, "
+        f"required: {str(argument['required']).lower()}, "
+        f"repeatable: {str(argument['repeatable']).lower()}"
+        ")"
+    )
+
+
+def option_parameter_name(command, option):
+    compatibility_names = {
+        ("dns.create", "--nameserver"): "nameservers",
+        ("dns.create", "--search-domain"): "searchDomains",
+        ("dns.create", "--option"): "options",
+    }
+    return compatibility_names.get(
+        (command["methodID"], option["names"][0]),
+        lower_camel(option["names"][0][2:]),
+    )
+
+
+def render_swift_option(command, option):
+    names = ", ".join(swift_string(name) for name in option["names"])
+    parameter_name = option_parameter_name(command, option)
+    default = "nil"
+    if option["default"] is not None:
+        default = swift_json_value(option["default"], option["type"])
+    return (
+        ".init("
+        f"names: [{names}], "
+        f"parameterName: {swift_string(parameter_name)}, "
+        f"type: {swift_string(option['type'])}, "
+        f"required: {str(option['required']).lower()}, "
+        f"repeatable: {str(option['repeatable']).lower()}, "
+        f"defaultValue: {default}"
+        ")"
+    )
+
+
+def render_swift_list(values, indent):
+    if not values:
+        return "[]"
+    padding = " " * indent
+    inner = (",\n" + padding).join(values)
+    return f"[\n{padding}{inner},\n{' ' * (indent - 4)}]"
+
+
+def render_catalog_swift(catalog):
+    command_blocks = []
+    for command in catalog["commands"]:
+        positionals = render_swift_list(
+            [render_swift_argument(command, index, value) for index, value in enumerate(command["positionals"])],
+            12,
+        )
+        options = render_swift_list([render_swift_option(command, value) for value in command["options"]], 12)
+        implicit_defaults = "[:]"
+        if command["methodID"] == "dns.create":
+            implicit_defaults = '["searchDomains": .array([]), "options": .array([])]'
+        command_blocks.append(
+            "    .init(\n"
+            f"        commandID: {swift_string(command['commandID'])},\n"
+            f"        methodID: {swift_string(command['methodID'])},\n"
+            f"        namespace: {swift_string(command['namespace'])},\n"
+            f"        sourceKind: {swift_string(command['sourceKind'])},\n"
+            f"        aliases: {render_swift_list([swift_string(value) for value in command['aliases']], 12)},\n"
+            f"        resource: {swift_string(command['resource'])},\n"
+            f"        operation: {swift_string(command['operation'])},\n"
+            f"        shape: .{command['commandShape']},\n"
+            f"        signature: {swift_string(command['signature'])},\n"
+            f"        resultType: {swift_string(command['resultType'])},\n"
+            f"        appleAPISymbol: {swift_string(command['appleAPISymbol'])},\n"
+            f"        appleDocumentationURL: {swift_string(command['appleDocumentationURL'])},\n"
+            f"        swiftModule: {swift_string(command['swiftModule']) if 'swiftModule' in command else 'nil'},\n"
+            f"        swiftSymbol: {swift_string(command.get('swiftSymbol', command['appleAPISymbol']))},\n"
+            f"        swiftSource: {swift_string(command['swiftSource']) if 'swiftSource' in command else 'nil'},\n"
+            f"        exampleArguments: {render_swift_list([swift_string(value) for value in command['minimalArgv']], 12)},\n"
+            f"        positionals: {positionals},\n"
+            f"        options: {options},\n"
+            f"        implicitDefaults: {implicit_defaults}\n"
+            "    )"
+        )
+
+    rendered_commands = ",\n".join(command_blocks)
+
+    return f'''// Generated by scripts/generate-ghostbox-command-catalog.py. Do not edit.
+
+enum GhostboxCommandShape: String, Sendable {{
+    case `static`
+    case create
+    case reference
+}}
+
+struct GhostboxCommandArgument: Sendable {{
+    let name: String
+    let parameterName: String
+    let type: String
+    let required: Bool
+    let repeatable: Bool
+}}
+
+struct GhostboxCommandOption: Sendable {{
+    let names: [String]
+    let parameterName: String
+    let type: String
+    let required: Bool
+    let repeatable: Bool
+    let defaultValue: GhostboxJSONValue?
+}}
+
+struct GhostboxCommandSignature: Sendable {{
+    let commandID: String
+    let methodID: String
+    let namespace: String
+    let sourceKind: String
+    let aliases: [String]
+    let resource: String
+    let operation: String
+    let shape: GhostboxCommandShape
+    let signature: String
+    let resultType: String
+    let appleAPISymbol: String
+    let appleDocumentationURL: String
+    let swiftModule: String?
+    let swiftSymbol: String
+    let swiftSource: String?
+    let exampleArguments: [String]
+    let positionals: [GhostboxCommandArgument]
+    let options: [GhostboxCommandOption]
+    let implicitDefaults: [String: GhostboxJSONValue]
+}}
+
+let ghostboxCommandResources = {render_swift_list([swift_string(value) for value in catalog['resources']], 4)}
+
+let ghostboxCommandCatalog: [GhostboxCommandSignature] = [
+{rendered_commands},
+]
+'''
+
+
+def render_fixtures_swift(catalog):
+    fixtures = []
+    for command in catalog["commands"]:
+        argv = ", ".join(swift_string(value) for value in command["minimalArgv"])
+        fixtures.append(
+            "    .init("
+            f"commandID: {swift_string(command['commandID'])}, "
+            f"methodID: {swift_string(command['methodID'])}, "
+            f"argv: [{argv}]"
+            ")"
+        )
+    rendered_fixtures = ",\n".join(fixtures)
+    return f'''// Generated by scripts/generate-ghostbox-command-catalog.py. Do not edit.
+
+struct GhostboxCommandFixture: Sendable {{
+    let commandID: String
+    let methodID: String
+    let argv: [String]
+}}
+
+let ghostboxCommandFixtures: [GhostboxCommandFixture] = [
+{rendered_fixtures},
+]
+'''
+
+
+def generated_outputs(catalog):
+    return {
+        GENERATED_CATALOG_PATH: render_catalog_swift(catalog),
+        GENERATED_FIXTURES_PATH: render_fixtures_swift(catalog),
+    }
+
+
+def load_valid_catalog():
+    catalog = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
+    errors = validate_catalog(catalog)
+    if errors:
+        raise CatalogError("catalog validation failed:\n" + "\n".join(f"- {error}" for error in errors))
+    return catalog
+
+
+def validate_runtime_coverage(catalog):
+    method_pattern = re.compile(r'"([a-z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*)"')
+    case_pattern = re.compile(
+        r'^\s*case\s+(?P"[a-z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*"'
+        r'(?:\s*,\s*"[a-z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*")*)\s*:',
+        re.MULTILINE,
+    )
+    comparison_pattern = re.compile(
+        r'method\.rawValue\s*(?:==|!=)\s*"([a-z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*)"'
+    )
+    runtime_methods = set()
+    for path in sorted(RUNTIME_HANDLER_DIR.glob("*.swift")):
+        source = path.read_text(encoding="utf-8")
+        for match in case_pattern.finditer(source):
+            runtime_methods.update(method_pattern.findall(match.group("labels")))
+        runtime_methods.update(comparison_pattern.findall(source))
+    declaration_pattern = re.compile(r'rawValue:\s*"([a-z][A-Za-z0-9]*\.[a-z][A-Za-z0-9]*)"')
+    runtime_methods.update(declaration_pattern.findall(RUNTIME_METHOD_PATH.read_text(encoding="utf-8")))
+
+    catalog_methods = {command["methodID"] for command in catalog["commands"]}
+    missing_extensions = sorted(GHOSTVM_EXTENSION_METHODS - runtime_methods)
+    missing = sorted(catalog_methods - runtime_methods)
+    extra = sorted(runtime_methods - catalog_methods - GHOSTVM_EXTENSION_METHODS)
+    if missing or extra or missing_extensions:
+        errors = [f"runtime is missing method {method}" for method in missing]
+        errors.extend(f"runtime declares non-catalog method {method}" for method in extra)
+        errors.extend(f"runtime is missing GhostVM extension method {method}" for method in missing_extensions)
+        raise CatalogError("runtime coverage validation failed:\n" + "\n".join(f"- {error}" for error in errors))
+    return len(catalog_methods)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    action = parser.add_mutually_exclusive_group(required=True)
+    action.add_argument("--generate", action="store_true", help="rebuild the JSON catalog and generated Swift sources from the templates")
+    action.add_argument("--check", action="store_true", help="validate the authoritative templates, JSON catalog, and generated Swift sources")
+    args = parser.parse_args()
+
+    try:
+        expected_catalog = build_catalog()
+        errors = validate_catalog(expected_catalog)
+        if errors:
+            raise CatalogError("generated catalog validation failed:\n" + "\n".join(f"- {error}" for error in errors))
+        if args.generate:
+            catalog = expected_catalog
+            write_catalog(catalog)
+        else:
+            catalog = load_valid_catalog()
+            if catalog != expected_catalog:
+                raise CatalogError(
+                    "catalog validation failed:\n"
+                    f"- {CATALOG_PATH.relative_to(ROOT)} is stale relative to the authoritative templates"
+                )
+        catalog_with_help = enrich_catalog_help(catalog)
+        outputs = generated_outputs(catalog_with_help)
+        if args.generate:
+            GENERATED_DIR.mkdir(parents=True, exist_ok=True)
+            for path, content in outputs.items():
+                path.write_text(content, encoding="utf-8")
+            print(
+                f"generated {CATALOG_PATH.relative_to(ROOT)} and {len(outputs)} Swift files: "
+                f"{len(catalog['commands'])} commands, {len(catalog['resources'])} resources"
+            )
+        else:
+            stale = []
+            for path, expected in outputs.items():
+                try:
+                    actual = path.read_text(encoding="utf-8")
+                except FileNotFoundError:
+                    stale.append(f"{path.relative_to(ROOT)} is missing")
+                    continue
+                if actual != expected:
+                    stale.append(f"{path.relative_to(ROOT)} is stale")
+            if stale:
+                raise CatalogError("generated Swift validation failed:\n" + "\n".join(f"- {error}" for error in stale))
+            runtime_method_count = validate_runtime_coverage(catalog)
+            print(
+                f"validated catalog, {len(outputs)} generated Swift files, and {runtime_method_count} runtime methods: "
+                f"{len(catalog['commands'])} commands, {len(catalog['resources'])} resources"
+            )
+    except (CatalogError, json.JSONDecodeError, OSError) as error:
+        print(error, file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/ghostbox-docker b/scripts/ghostbox-docker
new file mode 100755
index 0000000..c42a707
--- /dev/null
+++ b/scripts/ghostbox-docker
@@ -0,0 +1,1514 @@
+#!/bin/sh
+
+set -eu
+
+SCRIPT_DIR=$(CDPATH='' cd -- "$(dirname "$0")" && pwd)
+GHOSTBOX=${GHOSTBOX:-$SCRIPT_DIR/ghostbox}
+INITFS_REFERENCE=${INITFS_REFERENCE:-ghcr.io/apple/containerization/vminit@sha256:a69ff331d77997042afc3c7389969be176dfb657ec9ed46366c0e057ec40a297}
+GHOSTBOX_DOCKER_WAIT_TIMEOUT=${GHOSTBOX_DOCKER_WAIT_TIMEOUT:-10}
+GHOSTBOX_DOCKER_BUILD_TIMEOUT=${GHOSTBOX_DOCKER_BUILD_TIMEOUT:-600}
+BUILDKIT_IMAGE=${BUILDKIT_IMAGE:-docker.io/moby/buildkit@sha256:504731e577c20559c00f968f33219f30115e70be29ab96728d1d06e963fc494b}
+REGISTRY_IMAGE=${REGISTRY_IMAGE:-docker.io/library/registry@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373}
+
+if [ -n "${GHOSTBOX_DOCKER_STATE:-}" ]; then
+    STATE_DIR=$GHOSTBOX_DOCKER_STATE
+elif [ -n "${XDG_STATE_HOME:-}" ]; then
+    STATE_DIR=$XDG_STATE_HOME/ghostbox-docker
+else
+    STATE_DIR=${HOME:?HOME is required}/.local/state/ghostbox-docker
+fi
+
+runtime_lock=
+container_ref=
+process_config_ref=
+stdout_ref=
+stderr_ref=
+stdout_pid=
+stderr_pid=
+build_context_mount=
+build_dockerfile_mount=
+build_dir=
+registry_container_ref=
+registry_process_config_ref=
+registry_health_process_ref=
+registry_health_config_ref=
+build_registry_image_ref=
+build_registry_push_ref=
+build_image_store=
+registry_forward_pid=
+stdin_ref=
+stdin_pid=
+run_forward_pids=
+run_mount_refs=
+
+usage() {
+    cat <<'EOF'
+Usage: ghostbox-docker COMMAND
+
+Commands:
+  build [OPTIONS] PATH                 Build an image from a Dockerfile
+  pull [--platform PLATFORM] IMAGE  Pull an image into Ghostbox
+  run [OPTIONS] IMAGE [COMMAND...]  Run a foreground container
+EOF
+}
+
+pull_usage() {
+    cat <<'EOF'
+Usage: ghostbox-docker pull [--platform PLATFORM] IMAGE
+EOF
+}
+
+run_usage() {
+    cat <<'EOF'
+Usage: ghostbox-docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
+
+Options:
+      --rm                      Remove the container when it exits (required)
+      --name NAME               Assign a container name
+  -e, --env NAME[=VALUE]        Set an environment variable
+      --env-file PATH           Read environment variables from a file
+  -w, --workdir PATH            Set the working directory
+  -u, --user UID[:GID]          Set the numeric user and group
+      --entrypoint PATH         Override the image entrypoint
+  -h, --hostname NAME           Set the container hostname
+      --read-only               Make the root filesystem read-only
+      --init                    Run an init process
+      --cpus COUNT              Set an integer CPU limit
+  -m, --memory BYTES            Set a memory limit (b, k, m, or g suffix)
+      --network MODE            Use default/bridge networking or none
+      --pull POLICY             always, missing, or never
+      --platform PLATFORM       Container platform (linux/arm64 only)
+  -i, --interactive             Keep standard input open
+  -v, --volume SRC:DST[:MODE]   Bind mount; MODE supports ro and cache-ttl=0..300
+      --mount SPEC              Attach type=bind; supports cache-ttl=0..300
+  -p, --publish SPEC            Publish 127.0.0.1:HOST:CONTAINER/tcp
+
+Detached containers, TTYs, named volumes/networks, and public port bindings are not implemented.
+EOF
+}
+
+build_usage() {
+    cat <<'EOF'
+Usage: ghostbox-docker build [OPTIONS] PATH
+
+Options:
+  -f, --file PATH          Name of the Dockerfile
+  -t, --tag NAME[:TAG]     Name and optionally tag the image
+      --build-arg NAME=VALUE
+      --no-cache
+      --platform PLATFORM
+      --progress MODE
+      --pull
+      --target STAGE
+EOF
+}
+
+run_with_timeout() {
+    timeout=$1
+    shift
+    /usr/bin/perl -e 'alarm shift @ARGV; exec @ARGV' "$timeout" "$@"
+}
+
+normalize_image_reference() {
+    reference=$1
+    case "$reference" in
+        *://*)
+            printf 'docker: invalid image reference: %s\n' "$reference" >&2
+            return 125
+            ;;
+    esac
+
+    first=${reference%%/*}
+    if [ "$first" = "$reference" ]; then
+        reference=docker.io/library/$reference
+    else
+        case "$first" in
+            *.*|*:*|localhost)
+                if [ "$first" = docker.io ]; then
+                    remainder=${reference#*/}
+                    case "$remainder" in
+                        */*) ;;
+                        *) reference=docker.io/library/$remainder ;;
+                    esac
+                fi
+                ;;
+            *)
+                reference=docker.io/$reference
+                ;;
+        esac
+    fi
+
+    case "$reference" in
+        *@*) ;;
+        *)
+            last=${reference##*/}
+            case "$last" in
+                *:*) ;;
+                *) reference=$reference:latest ;;
+            esac
+            ;;
+    esac
+    printf '%s\n' "$reference"
+}
+
+release_runtime_lock() {
+    if [ -n "$runtime_lock" ]; then
+        rmdir "$runtime_lock" >/dev/null 2>&1 || true
+        runtime_lock=
+    fi
+}
+
+cleanup_run() {
+    set +e
+    if [ -n "$run_forward_pids" ]; then
+        while IFS= read -r record; do
+            [ -n "$record" ] || continue
+            forward_pid=${record#x}
+            kill "$forward_pid" >/dev/null 2>&1
+            sleep 0.1
+            kill -KILL "$forward_pid" >/dev/null 2>&1
+            wait "$forward_pid" 2>/dev/null
+        done </dev/null 2>&1
+    fi
+    if [ -n "$stdin_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:reader-stream:close "$stdin_ref" >/dev/null 2>&1
+    fi
+    if [ -n "$stdout_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:writer:close "$stdout_ref" >/dev/null 2>&1
+    fi
+    if [ -n "$stderr_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:writer:close "$stderr_ref" >/dev/null 2>&1
+    fi
+    if [ -n "$stdout_pid" ]; then
+        wait "$stdout_pid" 2>/dev/null
+        stdout_pid=
+    fi
+    if [ -n "$stderr_pid" ]; then
+        wait "$stderr_pid" 2>/dev/null
+        stderr_pid=
+    fi
+    if [ -n "$stdin_pid" ]; then
+        kill "$stdin_pid" >/dev/null 2>&1
+        wait "$stdin_pid" 2>/dev/null
+        stdin_pid=
+    fi
+    if [ -n "$container_ref" ] && [ -n "${manager_ref:-}" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:manager:delete "$manager_ref" "$container_ref" >/dev/null 2>&1
+        container_ref=
+    fi
+    if [ -n "$process_config_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:process-config:delete "$process_config_ref" >/dev/null 2>&1
+        process_config_ref=
+    fi
+    if [ -n "$run_mount_refs" ]; then
+        while IFS= read -r record; do
+            [ -n "$record" ] || continue
+            run_with_timeout 2 "$GHOSTBOX" cn:mount:delete "${record#x}" >/dev/null 2>&1
+        done </dev/null 2>&1
+        wait "$registry_forward_pid" 2>/dev/null
+        registry_forward_pid=
+    fi
+    if [ -n "$registry_health_process_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:process:delete "$registry_health_process_ref" >/dev/null 2>&1
+        registry_health_process_ref=
+    fi
+    if [ -n "$registry_health_config_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:process-config:delete "$registry_health_config_ref" >/dev/null 2>&1
+        registry_health_config_ref=
+    fi
+    if [ -n "$registry_container_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:container:stop "$registry_container_ref" >/dev/null 2>&1
+        if [ -n "${manager_ref:-}" ]; then
+            run_with_timeout 2 "$GHOSTBOX" cn:manager:delete "$manager_ref" "$registry_container_ref" >/dev/null 2>&1
+        fi
+        registry_container_ref=
+    fi
+    if [ -n "$registry_process_config_ref" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:process-config:delete "$registry_process_config_ref" >/dev/null 2>&1
+        registry_process_config_ref=
+    fi
+    if [ -n "$build_registry_image_ref" ] && [ -n "$build_image_store" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:image-store:delete "$build_image_store" \
+            "$build_registry_image_ref" --perform-cleanup=false >/dev/null 2>&1
+        build_registry_image_ref=
+    fi
+    if [ -n "$build_context_mount" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:mount:delete "$build_context_mount" >/dev/null 2>&1
+        build_context_mount=
+    fi
+    if [ -n "$build_dockerfile_mount" ]; then
+        run_with_timeout 2 "$GHOSTBOX" cn:mount:delete "$build_dockerfile_mount" >/dev/null 2>&1
+        build_dockerfile_mount=
+    fi
+    if [ -n "$build_dir" ]; then
+        rm -rf -- "$build_dir"
+        build_dir=
+    fi
+    set -e
+}
+
+read_runtime_state() {
+    runtime_file=$STATE_DIR/runtime
+    if [ ! -f "$runtime_file" ]; then
+        resource_base=ghostbox-docker-$(id -u)-$(date +%s)-$$
+        manager_name=$resource_base-manager
+        network_name=$resource_base-network
+        runtime_tmp=$STATE_DIR/runtime.tmp.$$
+        printf '%s\n%s\n' "$manager_name" "$network_name" >"$runtime_tmp"
+        mv "$runtime_tmp" "$runtime_file"
+    else
+        {
+            IFS= read -r manager_name
+            IFS= read -r network_name
+        } <"$runtime_file"
+    fi
+
+    case "$manager_name" in
+        ''|*[!A-Za-z0-9_.-]*)
+            printf 'docker run: invalid runtime state in %s\n' "$runtime_file" >&2
+            return 125
+            ;;
+    esac
+    case "$network_name" in
+        ''|*[!A-Za-z0-9_.-]*)
+            printf 'docker run: invalid runtime state in %s\n' "$runtime_file" >&2
+            return 125
+            ;;
+    esac
+    manager_ref=@manager/$manager_name
+    network_ref=@network/$network_name
+}
+
+ensure_runtime() {
+    umask 077
+    mkdir -p "$STATE_DIR"
+    chmod 700 "$STATE_DIR"
+
+    runtime_lock=$STATE_DIR/runtime.lock
+    lock_attempt=0
+    until mkdir "$runtime_lock" 2>/dev/null; do
+        lock_attempt=$((lock_attempt + 1))
+        if [ "$lock_attempt" -ge 50 ]; then
+            printf '%s\n' 'docker run: timed out waiting for the runtime lock' >&2
+            runtime_lock=
+            return 125
+        fi
+        sleep 0.1
+    done
+
+    read_runtime_state
+    if run_with_timeout 10 "$GHOSTBOX" cn:manager:image-store "$manager_ref" >/dev/null 2>&1; then
+        release_runtime_lock
+        return 0
+    fi
+
+    if ! run_with_timeout 10 "$GHOSTBOX" cn:network:subnet "$network_ref" >/dev/null 2>&1; then
+        run_with_timeout 10 "$GHOSTBOX" cn:network:vmnet-create "$network_name" --mode shared >/dev/null
+    fi
+    kernel=$(run_with_timeout 600 "$GHOSTBOX" cn:kernel:install-recommended)
+    image_store=$(run_with_timeout 10 "$GHOSTBOX" cn:image-store:default)
+    run_with_timeout 10 "$GHOSTBOX" cn:manager:create-from-reference "$manager_name" \
+        --kernel "$kernel" \
+        --initfs-reference "$INITFS_REFERENCE" \
+        --image-store "$image_store" \
+        --network "$network_ref" >/dev/null
+    release_runtime_lock
+}
+
+pull_image() {
+    platform=linux/arm64
+    image=
+
+    while [ "$#" -gt 0 ]; do
+        case "$1" in
+            --help|-h)
+                pull_usage
+                return 0
+                ;;
+            --platform)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker pull: --platform requires a value' >&2
+                    return 125
+                fi
+                platform=$2
+                shift 2
+                ;;
+            --platform=*)
+                platform=${1#*=}
+                if [ -z "$platform" ]; then
+                    printf '%s\n' 'docker pull: --platform requires a value' >&2
+                    return 125
+                fi
+                shift
+                ;;
+            --*)
+                printf "docker pull: unsupported option '%s'\n" "$1" >&2
+                return 125
+                ;;
+            -*)
+                printf "docker pull: unsupported option '%s'\n" "$1" >&2
+                return 125
+                ;;
+            *)
+                if [ -n "$image" ]; then
+                    printf '%s\n' 'docker pull: exactly one image is required' >&2
+                    return 125
+                fi
+                image=$1
+                shift
+                ;;
+        esac
+    done
+
+    if [ -z "$image" ]; then
+        pull_usage >&2
+        return 125
+    fi
+    if [ ! -x "$GHOSTBOX" ]; then
+        printf "docker pull: Ghostbox executable not found: %s\n" "$GHOSTBOX" >&2
+        return 127
+    fi
+
+    image=$(normalize_image_reference "$image")
+    image_store=$(run_with_timeout 10 "$GHOSTBOX" cn:image-store:default)
+    image_reference=$(run_with_timeout 600 "$GHOSTBOX" cn:image-store:pull "$image_store" \
+        "$image" --platform "$platform")
+    printf 'Pulled %s (%s)\n' "$image" "$image_reference"
+}
+
+build_image() {
+    dockerfile=Dockerfile
+    tag=
+    platform=linux/arm64
+    progress=auto
+    no_cache=false
+    pull=false
+    target=
+    build_args=
+    context=
+
+    while [ "$#" -gt 0 ]; do
+        case "$1" in
+            --help)
+                build_usage
+                return 0
+                ;;
+            -f|--file)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker build: --file requires a value' >&2
+                    return 125
+                fi
+                dockerfile=$2
+                shift 2
+                ;;
+            --file=*)
+                dockerfile=${1#*=}
+                shift
+                ;;
+            -t|--tag)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker build: --tag requires a value' >&2
+                    return 125
+                fi
+                if [ -n "$tag" ]; then
+                    printf '%s\n' 'docker build: multiple tags are not implemented yet' >&2
+                    return 125
+                fi
+                tag=$2
+                shift 2
+                ;;
+            --tag=*)
+                if [ -n "$tag" ]; then
+                    printf '%s\n' 'docker build: multiple tags are not implemented yet' >&2
+                    return 125
+                fi
+                tag=${1#*=}
+                shift
+                ;;
+            --build-arg)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker build: --build-arg requires a value' >&2
+                    return 125
+                fi
+                case "$2" in
+                    *'
+'*)
+                        printf '%s\n' 'docker build: newlines in --build-arg are not implemented' >&2
+                        return 125
+                        ;;
+                esac
+                build_args=$build_args${build_args:+"
+"}$2
+                shift 2
+                ;;
+            --build-arg=*)
+                argument=${1#*=}
+                case "$argument" in
+                    ''|*'
+'*)
+                        printf '%s\n' 'docker build: invalid --build-arg value' >&2
+                        return 125
+                        ;;
+                esac
+                build_args=$build_args${build_args:+"
+"}$argument
+                shift
+                ;;
+            --no-cache)
+                no_cache=true
+                shift
+                ;;
+            --pull)
+                pull=true
+                shift
+                ;;
+            --platform)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker build: --platform requires a value' >&2
+                    return 125
+                fi
+                platform=$2
+                shift 2
+                ;;
+            --platform=*)
+                platform=${1#*=}
+                shift
+                ;;
+            --progress)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker build: --progress requires a value' >&2
+                    return 125
+                fi
+                progress=$2
+                shift 2
+                ;;
+            --progress=*)
+                progress=${1#*=}
+                shift
+                ;;
+            --target)
+                if [ "$#" -lt 2 ] || [ -z "$2" ]; then
+                    printf '%s\n' 'docker build: --target requires a value' >&2
+                    return 125
+                fi
+                target=$2
+                shift 2
+                ;;
+            --target=*)
+                target=${1#*=}
+                shift
+                ;;
+            --)
+                shift
+                break
+                ;;
+            -*)
+                printf "docker build: unsupported option '%s'\n" "$1" >&2
+                return 125
+                ;;
+            *)
+                if [ -n "$context" ]; then
+                    printf '%s\n' 'docker build: exactly one build context is required' >&2
+                    return 125
+                fi
+                context=$1
+                shift
+                ;;
+        esac
+    done
+
+    if [ "$#" -gt 0 ] || [ -z "$context" ]; then
+        build_usage >&2
+        return 125
+    fi
+    if [ "$platform" != linux/arm64 ]; then
+        printf 'docker build: unsupported platform %s; Ghostbox currently builds linux/arm64\n' "$platform" >&2
+        return 125
+    fi
+    case "$progress" in
+        auto|plain|tty|rawjson) ;;
+        *)
+            printf 'docker build: unsupported progress mode %s\n' "$progress" >&2
+            return 125
+            ;;
+    esac
+    case "$GHOSTBOX_DOCKER_BUILD_TIMEOUT" in
+        ''|*[!0-9]*|0|0*)
+            printf '%s\n' 'docker build: GHOSTBOX_DOCKER_BUILD_TIMEOUT must be a positive integer without leading zeroes' >&2
+            return 125
+            ;;
+    esac
+    if [ ! -x "$GHOSTBOX" ]; then
+        printf "docker build: Ghostbox executable not found: %s\n" "$GHOSTBOX" >&2
+        return 127
+    fi
+    if [ ! -d "$context" ]; then
+        printf 'docker build: build context is not a directory: %s\n' "$context" >&2
+        return 125
+    fi
+    context_dir=$(CDPATH='' cd -- "$context" && pwd -P)
+
+    case "$dockerfile" in
+        /*) dockerfile_path=$dockerfile ;;
+        Dockerfile) dockerfile_path=$context_dir/Dockerfile ;;
+        *) dockerfile_path=$(pwd -P)/$dockerfile ;;
+    esac
+    if [ ! -f "$dockerfile_path" ]; then
+        printf 'docker build: Dockerfile not found: %s\n' "$dockerfile_path" >&2
+        return 125
+    fi
+    dockerfile_dir=$(CDPATH='' cd -- "$(dirname "$dockerfile_path")" && pwd -P)
+    dockerfile_name=$(basename "$dockerfile_path")
+
+    build_id=$(date +%s)-$$
+    if [ -z "$tag" ]; then
+        tag=ghostbox-docker-untagged:$build_id
+    fi
+    tag=$(normalize_image_reference "$tag")
+
+    trap cleanup_build EXIT
+    trap 'exit 129' HUP
+    trap 'exit 130' INT
+    trap 'exit 143' TERM
+
+    ensure_runtime
+    build_dir=$STATE_DIR/builds/$build_id
+    mkdir -p "$build_dir"
+
+    build_context_mount=$(run_with_timeout 10 "$GHOSTBOX" cn:mount:guest-share \
+        "docker-build-$build_id-context" --source "$context_dir" \
+        --destination /workspace/context --read-only=true)
+    build_dockerfile_mount=$(run_with_timeout 10 "$GHOSTBOX" cn:mount:guest-share \
+        "docker-build-$build_id-dockerfile" --source "$dockerfile_dir" \
+        --destination /workspace/dockerfile --read-only=true)
+
+    image_store=$(run_with_timeout 10 "$GHOSTBOX" cn:manager:image-store "$manager_ref")
+    build_image_store=$image_store
+    run_with_timeout 600 "$GHOSTBOX" cn:image-store:pull "$image_store" \
+        "$BUILDKIT_IMAGE" --platform linux/arm64 >/dev/null
+    run_with_timeout 600 "$GHOSTBOX" cn:image-store:pull "$image_store" \
+        "$REGISTRY_IMAGE" --platform linux/arm64 >/dev/null
+
+    registry_name=docker-build-$build_id-registry
+    registry_process_name=$registry_name-process
+    registry_container_ref=@container/$registry_name
+    registry_process_config_ref=@process-config/$registry_process_name
+    run_with_timeout 10 "$GHOSTBOX" cn:process-config:create "$registry_process_name" \
+        -- /entrypoint.sh /etc/docker/registry/config.yml >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:manager:create-container "$manager_ref" "$registry_name" \
+        --reference "$REGISTRY_IMAGE" \
+        --process "$registry_process_config_ref" \
+        --networking true \
+        --cpus 1 \
+        --memory 536870912 >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:container:create "$registry_container_ref" >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:container:start "$registry_container_ref" >/dev/null
+
+    registry_health_name=$registry_name-health
+    registry_health_config_ref=@process-config/$registry_health_name
+    # The shell program is expanded inside the registry container.
+    # shellcheck disable=SC2016
+    run_with_timeout 10 "$GHOSTBOX" cn:process-config:create "$registry_health_name" \
+        -- /bin/sh -c 'attempt=0; until wget -qO- http://127.0.0.1:5000/v2/ | grep -q "{}"; do attempt=$((attempt + 1)); [ "$attempt" -lt 50 ] || exit 1; sleep 0.1; done' >/dev/null
+    registry_health_process_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:container:exec "$registry_container_ref" \
+        health --configuration "$registry_health_config_ref")
+    run_with_timeout 10 "$GHOSTBOX" cn:process:start "$registry_health_process_ref" >/dev/null
+    registry_health_status=$(run_with_timeout 10 "$GHOSTBOX" cn:process:wait "$registry_health_process_ref" \
+        --timeout-seconds 10)
+    registry_health_exit=$(printf '%s' "$registry_health_status" | plutil -extract exitCode raw -o - -)
+    if [ "$registry_health_exit" -ne 0 ]; then
+        printf '%s\n' 'docker build: local registry failed its health check' >&2
+        return 1
+    fi
+    run_with_timeout 10 "$GHOSTBOX" cn:process:delete "$registry_health_process_ref" >/dev/null
+    registry_health_process_ref=
+    run_with_timeout 10 "$GHOSTBOX" cn:process-config:delete "$registry_health_config_ref" >/dev/null
+    registry_health_config_ref=
+
+    interfaces=$(run_with_timeout 10 "$GHOSTBOX" cn:container:interfaces "$registry_container_ref")
+    # Ghostbox emits interface references as a whitespace-delimited list.
+    # shellcheck disable=SC2086
+    set -- $interfaces
+    if [ "$#" -eq 0 ]; then
+        printf '%s\n' 'docker build: local registry has no network interface' >&2
+        return 1
+    fi
+    registry_address=$(run_with_timeout 10 "$GHOSTBOX" cn:interface:ipv4-address "$1")
+    registry_address=${registry_address#\"}
+    registry_address=${registry_address%\"}
+    registry_address=${registry_address%/*}
+    build_registry_push_ref=$registry_address:5000/ghostbox-build:$build_id
+    registry_port=$((20000 + ($$ % 20000)))
+    build_registry_image_ref=127.0.0.1:$registry_port/ghostbox-build:$build_id
+    forward_timeout=$((GHOSTBOX_DOCKER_BUILD_TIMEOUT + 30))
+    run_with_timeout "$forward_timeout" "$GHOSTBOX" cn:container:forward "$registry_container_ref" \
+        -p "127.0.0.1:$registry_port:5000/tcp" >"$build_dir/registry-forward.log" 2>&1 &
+    registry_forward_pid=$!
+    sleep 0.2
+
+    container_name=docker-build-$build_id
+    process_config_name=$container_name-process
+    stdout_name=$container_name-stdout
+    stderr_name=$container_name-stderr
+    container_ref=@container/$container_name
+    process_config_ref=@process-config/$process_config_name
+    stdout_ref=@writer/$stdout_name
+    stderr_ref=@writer/$stderr_name
+
+    set -- /usr/bin/buildctl-daemonless.sh build \
+        --frontend dockerfile.v0 \
+        --local context=/workspace/context \
+        --local dockerfile=/workspace/dockerfile \
+        --opt "filename=$dockerfile_name" \
+        --opt platform=linux/arm64 \
+        --progress "$progress" \
+        --output "type=image,name=$build_registry_push_ref,push=true,registry.insecure=true"
+    if [ "$no_cache" = true ]; then
+        set -- "$@" --no-cache
+    fi
+    if [ "$pull" = true ]; then
+        set -- "$@" --opt image-resolve-mode=pull
+    fi
+    if [ -n "$target" ]; then
+        set -- "$@" --opt "target=$target"
+    fi
+    if [ -n "$build_args" ]; then
+        while IFS= read -r argument; do
+            set -- "$@" --opt "build-arg:$argument"
+        done </dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:writer:create "$stderr_name" >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:process-config:create "$process_config_name" \
+        --environment PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
+        --environment HOME=/home/user \
+        --environment USER=user \
+        --environment XDG_RUNTIME_DIR=/run/user/1000 \
+        --environment TMPDIR=/home/user/.local/tmp \
+        --environment BUILDKIT_HOST=unix:///run/user/1000/buildkit/buildkitd.sock \
+        --environment 'BUILDKITD_FLAGS=--oci-worker-no-process-sandbox --oci-worker-snapshotter=native' \
+        --user '{"uid":1000,"gid":1000}' \
+        --stdout "$stdout_ref" \
+        --stderr "$stderr_ref" \
+        -- "$@" >/dev/null
+
+    set -- cn:manager:create-container "$manager_ref" "$container_name" \
+        --reference "$BUILDKIT_IMAGE" \
+        --process "$process_config_ref" \
+        --networking true \
+        --cpus 1 \
+        --memory 536870912
+    default_mounts=$(run_with_timeout 10 "$GHOSTBOX" cn:container:default-mounts)
+    for mount_ref in $default_mounts "$build_context_mount" "$build_dockerfile_mount"; do
+        set -- "$@" --mounts "$mount_ref"
+    done
+    run_with_timeout 10 "$GHOSTBOX" "$@" >/dev/null
+
+    attach_timeout=$((GHOSTBOX_DOCKER_BUILD_TIMEOUT + 10))
+    run_with_timeout "$attach_timeout" "$GHOSTBOX" cn:writer:attach "$stdout_ref" &
+    stdout_pid=$!
+    run_with_timeout "$attach_timeout" "$GHOSTBOX" cn:writer:attach "$stderr_ref" >&2 &
+    stderr_pid=$!
+    run_with_timeout 10 "$GHOSTBOX" cn:container:create "$container_ref" >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:container:start "$container_ref" >/dev/null
+    status=$(run_with_timeout "$attach_timeout" "$GHOSTBOX" cn:container:wait "$container_ref" \
+        --timeout-seconds "$GHOSTBOX_DOCKER_BUILD_TIMEOUT")
+    build_exit=$(printf '%s' "$status" | plutil -extract exitCode raw -o - -)
+    if [ "$build_exit" -ne 0 ]; then
+        return "$build_exit"
+    fi
+
+    cleanup_run
+    run_with_timeout 600 "$GHOSTBOX" cn:image-store:pull "$image_store" "$build_registry_image_ref" \
+        --platform linux/arm64 --insecure=true >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:image-store:tag "$image_store" "$build_registry_image_ref" "$tag" >/dev/null
+    image_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:image-store:get "$image_store" "$tag" --pull=false)
+    digest=$(run_with_timeout 10 "$GHOSTBOX" cn:image:digest "$image_ref")
+    digest=${digest#\"}
+    digest=${digest%\"}
+
+    cleanup_build
+    trap - EXIT HUP INT TERM
+    printf '%s\n' "$digest"
+}
+
+run_option_value() {
+    option=$1
+    count=$2
+    value=${3-}
+    if [ "$count" -lt 2 ] || [ -z "$value" ]; then
+        printf 'docker run: %s requires a value\n' "$option" >&2
+        return 125
+    fi
+    case "$value" in
+        *'
+'*)
+            printf 'docker run: newlines in %s are not implemented\n' "$option" >&2
+            return 125
+            ;;
+    esac
+    printf '%s\n' "$value"
+}
+
+parse_memory_bytes() {
+    memory_value=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+    case "$memory_value" in
+        *gib) memory_number=${memory_value%gib}; memory_multiplier=1073741824 ;;
+        *gb) memory_number=${memory_value%gb}; memory_multiplier=1073741824 ;;
+        *g) memory_number=${memory_value%g}; memory_multiplier=1073741824 ;;
+        *mib) memory_number=${memory_value%mib}; memory_multiplier=1048576 ;;
+        *mb) memory_number=${memory_value%mb}; memory_multiplier=1048576 ;;
+        *m) memory_number=${memory_value%m}; memory_multiplier=1048576 ;;
+        *kib) memory_number=${memory_value%kib}; memory_multiplier=1024 ;;
+        *kb) memory_number=${memory_value%kb}; memory_multiplier=1024 ;;
+        *k) memory_number=${memory_value%k}; memory_multiplier=1024 ;;
+        *b) memory_number=${memory_value%b}; memory_multiplier=1 ;;
+        *) memory_number=$memory_value; memory_multiplier=1 ;;
+    esac
+    case "$memory_number" in
+        ''|*[!0-9]*|0|0*)
+            printf 'docker run: invalid memory limit %s\n' "$1" >&2
+            return 125
+            ;;
+    esac
+    if [ "${#memory_number}" -gt 12 ]; then
+        printf 'docker run: memory limit is too large: %s\n' "$1" >&2
+        return 125
+    fi
+    maximum_memory_number=$((9223372036854775807 / memory_multiplier))
+    if [ "$memory_number" -gt "$maximum_memory_number" ]; then
+        printf 'docker run: memory limit is too large: %s\n' "$1" >&2
+        return 125
+    fi
+    memory_bytes=$((memory_number * memory_multiplier))
+    if [ "$memory_bytes" -lt 6291456 ]; then
+        printf '%s\n' 'docker run: minimum memory limit is 6m' >&2
+        return 125
+    fi
+    printf '%s\n' "$memory_bytes"
+}
+
+image_array_records() {
+    image_array_key=$1
+    image_array_count=$(printf '%s' "$image_config" | \
+        plutil -extract "config.$image_array_key" raw -o - - 2>/dev/null) || return 0
+    image_array_index=0
+    while [ "$image_array_index" -lt "$image_array_count" ]; do
+        image_array_value=$(printf '%s' "$image_config" | \
+            plutil -extract "config.$image_array_key.$image_array_index" raw -o - -)
+        case "$image_array_value" in
+            *'
+'*)
+                printf 'docker run: newlines in image %s values are not implemented\n' "$image_array_key" >&2
+                return 125
+                ;;
+        esac
+        printf 'x%s\n' "$image_array_value"
+        image_array_index=$((image_array_index + 1))
+    done
+}
+
+image_command_array_records() {
+    image_command_key=$1
+    image_command_count=$(printf '%s' "$image_config" | \
+        plutil -extract "config.$image_command_key" raw -o - - 2>/dev/null) || return 0
+    image_command_index=0
+    while [ "$image_command_index" -lt "$image_command_count" ]; do
+        image_command_value=$(printf '%s' "$image_config" | \
+            plutil -extract "config.$image_command_key.$image_command_index" raw -o - -)
+        image_command_encoded=$(printf '%s' "$image_command_value" | base64 | tr -d '\n')
+        printf 'x%s\n' "$image_command_encoded"
+        image_command_index=$((image_command_index + 1))
+    done
+}
+
+image_config_value() {
+    printf '%s' "$image_config" | plutil -extract "config.$1" raw -o - - 2>/dev/null || true
+}
+
+upsert_run_environment() {
+    environment_assignment=$1
+    environment_name=${environment_assignment%%=*}
+    if [ -z "$environment_name" ] || [ "$environment_name" = "$environment_assignment" ]; then
+        printf 'docker run: invalid environment assignment: %s\n' "$environment_assignment" >&2
+        return 125
+    fi
+    updated_environment=
+    if [ -n "$resolved_environment" ]; then
+        while IFS= read -r environment_record; do
+            [ -n "$environment_record" ] || continue
+            existing_assignment=${environment_record#x}
+            existing_name=${existing_assignment%%=*}
+            if [ "$existing_name" != "$environment_name" ]; then
+                updated_environment=$updated_environment${updated_environment:+"
+"}$environment_record
+            fi
+        done <&2
+            return 125
+            ;;
+        *)
+            if inherited_value=$(/usr/bin/printenv "$environment_value"); then
+                case "$inherited_value" in
+                    *'
+'*)
+                        printf 'docker run: newlines in inherited environment values are not implemented\n' >&2
+                        return 125
+                        ;;
+                esac
+                upsert_run_environment "$environment_value=$inherited_value"
+            else
+                unset_run_environment "$environment_value"
+            fi
+            ;;
+    esac
+}
+
+apply_run_env_file() {
+    environment_file=$1
+    if [ ! -f "$environment_file" ]; then
+        printf 'docker run: env file not found: %s\n' "$environment_file" >&2
+        return 125
+    fi
+    carriage_return=$(printf '\r')
+    while IFS= read -r environment_line || [ -n "$environment_line" ]; do
+        case "$environment_line" in
+            *"$carriage_return") environment_line=${environment_line%"$carriage_return"} ;;
+        esac
+        case "$environment_line" in
+            ''|'#'*) continue ;;
+            'export '*) environment_line=${environment_line#export } ;;
+        esac
+        apply_run_environment_value "$environment_line"
+    done <"$environment_file"
+}
+
+normalize_run_user() {
+    user_value=$1
+    case "$user_value" in
+        *:*:*)
+            printf 'docker run: only numeric UID[:GID] users are implemented: %s\n' "$user_value" >&2
+            return 125
+            ;;
+        *:*) user_uid=${user_value%%:*}; user_gid=${user_value#*:} ;;
+        *) user_uid=$user_value; user_gid=0 ;;
+    esac
+    case "$user_uid" in
+        ''|*[!0-9]*)
+            printf 'docker run: only numeric UID[:GID] users are implemented: %s\n' "$user_value" >&2
+            return 125
+            ;;
+    esac
+    case "$user_gid" in
+        ''|*[!0-9]*)
+            printf 'docker run: only numeric UID[:GID] users are implemented: %s\n' "$user_value" >&2
+            return 125
+            ;;
+    esac
+    printf '{"uid":%s,"gid":%s}\n' "$user_uid" "$user_gid"
+}
+
+create_run_bind_mount() {
+    bind_source=$1
+    bind_destination=$2
+    bind_read_only=$3
+    bind_create_source=$4
+    bind_cache_ttl=${5-}
+    case "$bind_destination" in
+        /*) ;;
+        *)
+            printf 'docker run: mount destination must be absolute: %s\n' "$bind_destination" >&2
+            return 125
+            ;;
+    esac
+    case "$bind_source" in
+        /*) ;;
+        *) bind_source=$(pwd -P)/$bind_source ;;
+    esac
+    if [ ! -e "$bind_source" ]; then
+        if [ "$bind_create_source" = true ]; then
+            mkdir -p -- "$bind_source"
+        else
+            printf 'docker run: bind source does not exist: %s\n' "$bind_source" >&2
+            return 125
+        fi
+    fi
+    if [ -d "$bind_source" ]; then
+        bind_source=$(CDPATH='' cd -- "$bind_source" && pwd -P)
+    else
+        bind_parent=$(CDPATH='' cd -- "$(dirname "$bind_source")" && pwd -P)
+        bind_source=$bind_parent/$(basename "$bind_source")
+    fi
+    mount_index=$((mount_index + 1))
+    if [ -n "$bind_cache_ttl" ]; then
+        mount_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:mount:guest-share \
+            "$run_resource_name-mount-$mount_index" --source "$bind_source" \
+            --destination "$bind_destination" --read-only="$bind_read_only" \
+            --cache-ttl "$bind_cache_ttl")
+    else
+        mount_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:mount:guest-share \
+            "$run_resource_name-mount-$mount_index" --source "$bind_source" \
+            --destination "$bind_destination" --read-only="$bind_read_only")
+    fi
+    run_mount_refs=$run_mount_refs${run_mount_refs:+"
+"}x$mount_ref
+}
+
+create_run_volume_mount() {
+    volume_spec=$1
+    volume_source=${volume_spec%%:*}
+    volume_rest=${volume_spec#*:}
+    if [ -z "$volume_source" ] || [ "$volume_rest" = "$volume_spec" ]; then
+        printf 'docker run: only bind SRC:DST[:ro] volumes are implemented: %s\n' "$volume_spec" >&2
+        return 125
+    fi
+    case "$volume_source" in
+        /*|./*|../*) ;;
+        *)
+            printf 'docker run: named volumes are not implemented: %s\n' "$volume_source" >&2
+            return 125
+            ;;
+    esac
+    case "$volume_rest" in
+        *:*)
+            volume_destination=${volume_rest%%:*}
+            volume_mode=${volume_rest#*:}
+            volume_read_only=false
+            volume_cache_ttl=
+            old_ifs=$IFS
+            IFS=,
+            set -f
+            # shellcheck disable=SC2086
+            set -- $volume_mode
+            set +f
+            IFS=$old_ifs
+            for volume_option in "$@"; do
+                case "$volume_option" in
+                    ro) volume_read_only=true ;;
+                    rw|'') volume_read_only=false ;;
+                    cache-ttl=*) volume_cache_ttl=${volume_option#cache-ttl=} ;;
+                    *)
+                        printf 'docker run: unsupported volume mode: %s\n' "$volume_option" >&2
+                        return 125
+                        ;;
+                esac
+            done
+            ;;
+        *) volume_destination=$volume_rest; volume_read_only=false; volume_cache_ttl= ;;
+    esac
+    case "$volume_cache_ttl" in
+        '') ;;
+        *[!0-9]*)
+            printf 'docker run: volume cache-ttl must be an integer from 0 through 300: %s\n' "$volume_cache_ttl" >&2
+            return 125
+            ;;
+        *)
+            if [ "$volume_cache_ttl" -gt 300 ]; then
+                printf 'docker run: volume cache-ttl must be an integer from 0 through 300: %s\n' "$volume_cache_ttl" >&2
+                return 125
+            fi
+            ;;
+    esac
+    create_run_bind_mount "$volume_source" "$volume_destination" "$volume_read_only" true "$volume_cache_ttl"
+}
+
+create_run_mount() {
+    mount_spec=$1
+    mount_type=
+    mount_source=
+    mount_destination=
+    mount_read_only=false
+    mount_cache_ttl=
+    old_ifs=$IFS
+    IFS=,
+    set -f
+    # Split the comma-delimited mount specification with globbing disabled.
+    # shellcheck disable=SC2086
+    set -- $mount_spec
+    set +f
+    IFS=$old_ifs
+    for mount_field in "$@"; do
+        case "$mount_field" in
+            type=*) mount_type=${mount_field#type=} ;;
+            src=*|source=*) mount_source=${mount_field#*=} ;;
+            dst=*|destination=*|target=*) mount_destination=${mount_field#*=} ;;
+            ro|readonly|read-only) mount_read_only=true ;;
+            readonly=true|read-only=true) mount_read_only=true ;;
+            readonly=false|read-only=false) mount_read_only=false ;;
+            cache-ttl=*) mount_cache_ttl=${mount_field#cache-ttl=} ;;
+            *)
+                printf 'docker run: unsupported --mount field: %s\n' "$mount_field" >&2
+                return 125
+                ;;
+        esac
+    done
+    if [ "$mount_type" != bind ] || [ -z "$mount_source" ] || [ -z "$mount_destination" ]; then
+        printf 'docker run: --mount currently requires type=bind,src=PATH,dst=PATH\n' >&2
+        return 125
+    fi
+    case "$mount_cache_ttl" in
+        '') ;;
+        *[!0-9]*)
+            printf 'docker run: --mount cache-ttl must be an integer from 0 through 300: %s\n' "$mount_cache_ttl" >&2
+            return 125
+            ;;
+        *)
+            if [ "$mount_cache_ttl" -gt 300 ]; then
+                printf 'docker run: --mount cache-ttl must be an integer from 0 through 300: %s\n' "$mount_cache_ttl" >&2
+                return 125
+            fi
+            ;;
+    esac
+    create_run_bind_mount "$mount_source" "$mount_destination" "$mount_read_only" false "$mount_cache_ttl"
+}
+
+normalize_run_publish() {
+    publish_spec=$1
+    case "$publish_spec" in
+        */tcp) publish_spec=${publish_spec%/tcp} ;;
+        */*)
+            printf 'docker run: only TCP publishing is implemented: %s\n' "$1" >&2
+            return 125
+            ;;
+    esac
+    publish_ip=${publish_spec%%:*}
+    publish_rest=${publish_spec#*:}
+    publish_host_port=${publish_rest%%:*}
+    publish_container_port=${publish_rest#*:}
+    if [ "$publish_ip" != 127.0.0.1 ] || [ "$publish_rest" = "$publish_spec" ] || \
+        [ "$publish_container_port" = "$publish_rest" ]; then
+        printf 'docker run: publish must use 127.0.0.1:HOST:CONTAINER[/tcp]\n' >&2
+        return 125
+    fi
+    case "$publish_rest" in
+        *:*:*)
+            printf 'docker run: invalid publish specification: %s\n' "$1" >&2
+            return 125
+            ;;
+    esac
+    case "$publish_host_port" in ''|*[!0-9]*) printf 'docker run: invalid publish specification: %s\n' "$1" >&2; return 125 ;; esac
+    case "$publish_container_port" in ''|*[!0-9]*) printf 'docker run: invalid publish specification: %s\n' "$1" >&2; return 125 ;; esac
+    if [ "$publish_host_port" -lt 1 ] || [ "$publish_host_port" -gt 65535 ] || \
+        [ "$publish_container_port" -lt 1 ] || [ "$publish_container_port" -gt 65535 ]; then
+        printf 'docker run: published ports must be between 1 and 65535\n' >&2
+        return 125
+    fi
+    printf '127.0.0.1:%s:%s/tcp\n' "$publish_host_port" "$publish_container_port"
+}
+
+append_command_records() {
+    records_to_append=$1
+    [ -n "$records_to_append" ] || return 0
+    while IFS= read -r command_record; do
+        [ -n "$command_record" ] || continue
+        resolved_command=$resolved_command${resolved_command:+"
+"}$command_record
+    done <&2
+                return 125
+                ;;
+            --name|-w|--workdir|-u|--user|--entrypoint|-h|--hostname|--cpus|-m|--memory|--network|--net|--pull|--platform|-e|--env|--env-file|-v|--volume|--mount|-p|--publish)
+                option=$1
+                value=$(run_option_value "$option" "$#" "${2-}") || return $?
+                case "$option" in
+                    --name) requested_name=$value ;;
+                    -w|--workdir) workdir=$value ;;
+                    -u|--user) user_value=$value ;;
+                    --entrypoint) entrypoint=$value; entrypoint_set=true ;;
+                    -h|--hostname) hostname=$value ;;
+                    --cpus) cpus=$value ;;
+                    -m|--memory) memory=$value ;;
+                    --network|--net) network_mode=$value ;;
+                    --pull) pull_policy=$value ;;
+                    --platform) platform=$value ;;
+                    -e|--env) environment_operations=$environment_operations${environment_operations:+"
+"}v$value ;;
+                    --env-file) environment_operations=$environment_operations${environment_operations:+"
+"}f$value ;;
+                    -v|--volume) mount_operations=$mount_operations${mount_operations:+"
+"}v$value ;;
+                    --mount) mount_operations=$mount_operations${mount_operations:+"
+"}m$value ;;
+                    -p|--publish)
+                        normalized_publish=$(normalize_run_publish "$value") || return $?
+                        publish_records=$publish_records${publish_records:+"
+"}x$normalized_publish
+                        ;;
+                esac
+                shift 2
+                ;;
+            --name=*|--workdir=*|--user=*|--entrypoint=*|--hostname=*|--cpus=*|--memory=*|--network=*|--net=*|--pull=*|--platform=*|--env=*|--env-file=*|--volume=*|--mount=*|--publish=*)
+                option=${1%%=*}
+                value=${1#*=}
+                value=$(run_option_value "$option" 2 "$value") || return $?
+                case "$option" in
+                    --name) requested_name=$value ;;
+                    --workdir) workdir=$value ;;
+                    --user) user_value=$value ;;
+                    --entrypoint) entrypoint=$value; entrypoint_set=true ;;
+                    --hostname) hostname=$value ;;
+                    --cpus) cpus=$value ;;
+                    --memory) memory=$value ;;
+                    --network|--net) network_mode=$value ;;
+                    --pull) pull_policy=$value ;;
+                    --platform) platform=$value ;;
+                    --env) environment_operations=$environment_operations${environment_operations:+"
+"}v$value ;;
+                    --env-file) environment_operations=$environment_operations${environment_operations:+"
+"}f$value ;;
+                    --volume) mount_operations=$mount_operations${mount_operations:+"
+"}v$value ;;
+                    --mount) mount_operations=$mount_operations${mount_operations:+"
+"}m$value ;;
+                    --publish)
+                        normalized_publish=$(normalize_run_publish "$value") || return $?
+                        publish_records=$publish_records${publish_records:+"
+"}x$normalized_publish
+                        ;;
+                esac
+                shift
+                ;;
+            --read-only) read_only=true; shift ;;
+            --init) use_init=true; shift ;;
+            -i|--interactive) interactive=true; shift ;;
+            --)
+                shift
+                if [ "$#" -gt 0 ]; then image=$1; shift; fi
+                break
+                ;;
+            -*)
+                printf "docker run: unsupported option '%s'\n" "$1" >&2
+                return 125
+                ;;
+            *) image=$1; shift; break ;;
+        esac
+    done
+
+    cli_command_records=
+    for command_argument in "$@"; do
+        command_encoded=$(printf '%s' "$command_argument" | base64 | tr -d '\n')
+        cli_command_records=$cli_command_records${cli_command_records:+"
+"}x$command_encoded
+    done
+    if [ "$remove" != true ]; then
+        printf '%s\n' 'docker run: --rm is required until persistent containers are implemented' >&2
+        return 125
+    fi
+    if [ -z "$image" ]; then run_usage >&2; return 125; fi
+    case "$requested_name" in
+        '') ;;
+        *[!A-Za-z0-9_.-]*|[!A-Za-z0-9]*)
+            printf 'docker run: invalid container name: %s\n' "$requested_name" >&2
+            return 125
+            ;;
+    esac
+    if [ "${#requested_name}" -gt 128 ]; then
+        printf 'docker run: container name exceeds 128 bytes: %s\n' "$requested_name" >&2
+        return 125
+    fi
+    case "$hostname" in *'
+'*) printf '%s\n' 'docker run: invalid hostname' >&2; return 125 ;; esac
+    if [ -n "$workdir" ]; then
+        case "$workdir" in /*) ;; *) printf 'docker run: workdir must be absolute: %s\n' "$workdir" >&2; return 125 ;; esac
+    fi
+    case "$cpus" in ''|*[!0-9]*|0|0*) printf 'docker run: --cpus currently requires a positive integer\n' >&2; return 125 ;; esac
+    memory=$(parse_memory_bytes "$memory") || return $?
+    network_mode=${network_mode:-default}
+    case "$network_mode" in default|bridge) networking=true ;; none) networking=false ;; *) printf 'docker run: unsupported network mode: %s\n' "$network_mode" >&2; return 125 ;; esac
+    if [ "$networking" = false ] && [ -n "$publish_records" ]; then
+        printf '%s\n' 'docker run: port publishing is incompatible with --network=none' >&2
+        return 125
+    fi
+    case "$pull_policy" in always|missing|never) ;; *) printf 'docker run: invalid pull policy: %s\n' "$pull_policy" >&2; return 125 ;; esac
+    if [ "$platform" != linux/arm64 ]; then printf 'docker run: unsupported platform: %s\n' "$platform" >&2; return 125; fi
+    case "$GHOSTBOX_DOCKER_WAIT_TIMEOUT" in
+        ''|*[!0-9]*|0|0*) printf '%s\n' 'docker run: GHOSTBOX_DOCKER_WAIT_TIMEOUT must be a positive integer without leading zeroes' >&2; return 125 ;;
+    esac
+    if [ ! -x "$GHOSTBOX" ]; then printf "docker run: Ghostbox executable not found: %s\n" "$GHOSTBOX" >&2; return 127; fi
+
+    trap cleanup_run EXIT
+    trap 'exit 129' HUP
+    trap 'exit 130' INT
+    trap 'exit 143' TERM
+
+    image=$(normalize_image_reference "$image")
+    ensure_runtime
+    image_store=$(run_with_timeout 10 "$GHOSTBOX" cn:manager:image-store "$manager_ref")
+    case "$pull_policy" in
+        always)
+            image_ref=$(run_with_timeout 600 "$GHOSTBOX" cn:image-store:pull "$image_store" "$image" --platform "$platform")
+            ;;
+        missing)
+            if ! image_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:image-store:get "$image_store" "$image" --pull=false 2>/dev/null); then
+                image_ref=$(run_with_timeout 600 "$GHOSTBOX" cn:image-store:pull "$image_store" "$image" --platform "$platform")
+            fi
+            ;;
+        never)
+            if ! image_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:image-store:get "$image_store" "$image" --pull=false); then
+                printf 'docker run: image not found locally: %s\n' "$image" >&2
+                return 125
+            fi
+            ;;
+    esac
+
+    image_config=$(run_with_timeout 10 "$GHOSTBOX" cn:image:config "$image_ref" "$platform")
+    image_entrypoint_records=$(image_command_array_records Entrypoint)
+    image_cmd_records=$(image_command_array_records Cmd)
+    image_environment_records=$(image_array_records Env)
+    image_workdir=$(image_config_value WorkingDir)
+    image_user=$(image_config_value User)
+
+    resolved_environment=
+    if [ -n "$image_environment_records" ]; then
+        while IFS= read -r environment_record; do
+            [ -n "$environment_record" ] || continue
+            upsert_run_environment "${environment_record#x}"
+        done <&2; return 125; fi
+    [ -n "$workdir" ] || workdir=${image_workdir:-/}
+    [ -n "$user_value" ] || user_value=$image_user
+    user_json=
+    if [ -n "$user_value" ]; then user_json=$(normalize_run_user "$user_value") || return $?; fi
+
+    run_resource_name=docker-run-$(date +%s)-$$
+    container_name=${requested_name:-$run_resource_name}
+    process_config_name=$run_resource_name-process
+    stdout_name=$run_resource_name-stdout
+    stderr_name=$run_resource_name-stderr
+    mount_index=0
+
+    stdout_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:writer:create "$stdout_name")
+    stderr_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:writer:create "$stderr_name")
+    if [ "$interactive" = true ]; then
+        stdin_ref=$(run_with_timeout 10 "$GHOSTBOX" cn:reader-stream:create "$run_resource_name-stdin")
+    fi
+    if [ -n "$mount_operations" ]; then
+        while IFS= read -r mount_operation; do
+            [ -n "$mount_operation" ] || continue
+            case "$mount_operation" in
+                v*) create_run_volume_mount "${mount_operation#v}" ;;
+                m*) create_run_mount "${mount_operation#m}" ;;
+            esac
+        done <&2 &
+    stderr_pid=$!
+    if [ -n "$stdin_ref" ]; then
+        run_with_timeout "$attach_timeout" "$GHOSTBOX" cn:reader-stream:attach "$stdin_ref" &
+        stdin_pid=$!
+    fi
+    run_with_timeout 10 "$GHOSTBOX" cn:container:create "$container_ref" >/dev/null
+    run_with_timeout 10 "$GHOSTBOX" cn:container:start "$container_ref" >/dev/null
+    if [ -n "$publish_records" ]; then
+        forward_timeout=$((GHOSTBOX_DOCKER_WAIT_TIMEOUT + 10))
+        while IFS= read -r publish_record; do
+            [ -n "$publish_record" ] || continue
+            if [ "${GHOSTBOX_FORWARD_DIAGNOSTICS:-}" = 1 ]; then
+                run_with_timeout "$forward_timeout" "$GHOSTBOX" cn:container:forward "$container_ref" \
+                    -p "${publish_record#x}" >/dev/null &
+            else
+                run_with_timeout "$forward_timeout" "$GHOSTBOX" cn:container:forward "$container_ref" \
+                    -p "${publish_record#x}" >/dev/null 2>&1 &
+            fi
+            forward_pid=$!
+            run_forward_pids=$run_forward_pids${run_forward_pids:+"
+"}x$forward_pid
+        done <&2
+    exit 125
+fi
+
+command=$1
+shift
+case "$command" in
+    build)
+        build_image "$@"
+        ;;
+    pull)
+        pull_image "$@"
+        ;;
+    run)
+        run_image "$@"
+        ;;
+    --help|-h|help)
+        usage
+        ;;
+    *)
+        printf "docker: unsupported command '%s'\n" "$command" >&2
+        exit 125
+        ;;
+esac
diff --git a/scripts/ghostbox-docker-compose b/scripts/ghostbox-docker-compose
new file mode 100755
index 0000000..8734735
--- /dev/null
+++ b/scripts/ghostbox-docker-compose
@@ -0,0 +1,716 @@
+#!/usr/bin/ruby
+
+require "fileutils"
+require "json"
+require "shellwords"
+require "yaml"
+
+PROGRAM = "ghostbox-docker-compose"
+SCRIPT_PATH = File.expand_path(__FILE__)
+DEFAULT_DOCKER = File.join(File.dirname(SCRIPT_PATH), "ghostbox-docker")
+SERVICE_RUNNER = "__run-service"
+
+class ComposeError < StandardError
+end
+
+def usage
+  <<~USAGE
+    Usage: #{PROGRAM} [OPTIONS] COMMAND [ARGS...]
+
+    Options:
+      -f, --file PATH             Specify a Compose file
+      -p, --project-name NAME     Specify a project name
+          --env-file PATH         Specify an interpolation environment file
+
+    Commands:
+      config                      Parse and render the resolved configuration
+      pull [SERVICE...]           Pull service images
+      up [-d] [SERVICE...]        Create and start services
+      down                        Stop and remove services
+      ps                          List project services
+      logs [-f] [SERVICE...]      Show service logs
+
+    Supported service fields include image, command, entrypoint, environment,
+    env_file, ports, bind volumes, depends_on, working_dir, user, hostname,
+    read_only, init, cpus, mem_limit, network_mode, platform, and pull_policy.
+  USAGE
+end
+
+def state_root
+  return ENV["GHOSTBOX_DOCKER_COMPOSE_STATE"] unless ENV["GHOSTBOX_DOCKER_COMPOSE_STATE"].to_s.empty?
+  return File.join(ENV["XDG_STATE_HOME"], PROGRAM) unless ENV["XDG_STATE_HOME"].to_s.empty?
+
+  home = ENV["HOME"]
+  raise ComposeError, "HOME is required" if home.to_s.empty?
+
+  File.join(home, ".local", "state", PROGRAM)
+end
+
+def atomic_write(path, value)
+  FileUtils.mkdir_p(File.dirname(path))
+  temporary = "#{path}.#{Process.pid}.tmp"
+  File.open(temporary, "w", 0o600) { |file| file.write(value) }
+  File.rename(temporary, path)
+ensure
+  File.unlink(temporary) if defined?(temporary) && File.exist?(temporary)
+end
+
+def read_json(path)
+  JSON.parse(File.read(path))
+rescue Errno::ENOENT
+  nil
+rescue JSON::ParserError => error
+  raise ComposeError, "invalid state file #{path}: #{error.message}"
+end
+
+def write_json(path, value)
+  atomic_write(path, JSON.pretty_generate(value) + "\n")
+end
+
+def process_alive?(pid)
+  return false unless pid.is_a?(Integer) && pid.positive?
+
+  Process.kill(0, pid)
+  true
+rescue Errno::ESRCH
+  false
+rescue Errno::EPERM
+  true
+end
+
+def load_env_file(path)
+  values = {}
+  File.foreach(path).with_index(1) do |line, line_number|
+    line = line.strip
+    next if line.empty? || line.start_with?("#")
+
+    line = line.sub(/\Aexport\s+/, "")
+    key, value = line.split("=", 2)
+    unless key && key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+      raise ComposeError, "#{path}:#{line_number}: invalid environment assignment"
+    end
+
+    value = "" if value.nil?
+    if value.length >= 2 && value.start_with?("'") && value.end_with?("'")
+      value = value[1...-1]
+    elsif value.length >= 2 && value.start_with?("\"") && value.end_with?("\"")
+      value = value[1...-1].gsub(/\\([\\"nrt])/) do
+        { "\\" => "\\", "\"" => "\"", "n" => "\n", "r" => "\r", "t" => "\t" }[Regexp.last_match(1)]
+      end
+    else
+      value = value.sub(/\s+#.*\z/, "")
+    end
+    values[key] = value
+  end
+  values
+rescue Errno::ENOENT
+  raise ComposeError, "environment file not found: #{path}"
+end
+
+def interpolate_string(value, environment)
+  pattern = /\$\$|\$\{([A-Za-z_][A-Za-z0-9_]*)(?:(:?[-+?])(.*?))?\}|\$([A-Za-z_][A-Za-z0-9_]*)/
+  value.gsub(pattern) do |match|
+    next "$" if match == "$$"
+
+    name = Regexp.last_match(1) || Regexp.last_match(4)
+    operator = Regexp.last_match(2)
+    operand = Regexp.last_match(3).to_s
+    present = environment.key?(name)
+    current = environment[name].to_s
+    nonempty = present && !current.empty?
+
+    case operator
+    when nil then current
+    when ":-" then nonempty ? current : operand
+    when "-" then present ? current : operand
+    when ":+" then nonempty ? operand : ""
+    when "+" then present ? operand : ""
+    when ":?"
+      raise ComposeError, "#{name}: #{operand.empty? ? "variable is required" : operand}" unless nonempty
+      current
+    when "?"
+      raise ComposeError, "#{name}: #{operand.empty? ? "variable is required" : operand}" unless present
+      current
+    else
+      match
+    end
+  end
+end
+
+def interpolate(value, environment)
+  case value
+  when String
+    interpolate_string(value, environment)
+  when Array
+    value.map { |item| interpolate(item, environment) }
+  when Hash
+    value.each_with_object({}) do |(key, item), result|
+      result[interpolate_string(key.to_s, environment)] = interpolate(item, environment)
+    end
+  else
+    value
+  end
+end
+
+def find_compose_file(explicit_files)
+  unless explicit_files.empty?
+    raise ComposeError, "multiple Compose files are not implemented" if explicit_files.length > 1
+    return File.expand_path(explicit_files.first)
+  end
+
+  unless ENV["COMPOSE_FILE"].to_s.empty?
+    separator = File::PATH_SEPARATOR
+    files = ENV["COMPOSE_FILE"].split(separator)
+    raise ComposeError, "multiple Compose files are not implemented" if files.length > 1
+    return File.expand_path(files.first)
+  end
+
+  directory = Dir.pwd
+  loop do
+    %w[compose.yaml compose.yml docker-compose.yaml docker-compose.yml].each do |name|
+      candidate = File.join(directory, name)
+      return candidate if File.file?(candidate)
+    end
+    parent = File.dirname(directory)
+    break if parent == directory
+    directory = parent
+  end
+  raise ComposeError, "no Compose file found"
+end
+
+def load_config(path, interpolation_env_file)
+  raise ComposeError, "Compose file not found: #{path}" unless File.file?(path)
+
+  directory = File.dirname(path)
+  environment = {}
+  default_env = File.join(directory, ".env")
+  environment.merge!(load_env_file(default_env)) if File.file?(default_env)
+  environment.merge!(ENV.to_h)
+  environment.merge!(load_env_file(File.expand_path(interpolation_env_file))) if interpolation_env_file
+
+  raw = YAML.safe_load(
+    File.read(path),
+    permitted_classes: [],
+    permitted_symbols: [],
+    aliases: true,
+    filename: path
+  )
+  config = interpolate(raw, environment)
+  raise ComposeError, "#{path}: top level must be a mapping" unless config.is_a?(Hash)
+  raise ComposeError, "#{path}: services must be a mapping" unless config["services"].is_a?(Hash)
+
+  config["services"].each do |name, service|
+    unless name.match?(/\A[A-Za-z0-9][A-Za-z0-9_.-]*\z/) && service.is_a?(Hash)
+      raise ComposeError, "#{path}: invalid service #{name.inspect}"
+    end
+    raise ComposeError, "service #{name}: image is required; build is not implemented" if service["image"].to_s.empty?
+    raise ComposeError, "service #{name}: build is not implemented" if service.key?("build")
+    supported_fields = %w[
+      image command entrypoint environment env_file ports volumes depends_on
+      working_dir user hostname read_only init cpus mem_limit network_mode
+      platform pull_policy container_name networks
+    ]
+    unsupported_fields = service.keys.reject { |field| supported_fields.include?(field) || field.start_with?("x-") }
+    unless unsupported_fields.empty?
+      raise ComposeError, "service #{name}: unsupported field#{unsupported_fields.length == 1 ? "" : "s"} #{unsupported_fields.join(", ")}"
+    end
+    if service.key?("networks")
+      raise ComposeError, "service #{name}: custom networks are not implemented"
+    end
+  end
+  config
+rescue Psych::Exception => error
+  raise ComposeError, "invalid Compose file #{path}: #{error.message}"
+end
+
+def project_name(config, config_path, explicit)
+  name = explicit || ENV["COMPOSE_PROJECT_NAME"] || config["name"] || File.basename(File.dirname(config_path))
+  name = name.to_s.downcase.gsub(/[^a-z0-9_-]+/, "-").sub(/\A[-_]+/, "").sub(/[-_]+\z/, "")
+  raise ComposeError, "project name is empty after normalization" if name.empty?
+  raise ComposeError, "project name is too long" if name.length > 63
+  name
+end
+
+def selected_services(config, requested, include_dependencies: false)
+  services = config.fetch("services")
+  names = requested.empty? ? services.keys : requested
+  unknown = names.reject { |name| services.key?(name) }
+  raise ComposeError, "unknown service#{unknown.length == 1 ? "" : "s"}: #{unknown.join(", ")}" unless unknown.empty?
+
+  return names unless include_dependencies
+
+  ordered = []
+  visiting = {}
+  visit = lambda do |name|
+    raise ComposeError, "circular depends_on includes #{name}" if visiting[name] == :active
+    return if visiting[name] == :done
+
+    visiting[name] = :active
+    dependency_value = services.fetch(name)["depends_on"]
+    dependencies = dependency_value.is_a?(Hash) ? dependency_value.keys : Array(dependency_value)
+    dependencies.each do |dependency|
+      raise ComposeError, "service #{name}: unknown dependency #{dependency}" unless services.key?(dependency)
+      visit.call(dependency)
+    end
+    visiting[name] = :done
+    ordered << name
+  end
+  names.each { |name| visit.call(name) }
+  ordered
+end
+
+def scalar_arguments(value, field, service)
+  case value
+  when nil then []
+  when String then Shellwords.shellsplit(value)
+  when Array then value.map(&:to_s)
+  else
+    raise ComposeError, "service #{service}: #{field} must be a string or list"
+  end
+rescue ArgumentError => error
+  raise ComposeError, "service #{service}: invalid #{field}: #{error.message}"
+end
+
+def environment_arguments(value, service)
+  case value
+  when nil
+    []
+  when Hash
+    value.map { |key, item| item.nil? ? key.to_s : "#{key}=#{item}" }
+  when Array
+    value.map(&:to_s)
+  else
+    raise ComposeError, "service #{service}: environment must be a mapping or list"
+  end
+end
+
+def volume_argument(value, config_directory, service)
+  if value.is_a?(Hash)
+    type = value["type"] || "volume"
+    raise ComposeError, "service #{service}: only bind volumes are implemented" unless type == "bind"
+    source = value["source"]
+    target = value["target"]
+    raise ComposeError, "service #{service}: bind volume requires source and target" if source.to_s.empty? || target.to_s.empty?
+    source = File.expand_path(source, config_directory)
+    return "#{source}:#{target}#{value["read_only"] ? ":ro" : ""}"
+  end
+
+  parts = value.to_s.split(":", 3)
+  raise ComposeError, "service #{service}: volume must include source and target" if parts.length < 2
+  source = parts[0]
+  unless source.start_with?("/", ".", "~")
+    raise ComposeError, "service #{service}: named volume #{source} is not implemented"
+  end
+  source = File.expand_path(source, config_directory)
+  ([source] + parts.drop(1)).join(":")
+end
+
+def port_argument(value, service)
+  if value.is_a?(Hash)
+    protocol = (value["protocol"] || "tcp").to_s
+    raise ComposeError, "service #{service}: only TCP ports are implemented" unless protocol == "tcp"
+    host = (value["host_ip"] || "127.0.0.1").to_s
+    published = value["published"]
+    target = value["target"]
+    if published.to_s.empty? || target.to_s.empty?
+      raise ComposeError, "service #{service}: published and target ports are required"
+    end
+    raise ComposeError, "service #{service}: ports must bind to 127.0.0.1" unless host == "127.0.0.1"
+    return "#{host}:#{published}:#{target}/tcp"
+  end
+
+  specification = value.to_s
+  protocol = specification.include?("/") ? specification.split("/", 2)[1] : "tcp"
+  raise ComposeError, "service #{service}: only TCP ports are implemented" unless protocol == "tcp"
+  specification = specification.split("/", 2)[0]
+  parts = specification.split(":")
+  parts.unshift("127.0.0.1") if parts.length == 2
+  unless parts.length == 3 && parts[0] == "127.0.0.1"
+    raise ComposeError, "service #{service}: port must be HOST:CONTAINER or 127.0.0.1:HOST:CONTAINER"
+  end
+  "#{parts.join(":")}/tcp"
+end
+
+def service_run_arguments(project, name, service, config_directory)
+  container_name = service["container_name"] || "#{project}-#{name}-1"
+  arguments = ["run", "--rm", "--name", container_name.to_s]
+
+  {
+    "working_dir" => "--workdir",
+    "user" => "--user",
+    "hostname" => "--hostname",
+    "cpus" => "--cpus",
+    "mem_limit" => "--memory",
+    "network_mode" => "--network",
+    "platform" => "--platform"
+  }.each do |field, option|
+    arguments.concat([option, service[field].to_s]) if service.key?(field)
+  end
+  arguments << "--read-only" if service["read_only"]
+  arguments << "--init" if service["init"]
+
+  pull_policy = service["pull_policy"]
+  if pull_policy
+    pull_policy = { "if_not_present" => "missing" }.fetch(pull_policy.to_s, pull_policy.to_s)
+    unless %w[always missing never].include?(pull_policy)
+      raise ComposeError, "service #{name}: unsupported pull_policy #{pull_policy}"
+    end
+    arguments.concat(["--pull", pull_policy])
+  end
+
+  environment_arguments(service["environment"], name).each { |value| arguments.concat(["--env", value]) }
+  Array(service["env_file"]).each do |path|
+    path = path["path"] if path.is_a?(Hash)
+    arguments.concat(["--env-file", File.expand_path(path.to_s, config_directory)])
+  end
+  Array(service["volumes"]).each do |volume|
+    arguments.concat(["--volume", volume_argument(volume, config_directory, name)])
+  end
+  Array(service["ports"]).each do |port|
+    arguments.concat(["--publish", port_argument(port, name)])
+  end
+
+  command = scalar_arguments(service["command"], "command", name)
+  entrypoint = scalar_arguments(service["entrypoint"], "entrypoint", name)
+  unless entrypoint.empty?
+    arguments.concat(["--entrypoint", entrypoint.shift])
+    command = entrypoint + command
+  end
+  arguments << service.fetch("image").to_s
+  arguments.concat(command)
+  arguments
+end
+
+def update_runner_state(path, attributes)
+  state = read_json(path) || {}
+  write_json(path, state.merge(attributes))
+end
+
+def run_service_runner(arguments)
+  docker = arguments.shift
+  state_path = arguments.shift
+  child = nil
+  stopping = false
+  forward_signal = proc do |signal|
+    stopping = true
+    begin
+      Process.kill(signal, child) if child
+    rescue Errno::ESRCH
+      nil
+    end
+  end
+  Signal.trap("TERM") { forward_signal.call("TERM") }
+  Signal.trap("INT") { forward_signal.call("INT") }
+  Signal.trap("HUP") { forward_signal.call("HUP") }
+
+  child = Process.spawn(
+    { "GHOSTBOX_DOCKER_WAIT_TIMEOUT" => ENV.fetch("GHOSTBOX_DOCKER_COMPOSE_WAIT_TIMEOUT", "31536000") },
+    docker,
+    *arguments
+  )
+  Process.kill("TERM", child) if stopping
+  update_runner_state(state_path, "pid" => Process.pid, "status" => "running", "started_at" => Time.now.utc.to_s)
+  _pid, status = Process.wait2(child)
+  exit_code = status.exited? ? status.exitstatus : 128 + status.termsig
+  update_runner_state(
+    state_path,
+    "pid" => nil,
+    "status" => "exited",
+    "exit_code" => exit_code,
+    "finished_at" => Time.now.utc.to_s
+  )
+  exit(exit_code)
+rescue StandardError => error
+  update_runner_state(state_path, "pid" => nil, "status" => "failed", "error" => error.message) if state_path
+  warn "#{PROGRAM}: service runner failed: #{error.message}"
+  exit(125)
+end
+
+def service_state_path(project_directory, service)
+  File.join(project_directory, "services", "#{service}.json")
+end
+
+def start_service(project_directory, project, name, service, config_directory, docker)
+  state_path = service_state_path(project_directory, name)
+  existing = read_json(state_path)
+  if existing && existing["status"] == "running" && process_alive?(existing["pid"])
+    puts "#{name} is already running"
+    return existing["pid"]
+  end
+
+  arguments = service_run_arguments(project, name, service, config_directory)
+  log_path = File.join(project_directory, "logs", "#{name}.log")
+  FileUtils.mkdir_p(File.dirname(log_path))
+  File.open(log_path, "w") {}
+  write_json(
+    state_path,
+    "service" => name,
+    "container_name" => (service["container_name"] || "#{project}-#{name}-1"),
+    "image" => service["image"].to_s,
+    "status" => "starting",
+    "pid" => nil,
+    "log" => log_path
+  )
+
+  pid = Process.spawn(
+    SCRIPT_PATH,
+    SERVICE_RUNNER,
+    docker,
+    state_path,
+    *arguments,
+    out: [log_path, "a"],
+    err: [:child, :out],
+    pgroup: true
+  )
+  Process.detach(pid)
+
+  deadline = Time.now + 5
+  loop do
+    state = read_json(state_path)
+    break if state && state["status"] == "running"
+    break if state && state["status"] == "exited" && state["exit_code"] == 0
+    if state && %w[failed exited].include?(state["status"])
+      detail = state["error"] || "exit status #{state["exit_code"]}"
+      raise ComposeError, "service #{name} failed to start: #{detail}"
+    end
+    raise ComposeError, "service #{name} did not start within 5 seconds" if Time.now >= deadline
+    sleep(0.05)
+  end
+  puts "#{name} started"
+  pid
+rescue SystemCallError => error
+  update_runner_state(state_path, "status" => "failed", "error" => error.message)
+  raise ComposeError, "service #{name}: #{error.message}"
+end
+
+def stop_project(project_directory, timeout)
+  paths = Dir.glob(File.join(project_directory, "services", "*.json"))
+  states = paths.map { |path| [path, read_json(path)] }.reject { |_path, state| state.nil? }
+  states.each do |_path, state|
+    pid = state["pid"]
+    next unless process_alive?(pid)
+
+    puts "#{state["service"]} stopping"
+    Process.kill("TERM", pid)
+  rescue Errno::ESRCH
+    nil
+  end
+
+  deadline = Time.now + timeout
+  states.each do |_path, state|
+    pid = state["pid"]
+    next unless pid
+    sleep(0.05) while process_alive?(pid) && Time.now < deadline
+    next unless process_alive?(pid)
+
+    Process.kill("KILL", pid)
+  rescue Errno::ESRCH
+    nil
+  end
+  FileUtils.rm_rf(File.join(project_directory, "services"))
+  FileUtils.rm_rf(File.join(project_directory, "logs"))
+  FileUtils.rm_f(File.join(project_directory, "project.json"))
+end
+
+def print_logs(project_directory, names, tail, follow, stop_requested = nil)
+  offsets = {}
+  names.each do |name|
+    state = read_json(service_state_path(project_directory, name))
+    raise ComposeError, "no container exists for service #{name}" unless state
+    path = state["log"]
+    lines = File.file?(path) ? File.readlines(path) : []
+    lines = lines.last(tail) if tail
+    lines.each { |line| print "#{name} | #{line}" }
+    offsets[name] = File.file?(path) ? File.size(path) : 0
+  end
+  return unless follow
+
+  loop do
+    break if stop_requested && stop_requested.call
+
+    names.each do |name|
+      state = read_json(service_state_path(project_directory, name))
+      next unless state && File.file?(state["log"])
+
+      File.open(state["log"]) do |file|
+        file.seek(offsets[name])
+        file.each_line { |line| print "#{name} | #{line}" }
+        offsets[name] = file.pos
+      end
+    end
+    break unless names.any? do |name|
+      state = read_json(service_state_path(project_directory, name))
+      state && state["status"] == "running" && process_alive?(state["pid"])
+    end
+    sleep(0.1)
+  end
+end
+
+def parse_global_options(arguments)
+  options = { files: [], project: nil, env_file: nil }
+  loop do
+    case arguments.first
+    when "-f", "--file"
+      arguments.shift
+      options[:files] << (arguments.shift || raise(ComposeError, "--file requires a value"))
+    when /\A--file=(.*)\z/
+      options[:files] << Regexp.last_match(1)
+      arguments.shift
+    when "-p", "--project-name"
+      arguments.shift
+      options[:project] = arguments.shift || raise(ComposeError, "--project-name requires a value")
+    when /\A--project-name=(.*)\z/
+      options[:project] = Regexp.last_match(1)
+      arguments.shift
+    when "--env-file"
+      arguments.shift
+      options[:env_file] = arguments.shift || raise(ComposeError, "--env-file requires a value")
+    when /\A--env-file=(.*)\z/
+      options[:env_file] = Regexp.last_match(1)
+      arguments.shift
+    when "--help", "-h"
+      puts usage
+      exit(0)
+    else
+      break
+    end
+  end
+  options
+end
+
+def main(arguments)
+  if arguments.first == SERVICE_RUNNER
+    arguments.shift
+    run_service_runner(arguments)
+  end
+
+  options = parse_global_options(arguments)
+  command = arguments.shift
+  raise ComposeError, "a command is required\n\n#{usage}" unless command
+
+  config_path = find_compose_file(options[:files])
+  config = load_config(config_path, options[:env_file])
+  project = project_name(config, config_path, options[:project])
+  project_directory = File.join(state_root, project)
+  docker = ENV.fetch("GHOSTBOX_DOCKER", DEFAULT_DOCKER)
+
+  case command
+  when "config"
+    if arguments == ["--services"]
+      puts config.fetch("services").keys
+    elsif arguments.empty?
+      puts YAML.dump(config)
+    else
+      raise ComposeError, "config: unsupported option #{arguments.first}"
+    end
+  when "pull"
+    names = selected_services(config, arguments)
+    raise ComposeError, "Docker helper not found: #{docker}" unless File.executable?(docker)
+    names.each do |name|
+      service = config.fetch("services").fetch(name)
+      pull_arguments = ["pull"]
+      pull_arguments.concat(["--platform", service["platform"].to_s]) if service["platform"]
+      pull_arguments << service.fetch("image").to_s
+      puts "Pulling #{name}"
+      success = system(docker, *pull_arguments)
+      raise ComposeError, "failed to pull service #{name}" unless success
+    end
+  when "up"
+    detached = false
+    requested = []
+    until arguments.empty?
+      case arguments.first
+      when "-d", "--detach" then detached = true
+      when "--no-build" then nil
+      when "--help"
+        puts "Usage: #{PROGRAM} up [-d] [SERVICE...]"
+        return
+      when /\A-/ then raise ComposeError, "up: unsupported option #{arguments.first}"
+      else requested << arguments.first
+      end
+      arguments.shift
+    end
+    raise ComposeError, "Docker helper not found: #{docker}" unless File.executable?(docker)
+    names = selected_services(config, requested, include_dependencies: true)
+    FileUtils.mkdir_p(project_directory)
+    write_json(File.join(project_directory, "project.json"), "project" => project, "config" => config_path, "services" => names)
+    names.each do |name|
+      start_service(project_directory, project, name, config.fetch("services").fetch(name), File.dirname(config_path), docker)
+    end
+    return if detached
+
+    interrupted = false
+    Signal.trap("INT") { interrupted = true }
+    Signal.trap("TERM") { interrupted = true }
+    print_logs(project_directory, names, nil, true, proc { interrupted })
+    stop_project(project_directory, 10) if interrupted
+  when "down"
+    timeout = 10
+    until arguments.empty?
+      case arguments.first
+      when "--timeout", "-t"
+        arguments.shift
+        timeout = Integer(arguments.shift || raise(ComposeError, "--timeout requires a value"), 10)
+      when /\A--timeout=(.*)\z/
+        timeout = Integer(Regexp.last_match(1), 10)
+      else
+        raise ComposeError, "down: unsupported option #{arguments.first}"
+      end
+      arguments.shift
+    end
+    raise ComposeError, "down: timeout must be positive" unless timeout.positive?
+    stop_project(project_directory, timeout)
+  when "ps"
+    services_only = arguments.delete("--services")
+    raise ComposeError, "ps: unsupported option #{arguments.first}" unless arguments.empty?
+    names = config.fetch("services").keys
+    if services_only
+      names.each { |name| puts name if File.file?(service_state_path(project_directory, name)) }
+      return
+    end
+    puts format("%-24s %-12s %s", "NAME", "STATUS", "IMAGE")
+    names.each do |name|
+      state = read_json(service_state_path(project_directory, name))
+      next unless state
+      status = state["status"]
+      status = "exited" if status == "running" && !process_alive?(state["pid"])
+      status = "#{status} (#{state["exit_code"]})" if state.key?("exit_code")
+      puts format("%-24s %-12s %s", name, status, state["image"])
+    end
+  when "logs"
+    follow = false
+    tail = nil
+    requested = []
+    until arguments.empty?
+      case arguments.first
+      when "-f", "--follow" then follow = true
+      when "--tail"
+        arguments.shift
+        value = arguments.shift || raise(ComposeError, "--tail requires a value")
+        tail = value == "all" ? nil : Integer(value, 10)
+      when /\A--tail=(.*)\z/
+        value = Regexp.last_match(1)
+        tail = value == "all" ? nil : Integer(value, 10)
+      when /\A-/ then raise ComposeError, "logs: unsupported option #{arguments.first}"
+      else requested << arguments.first
+      end
+      arguments.shift
+    end
+    raise ComposeError, "logs: tail must not be negative" if tail && tail.negative?
+    names = selected_services(config, requested)
+    print_logs(project_directory, names, tail, follow)
+  when "help", "--help", "-h"
+    puts usage
+  else
+    raise ComposeError, "unsupported command #{command}"
+  end
+rescue ArgumentError => error
+  raise ComposeError, error.message
+end
+
+begin
+  main(ARGV.dup)
+rescue ComposeError => error
+  warn "#{PROGRAM}: #{error.message}"
+  exit(1)
+end
diff --git a/scripts/gui-complete-ghostfile-folder.ts b/scripts/gui-complete-ghostfile-folder.ts
new file mode 100644
index 0000000..b730a84
--- /dev/null
+++ b/scripts/gui-complete-ghostfile-folder.ts
@@ -0,0 +1,15 @@
+import gui, { GuiKey, GuiKeyChord, GuiModifierKey } from "gui";
+import { setTimeout as delay } from "node:timers/promises";
+
+await gui.permissions.RequestPostInput();
+
+const input = gui.input.Direct();
+await input.Press(
+  GuiKeyChord.WithModifiers(GuiKey.Character("a"), [GuiModifierKey.Command()]),
+);
+await input.PasteText("/Users/bender/Desktop/GhostVM/tmp/GhostFileShare");
+await delay(300);
+await input.PressKey(GuiKey.Named("return"));
+await delay(800);
+await input.PressKey(GuiKey.Named("return"));
+await delay(800);
diff --git a/scripts/gui-enable-ghostfile-extension.ts b/scripts/gui-enable-ghostfile-extension.ts
new file mode 100644
index 0000000..caf4e98
--- /dev/null
+++ b/scripts/gui-enable-ghostfile-extension.ts
@@ -0,0 +1,28 @@
+import gui from "gui";
+
+await gui.permissions.RequestPostInput();
+await gui.permissions.RequestViewHierarchyAccess();
+
+const app = gui.applications.Named("System Settings");
+await app.Focus();
+const window = (await app.Windows().All())[0];
+if (!window) throw new Error("System Settings window not found");
+let root = await window.RootNode();
+const switches = await root.FindAll(async (node) => await node.Role() === "AXCheckBox");
+let moduleSwitch = null;
+for (const candidate of switches.All()) {
+  const frame = await candidate.Frame();
+  if (frame && frame.origin.x > 1300 && frame.origin.y > 330 && frame.origin.y < 430) {
+    moduleSwitch = candidate;
+    break;
+  }
+}
+if (!moduleSwitch) throw new Error("FSKit Modules switch not found");
+await moduleSwitch.Press();
+
+root = await window.RootNode();
+const done = await root.Find(async (node) =>
+  await node.Role() === "AXButton" && await node.AccessibleName() === "Done"
+);
+if (!done) throw new Error("Done button not found");
+await done.Press();
diff --git a/scripts/gui-inspect-ghostfile.ts b/scripts/gui-inspect-ghostfile.ts
new file mode 100644
index 0000000..577fea6
--- /dev/null
+++ b/scripts/gui-inspect-ghostfile.ts
@@ -0,0 +1,22 @@
+import gui from "gui";
+
+await gui.permissions.RequestViewHierarchyAccess();
+
+const app = gui.applications.Named("GhostFile");
+const windows = await app.Windows().All();
+const lines = [`windows=${windows.length}`];
+for (let windowIndex = 0; windowIndex < windows.length; windowIndex += 1) {
+  const window = windows[windowIndex];
+  lines.push(`window[${windowIndex}] title=${await window.Title()}`);
+  const nodes = await (await window.RootNode()).SelfAndDescendants();
+  for (let nodeIndex = 0; nodeIndex < nodes.Count(); nodeIndex += 1) {
+    const node = nodes.At(nodeIndex)!;
+    const role = await node.Role();
+    const name = await node.AccessibleName();
+    const value = await node.Value();
+    if (name || value) {
+      lines.push(`  ${nodeIndex}: role=${role} name=${JSON.stringify(name)} value=${JSON.stringify(value)} frame=${JSON.stringify(await node.Frame())}`);
+    }
+  }
+}
+await gui.pasteboard.SetText(lines.join("\n"));
diff --git a/scripts/gui-inspect-system-settings.ts b/scripts/gui-inspect-system-settings.ts
new file mode 100644
index 0000000..cff9e77
--- /dev/null
+++ b/scripts/gui-inspect-system-settings.ts
@@ -0,0 +1,22 @@
+import gui from "gui";
+
+await gui.permissions.RequestViewHierarchyAccess();
+
+const app = gui.applications.Named("System Settings");
+const windows = await app.Windows().All();
+const lines = [`windows=${windows.length}`];
+for (let windowIndex = 0; windowIndex < windows.length; windowIndex += 1) {
+  const window = windows[windowIndex];
+  lines.push(`window[${windowIndex}] title=${await window.Title()}`);
+  const nodes = await (await window.RootNode()).SelfAndDescendants();
+  for (let nodeIndex = 0; nodeIndex < nodes.Count(); nodeIndex += 1) {
+    const node = nodes.At(nodeIndex)!;
+    const role = await node.Role();
+    const name = await node.AccessibleName();
+    const value = await node.Value();
+    if (name || value || role === "AXCheckBox") {
+      lines.push(`  ${nodeIndex}: role=${role} name=${JSON.stringify(name)} value=${JSON.stringify(value)} frame=${JSON.stringify(await node.Frame())}`);
+    }
+  }
+}
+await gui.pasteboard.SetText(lines.join("\n"));
diff --git a/scripts/gui-open-ghostfile-extension.ts b/scripts/gui-open-ghostfile-extension.ts
new file mode 100644
index 0000000..706933e
--- /dev/null
+++ b/scripts/gui-open-ghostfile-extension.ts
@@ -0,0 +1,39 @@
+import gui, { GuiPoint, GuiScrollDelta } from "gui";
+
+await gui.permissions.RequestPostInput();
+await gui.permissions.RequestViewHierarchyAccess();
+
+const app = gui.applications.Named("System Settings");
+await app.Focus();
+const input = gui.input.Direct();
+let window = (await app.Windows().All())[0];
+if (!window) throw new Error("System Settings window not found");
+
+await input.Scroll(GuiPoint.At(1400, 900), GuiScrollDelta.Pixels(0, -420));
+let root = await window.RootNode();
+const ghostFile = await root.Find(async (node) =>
+  await node.Role() === "AXStaticText" && await node.AccessibleName() === "GhostFile"
+);
+if (!ghostFile) throw new Error("GhostFile extension row not found");
+await ghostFile.Focus();
+root = await window.RootNode();
+const visibleGhostFile = await root.Find(async (node) =>
+  await node.Role() === "AXStaticText" && await node.AccessibleName() === "GhostFile"
+);
+if (!visibleGhostFile) throw new Error("GhostFile extension row disappeared");
+const ghostFrame = await visibleGhostFile.Frame();
+if (!ghostFrame) throw new Error("GhostFile row has no frame");
+
+const detailButtons = await root.FindAll(async (node) =>
+  await node.Role() === "AXButton" && await node.AccessibleName() === "Show Detail"
+);
+let detail = null;
+for (const button of detailButtons.All()) {
+  const frame = await button.Frame();
+  if (frame && Math.abs(frame.origin.y - ghostFrame.origin.y) < 8) {
+    detail = button;
+    break;
+  }
+}
+if (!detail) throw new Error("GhostFile Show Detail button not found");
+await input.ClickNode(detail);
diff --git a/scripts/gui-start-ghostfile-share.ts b/scripts/gui-start-ghostfile-share.ts
new file mode 100644
index 0000000..e70c8f5
--- /dev/null
+++ b/scripts/gui-start-ghostfile-share.ts
@@ -0,0 +1,121 @@
+import gui, { GuiKey, GuiKeyChord, GuiModifierKey, GuiPoint, GuiWaitTimeout } from "gui";
+import { setTimeout as delay } from "node:timers/promises";
+
+const sharePath = "/Users/bender/Desktop/GhostVM/tmp/GhostFileShare";
+const accessKey = "ghostfile-test-key";
+
+await gui.permissions.RequestPostInput();
+await gui.permissions.RequestViewHierarchyAccess();
+
+const app = gui.applications.Named("GhostFile");
+await app.Focus();
+const input = gui.input.Direct();
+let windows = await app.Windows().All();
+let window: (typeof windows)[number] | null = null;
+for (const candidate of windows) {
+  if (await candidate.Title() === "GhostFile") window = candidate;
+}
+if (!window) throw new Error("GhostFile window not found");
+
+let initialRoot = await window.RootNode();
+const selectedFolder = await initialRoot.Find(
+  async (node) => await node.AccessibleName() === sharePath,
+);
+if (!selectedFolder) {
+  let dialog: (typeof windows)[number] | null = null;
+  for (const candidate of windows) {
+    if (await candidate.Title() === "Choose a folder to share") dialog = candidate;
+  }
+  if (dialog) {
+    await dialog.Raise();
+    await delay(200);
+    let goToRoot = await dialog.RootNode();
+    let goToFields = await goToRoot.FindAll(async (node) => await node.Role() === "AXTextField");
+    let goToField = null;
+    for (const field of goToFields.All()) {
+      const frame = await field.Frame();
+      if (frame && frame.size.width > 300 && frame.origin.y > 220 && frame.origin.y < 320) {
+        goToField = field;
+        break;
+      }
+    }
+    if (!goToField) {
+      await input.Press(
+        GuiKeyChord.WithModifiers(GuiKey.Character("g"), [GuiModifierKey.Command(), GuiModifierKey.Shift()]),
+      );
+      await delay(300);
+      goToRoot = await dialog.RootNode();
+      goToFields = await goToRoot.FindAll(async (node) => await node.Role() === "AXTextField");
+      for (const field of goToFields.All()) {
+        const frame = await field.Frame();
+        if (frame && frame.size.width > 300 && frame.origin.y > 220 && frame.origin.y < 320) {
+          goToField = field;
+          break;
+        }
+      }
+    }
+    if (!goToField) throw new Error("Go to folder field not found");
+    await goToField.Focus();
+    await input.Press(
+      GuiKeyChord.WithModifiers(GuiKey.Character("a"), [GuiModifierKey.Command()]),
+    );
+    await input.PasteText(sharePath);
+    await input.PressKey(GuiKey.Named("return"));
+    await delay(800);
+    const dialogRoot = await dialog.RootNode();
+    const confirm = await dialogRoot.Find(async (node) => await node.AccessibleName() === "Share Folder");
+    if (!confirm) throw new Error("Share Folder button not found");
+    await input.ClickNode(confirm);
+    await delay(800);
+  } else {
+  const choose = await initialRoot.Find(async (node) => await node.AccessibleName() === "Choose…");
+  if (!choose) throw new Error("Choose button not found");
+  await input.ClickNode(choose);
+  await input.Press(
+    GuiKeyChord.WithModifiers(GuiKey.Character("g"), [GuiModifierKey.Command(), GuiModifierKey.Shift()]),
+  );
+  await input.PasteText(sharePath);
+  await input.PressKey(GuiKey.Named("return"));
+  await delay(500);
+  await input.PressKey(GuiKey.Named("return"));
+  await delay(500);
+  }
+}
+
+let root = await window.RootNode();
+const fields = await root.FindAll(async (node) => await node.Role() === "AXTextField");
+if (fields.Count() < 3) throw new Error(`Expected three text fields, found ${fields.Count()}`);
+async function replaceFocusedText(value: string) {
+  await input.Press(
+    GuiKeyChord.WithModifiers(GuiKey.Character("a"), [GuiModifierKey.Command()]),
+  );
+  await input.PasteText(value);
+}
+await fields.At(0)!.Focus();
+await replaceFocusedText("GhostFileQUIC");
+await fields.At(1)!.Focus();
+await replaceFocusedText("0");
+await fields.At(2)!.Focus();
+await replaceFocusedText(accessKey);
+
+const start = await root.Find(async (node) => await node.AccessibleName() === "Start Sharing");
+if (!start) throw new Error("Start Sharing button not found");
+await start.WaitUntilActionable(GuiWaitTimeout.Seconds(5));
+const startFrame = await start.Frame();
+if (!startFrame) throw new Error("Start Sharing button has no frame");
+await input.Click(
+  GuiPoint.At(
+    startFrame.origin.x + startFrame.size.width / 2,
+    startFrame.origin.y + startFrame.size.height / 2,
+  ),
+);
+
+root = await window.RootNode();
+const lines: string[] = [];
+const nodes = await root.SelfAndDescendants();
+for (const node of nodes.All()) {
+  const name = await node.AccessibleName();
+  const value = await node.Value();
+  if (name || value) lines.push(`${await node.Role()} ${JSON.stringify(name)} ${JSON.stringify(value)}`);
+}
+await gui.pasteboard.SetText(lines.join("\n"));
diff --git a/scripts/notarize-ghostfile-dmg.sh b/scripts/notarize-ghostfile-dmg.sh
new file mode 100755
index 0000000..c74e4c3
--- /dev/null
+++ b/scripts/notarize-ghostfile-dmg.sh
@@ -0,0 +1,99 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+dmg_path=${1:-}
+timeout=${NOTARY_TIMEOUT:-45m}
+profile=${NOTARY_KEYCHAIN_PROFILE:-}
+keychain=${NOTARY_KEYCHAIN_PATH:-}
+key_file=${NOTARY_KEY_FILE:-}
+key_id=${NOTARY_KEY_ID:-}
+issuer_id=${NOTARY_ISSUER_ID:-}
+apple_id=${NOTARY_APPLE_ID:-}
+team_id=${NOTARY_TEAM_ID:-}
+password=${NOTARY_PASSWORD:-}
+lsregister=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
+
+if [[ -z "$dmg_path" || ! -f "$dmg_path" || "${dmg_path:e}" != "dmg" ]]; then
+    print -u2 "usage: $0 PATH_TO_SIGNED_DMG"
+    exit 64
+fi
+dmg_path=${dmg_path:A}
+result_path="${dmg_path:r}.notary-result.json"
+log_path="${dmg_path:r}.notary-log.json"
+
+typeset -a auth_args
+if [[ -n "$profile" ]]; then
+    auth_args=(--keychain-profile "$profile")
+    [[ -n "$keychain" ]] && auth_args+=(--keychain "$keychain")
+elif [[ -n "$key_file" && -n "$key_id" ]]; then
+    auth_args=(--key "$key_file" --key-id "$key_id")
+    [[ -n "$issuer_id" ]] && auth_args+=(--issuer "$issuer_id")
+elif [[ -n "$apple_id" && -n "$team_id" && -n "$password" ]]; then
+    auth_args=(--apple-id "$apple_id" --team-id "$team_id" --password "$password")
+else
+    print -u2 "No notarization credentials configured."
+    print -u2 "Set NOTARY_KEYCHAIN_PROFILE; NOTARY_KEY_FILE + NOTARY_KEY_ID; or"
+    print -u2 "NOTARY_APPLE_ID + NOTARY_TEAM_ID + NOTARY_PASSWORD."
+    exit 78
+fi
+
+print "Verifying signed disk image before upload…"
+/usr/bin/codesign --verify --verbose=2 "$dmg_path"
+/usr/bin/hdiutil verify "$dmg_path" >/dev/null
+
+print "Submitting ${dmg_path:t} to Apple’s notary service…"
+submit_succeeded=1
+if ! /usr/bin/xcrun notarytool submit "$dmg_path" \
+    "${auth_args[@]}" \
+    --wait \
+    --timeout "$timeout" \
+    --output-format json > "$result_path"; then
+    submit_succeeded=0
+fi
+
+notary_status=$(/usr/bin/plutil -extract status raw "$result_path" 2>/dev/null || true)
+submission_id=$(/usr/bin/plutil -extract id raw "$result_path" 2>/dev/null || true)
+if (( ! submit_succeeded )) || [[ "$notary_status" != "Accepted" ]]; then
+    print -u2 "Notarization failed with status: ${notary_status:-unknown}"
+    if [[ -n "$submission_id" ]]; then
+        /usr/bin/xcrun notarytool log "$submission_id" "$log_path" "${auth_args[@]}" || true
+        print -u2 "Notary log: $log_path"
+    fi
+    exit 65
+fi
+
+print "Notarization accepted; stapling ticket…"
+/usr/bin/xcrun stapler staple "$dmg_path"
+/usr/bin/xcrun stapler validate "$dmg_path"
+/usr/bin/codesign --verify --verbose=2 "$dmg_path"
+/usr/sbin/spctl --assess --type open --context context:primary-signature --verbose=2 "$dmg_path"
+
+work_dir=$(/usr/bin/mktemp -d "${TMPDIR:-/tmp}/ghostfile-notary-check.XXXXXX")
+mount_dir="$work_dir/mount"
+mkdir "$mount_dir"
+mounted=0
+cleanup() {
+    if ((mounted)); then
+        /usr/bin/pluginkit -r "$mount_dir/GhostFile.app/Contents/Extensions/GhostFileFS.appex" \
+            >/dev/null 2>&1 || true
+        "$lsregister" -u "$mount_dir/GhostFile.app" >/dev/null 2>&1 || true
+        /usr/bin/hdiutil detach "$mount_dir" -quiet >/dev/null 2>&1 || true
+    fi
+    /bin/rm -rf "$work_dir"
+}
+trap cleanup EXIT INT TERM
+
+/usr/bin/hdiutil attach -readonly -nobrowse -mountpoint "$mount_dir" "$dmg_path" >/dev/null
+mounted=1
+/usr/bin/codesign --verify --deep --strict --verbose=2 "$mount_dir/GhostFile.app"
+/usr/sbin/spctl --assess --type execute --verbose=2 "$mount_dir/GhostFile.app"
+/usr/bin/pluginkit -r "$mount_dir/GhostFile.app/Contents/Extensions/GhostFileFS.appex" \
+    >/dev/null 2>&1 || true
+"$lsregister" -u "$mount_dir/GhostFile.app" >/dev/null 2>&1 || true
+/usr/bin/hdiutil detach "$mount_dir" -quiet
+mounted=0
+
+print "Notarized GhostFile DMG ready: $dmg_path"
+print "submission=$submission_id"
+print "result=$result_path"
diff --git a/scripts/package-ghostfile-dmg.sh b/scripts/package-ghostfile-dmg.sh
new file mode 100755
index 0000000..cb0caa8
--- /dev/null
+++ b/scripts/package-ghostfile-dmg.sh
@@ -0,0 +1,148 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+app_path=${1:-}
+dmg_path=${2:-}
+volume_name=${3:-GhostFile}
+readme_path=${GHOSTFILE_DMG_README:-}
+sign_identity=${GHOSTFILE_CODESIGN_ID:-}
+expected_version=${GHOSTFILE_EXPECTED_VERSION:-}
+expected_build=${GHOSTFILE_EXPECTED_BUILD:-}
+lsregister=/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister
+
+if [[ -z "$app_path" || -z "$dmg_path" ]]; then
+    print -u2 "usage: $0 APP_PATH DMG_PATH [VOLUME_NAME]"
+    exit 64
+fi
+if [[ ! -d "$app_path" || "${app_path:t}" != "GhostFile.app" ]]; then
+    print -u2 "GhostFile app not found: $app_path"
+    exit 66
+fi
+if [[ "${dmg_path:e}" != "dmg" ]]; then
+    print -u2 "DMG output must end in .dmg: $dmg_path"
+    exit 64
+fi
+if [[ -z "$sign_identity" ]]; then
+    sign_identity=$(/usr/bin/security find-identity -v -p codesigning \
+        | /usr/bin/sed -n 's/.*"\(Developer ID Application:[^"]*\)".*/\1/p' \
+        | /usr/bin/head -1)
+fi
+if [[ "$sign_identity" != "Developer ID Application:"* ]]; then
+    print -u2 "GhostFile DMGs require a Developer ID Application identity, got: $sign_identity"
+    exit 65
+fi
+if [[ -z "$sign_identity" ]]; then
+    print -u2 "No Developer ID Application signing identity was found."
+    exit 69
+fi
+
+app_path=${app_path:A}
+dmg_path=${dmg_path:A}
+mkdir -p "${dmg_path:h}"
+work_dir=$(/usr/bin/mktemp -d "${TMPDIR:-/tmp}/ghostfile-dmg.XXXXXX")
+stage_dir="$work_dir/stage"
+mount_dir="$work_dir/mount"
+temporary_dmg="$work_dir/GhostFile.dmg"
+mounted=0
+
+cleanup() {
+    if ((mounted)); then
+        /usr/bin/pluginkit -r "$mount_dir/GhostFile.app/Contents/Extensions/GhostFileFS.appex" \
+            >/dev/null 2>&1 || true
+        "$lsregister" -u "$mount_dir/GhostFile.app" >/dev/null 2>&1 || true
+        /usr/bin/hdiutil detach "$mount_dir" -quiet >/dev/null 2>&1 || true
+    fi
+    /bin/rm -rf "$work_dir"
+}
+trap cleanup EXIT INT TERM
+
+print "Verifying exported GhostFile.app…"
+/usr/bin/codesign --verify --deep --strict --verbose=2 "$app_path"
+signature_details=$(/usr/bin/codesign --display --verbose=4 "$app_path" 2>&1)
+if [[ "$signature_details" != *"Authority=Developer ID Application:"* ]]; then
+    print -u2 "GhostFile.app is not Developer ID signed. Export it with DeveloperIDExportOptions.plist first."
+    exit 65
+fi
+if [[ "$signature_details" != *"flags="*"runtime"* ]]; then
+    print -u2 "GhostFile.app does not have the hardened runtime enabled."
+    exit 65
+fi
+app_version=$(/usr/bin/plutil -extract CFBundleShortVersionString raw "$app_path/Contents/Info.plist")
+app_build=$(/usr/bin/plutil -extract CFBundleVersion raw "$app_path/Contents/Info.plist")
+extension_version=$(/usr/bin/plutil -extract CFBundleShortVersionString raw \
+    "$app_path/Contents/Extensions/GhostFileFS.appex/Contents/Info.plist")
+extension_build=$(/usr/bin/plutil -extract CFBundleVersion raw \
+    "$app_path/Contents/Extensions/GhostFileFS.appex/Contents/Info.plist")
+if [[ "$app_version" != "$extension_version" || "$app_build" != "$extension_build" ]]; then
+    print -u2 "App/extension version mismatch: app=$app_version ($app_build), extension=$extension_version ($extension_build)"
+    exit 65
+fi
+entitlements_path="$work_dir/GhostFileFS-entitlements.plist"
+# Current codesign emits a diagnostic representation for `--entitlements -`.
+# The legacy `:-` output selector still emits a plist that plutil can inspect.
+/usr/bin/codesign --display --entitlements :- \
+    "$app_path/Contents/Extensions/GhostFileFS.appex" \
+    >"$entitlements_path" 2>/dev/null
+fskit_entitlement=$(/usr/bin/plutil -extract 'com\.apple\.developer\.fskit\.fsmodule' raw \
+    "$entitlements_path" 2>/dev/null || true)
+if [[ "$fskit_entitlement" != "true" ]]; then
+    print -u2 "The exported GhostFileFS extension is missing its FSKit entitlement."
+    exit 65
+fi
+if [[ -n "$expected_version" && "$app_version" != "$expected_version" ]]; then
+    print -u2 "Expected version $expected_version, found $app_version"
+    exit 65
+fi
+if [[ -n "$expected_build" && "$app_build" != "$expected_build" ]]; then
+    print -u2 "Expected build $expected_build, found $app_build"
+    exit 65
+fi
+
+mkdir -p "$stage_dir" "$mount_dir"
+/usr/bin/ditto "$app_path" "$stage_dir/GhostFile.app"
+/bin/ln -s /Applications "$stage_dir/Applications"
+if [[ -n "$readme_path" ]]; then
+    if [[ ! -f "$readme_path" ]]; then
+        print -u2 "DMG README not found: $readme_path"
+        exit 66
+    fi
+    /usr/bin/ditto "$readme_path" "$stage_dir/README.txt"
+fi
+
+print "Creating compressed APFS disk image…"
+/usr/bin/hdiutil create \
+    -volname "$volume_name" \
+    -srcfolder "$stage_dir" \
+    -fs APFS \
+    -format UDZO \
+    -ov \
+    "$temporary_dmg" >/dev/null
+
+print "Signing disk image with $sign_identity…"
+/usr/bin/codesign --force --timestamp --sign "$sign_identity" "$temporary_dmg"
+/usr/bin/codesign --verify --verbose=2 "$temporary_dmg"
+/usr/bin/hdiutil verify "$temporary_dmg" >/dev/null
+
+print "Inspecting packaged app…"
+/usr/bin/hdiutil attach -readonly -nobrowse -mountpoint "$mount_dir" "$temporary_dmg" >/dev/null
+mounted=1
+[[ -d "$mount_dir/GhostFile.app" ]]
+[[ $(/usr/bin/readlink "$mount_dir/Applications") == "/Applications" ]]
+/usr/bin/codesign --verify --deep --strict --verbose=2 "$mount_dir/GhostFile.app"
+packaged_version=$(/usr/bin/plutil -extract CFBundleShortVersionString raw \
+    "$mount_dir/GhostFile.app/Contents/Info.plist")
+packaged_build=$(/usr/bin/plutil -extract CFBundleVersion raw \
+    "$mount_dir/GhostFile.app/Contents/Info.plist")
+[[ "$packaged_version" == "$app_version" && "$packaged_build" == "$app_build" ]]
+
+/usr/bin/pluginkit -r "$mount_dir/GhostFile.app/Contents/Extensions/GhostFileFS.appex" \
+    >/dev/null 2>&1 || true
+"$lsregister" -u "$mount_dir/GhostFile.app" >/dev/null 2>&1 || true
+/usr/bin/hdiutil detach "$mount_dir" -quiet
+mounted=0
+
+/bin/rm -f "$dmg_path"
+/bin/mv "$temporary_dmg" "$dmg_path"
+print "GhostFile DMG ready: $dmg_path"
+print "version=$app_version build=$app_build"
diff --git a/scripts/stress-ghostfile.sh b/scripts/stress-ghostfile.sh
new file mode 100755
index 0000000..a75cb9d
--- /dev/null
+++ b/scripts/stress-ghostfile.sh
@@ -0,0 +1,169 @@
+#!/bin/zsh
+
+set -u
+set -o pipefail
+
+mount_point=${1:-}
+source_root=${2:-}
+workers=${GHOSTFILE_STRESS_WORKERS:-8}
+iterations=${GHOSTFILE_STRESS_ITERATIONS:-25}
+mode=${GHOSTFILE_STRESS_MODE:-readonly}
+
+if [[ -z "$mount_point" || -z "$source_root" ]]; then
+    print -u2 "usage: $0 MOUNT_POINT SOURCE_ROOT"
+    exit 64
+fi
+
+large_file="$mount_point/stress/alpha/large-image.png"
+source_large="$source_root/stress/alpha/large-image.png"
+small_file="$mount_point/probe.txt"
+source_small="$source_root/probe.txt"
+space_file="$mount_point/stress/beta/space name.txt"
+unicode_file="$mount_point/stress/beta/unicode-π-世界.txt"
+symlink_file="$mount_point/stress/beta/link-to-large"
+broken_symlink="$mount_point/stress/beta/broken-link"
+write_probe="$mount_point/__ghostfile_write_probe__.$$"
+source_write_probe="$source_root/__ghostfile_write_probe__.$$"
+directory_probe="$mount_point/__ghostfile_directory_probe__.$$"
+source_directory_probe="$source_root/__ghostfile_directory_probe__.$$"
+renamed_probe="$directory_probe/renamed-probe"
+source_renamed_probe="$source_directory_probe/renamed-probe"
+
+failures=0
+checks=0
+
+check() {
+    local label=$1
+    shift
+    checks=$((checks + 1))
+    if "$@"; then
+        print "PASS $label"
+    else
+        print -u2 "FAIL $label"
+        failures=$((failures + 1))
+    fi
+}
+
+expect_failure() {
+    local label=$1
+    shift
+    checks=$((checks + 1))
+    if "$@" >/dev/null 2>&1; then
+        print -u2 "FAIL $label unexpectedly succeeded"
+        failures=$((failures + 1))
+    else
+        print "PASS $label rejected"
+    fi
+}
+
+worker() {
+    local worker_number=$1
+    local loop_number
+    local skip_blocks
+    for ((loop_number = 0; loop_number < iterations; loop_number++)); do
+        /usr/bin/stat -f '%z:%m:%i' "$large_file" >/dev/null || return 1
+        /usr/bin/shasum -a 256 "$large_file" >/dev/null || return 1
+        /bin/ls -la "$mount_point/stress/alpha" "$mount_point/stress/beta" >/dev/null || return 1
+        /usr/bin/readlink "$symlink_file" >/dev/null || return 1
+        /bin/cat "$small_file" "$space_file" "$unicode_file" >/dev/null || return 1
+        skip_blocks=$(((worker_number * 97 + loop_number * 31) % 400))
+        /bin/dd if="$large_file" of=/dev/null bs=4096 skip=$skip_blocks count=16 2>/dev/null || return 1
+    done
+}
+
+mount_is_fskit() {
+    local resolved_mount_point
+    local volume_mount_point
+    resolved_mount_point=$(cd "$mount_point" && /bin/pwd -P) || return 1
+    # `mount_point` may intentionally target a subdirectory of the volume so a
+    # self-test can stay inside a disposable fixture. Resolve its enclosing
+    # filesystem before checking the FSKit mount flags.
+    volume_mount_point=$(/bin/df -P "$resolved_mount_point" | /usr/bin/sed -n '2s/^.*%  *//p') || return 1
+    [[ -n "$volume_mount_point" ]] || return 1
+    /sbin/mount | /usr/bin/grep -F " on $volume_mount_point " | /usr/bin/grep -F "fskit" >/dev/null
+}
+
+print "GhostFile stress target: $mount_point"
+print "workers=$workers iterations=$iterations mode=$mode"
+
+if [[ "$mode" != "readonly" && "$mode" != "writable" ]]; then
+    print -u2 "GHOSTFILE_STRESS_MODE must be readonly or writable"
+    exit 64
+fi
+
+check "mount is FSKit" mount_is_fskit
+check "source and mounted large file match" /usr/bin/cmp -s "$source_large" "$large_file"
+check "source and mounted small file match" /usr/bin/cmp -s "$source_small" "$small_file"
+check "space-containing filename" /usr/bin/cmp -s "$source_small" "$space_file"
+check "UTF-8 filename" /usr/bin/cmp -s "$source_small" "$unicode_file"
+check "symlink target" test "$(/usr/bin/readlink "$symlink_file")" = "../../alpha/large-image.png"
+check "broken symlink remains a symlink" test -L "$broken_symlink"
+expect_failure "broken symlink content read" /bin/cat "$broken_symlink"
+
+for ((enumeration = 0; enumeration < 100; enumeration++)); do
+    /usr/bin/find "$mount_point" -maxdepth 5 -print >/dev/null || {
+        print -u2 "FAIL recursive enumeration at iteration $enumeration"
+        failures=$((failures + 1))
+        break
+    }
+done
+checks=$((checks + 1))
+if ((failures == 0)); then
+    print "PASS 100 recursive enumerations"
+fi
+
+typeset -a worker_pids
+for ((worker_number = 0; worker_number < workers; worker_number++)); do
+    worker "$worker_number" &
+    worker_pids+=("$!")
+done
+
+parallel_failure=0
+for worker_pid in $worker_pids; do
+    if ! wait "$worker_pid"; then
+        parallel_failure=1
+    fi
+done
+checks=$((checks + 1))
+if ((parallel_failure == 0)); then
+    print "PASS $((workers * iterations)) parallel operation batches"
+else
+    print -u2 "FAIL parallel operation batches"
+    failures=$((failures + 1))
+fi
+
+if [[ "$mode" == "readonly" ]]; then
+    expect_failure "file creation on read-only mount" /usr/bin/touch "$write_probe"
+    expect_failure "directory creation on read-only mount" /bin/mkdir "$directory_probe"
+    expect_failure "hard-link creation on read-only mount" /bin/ln "$small_file" "$write_probe"
+    expect_failure "metadata mutation on read-only mount" /bin/chmod u+x "$small_file"
+    check "failed mutations left no file" test ! -e "$write_probe"
+    check "failed mutations left no directory" test ! -e "$directory_probe"
+else
+    cleanup_writable_probes() {
+        /bin/rm -f "$renamed_probe" "$write_probe" >/dev/null 2>&1 || true
+        /bin/rmdir "$directory_probe" >/dev/null 2>&1 || true
+    }
+    trap cleanup_writable_probes EXIT
+
+    check "file creation through writable mount" /bin/sh -c \
+        'printf "ghostfile writable stress\n" > "$1"' sh "$write_probe"
+    check "created file is source-visible" /usr/bin/cmp -s "$write_probe" "$source_write_probe"
+    check "directory creation through writable mount" /bin/mkdir "$directory_probe"
+    check "created directory is source-visible" test -d "$source_directory_probe"
+    check "metadata mutation through writable mount" /bin/chmod 640 "$write_probe"
+    check "metadata mutation is source-visible" test "$(/usr/bin/stat -f %Lp "$source_write_probe")" = 640
+    check "rename through writable mount" /bin/mv "$write_probe" "$renamed_probe"
+    check "rename is source-visible" test -f "$source_renamed_probe"
+    check "truncate through writable mount" /usr/bin/truncate -s 7 "$renamed_probe"
+    check "truncate is source-visible" test "$(/usr/bin/stat -f %z "$source_renamed_probe")" = 7
+    expect_failure "unsupported hard-link creation" /bin/ln "$small_file" "$write_probe"
+    check "file deletion through writable mount" /bin/rm "$renamed_probe"
+    check "file deletion is source-visible" test ! -e "$source_renamed_probe"
+    check "directory deletion through writable mount" /bin/rmdir "$directory_probe"
+    check "directory deletion is source-visible" test ! -e "$source_directory_probe"
+    trap - EXIT
+fi
+
+print "checks=$checks failures=$failures"
+exit "$failures"
diff --git a/scripts/test-ghostbox-docker-compose.sh b/scripts/test-ghostbox-docker-compose.sh
new file mode 100755
index 0000000..7f33cd1
--- /dev/null
+++ b/scripts/test-ghostbox-docker-compose.sh
@@ -0,0 +1,174 @@
+#!/bin/sh
+
+set -eu
+
+ROOT=$(CDPATH='' cd -- "$(dirname "$0")/.." && pwd)
+COMPOSE=$ROOT/scripts/ghostbox-docker-compose
+
+/usr/bin/ruby -c "$COMPOSE" >/dev/null
+
+help=$($COMPOSE --help)
+case "$help" in
+    *'Usage: ghostbox-docker-compose'*'up [-d]'*'down'*'logs [-f]'*) ;;
+    *)
+        printf '%s\n' 'ghostbox-docker-compose help is incomplete' >&2
+        exit 1
+        ;;
+esac
+
+test_dir=$(mktemp -d "${TMPDIR:-/tmp}/ghostbox-docker-compose-test.XXXXXX")
+test_dir=$(/usr/bin/ruby -e 'puts File.expand_path(ARGV.fetch(0))' "$test_dir")
+compose_file=$test_dir/compose.yaml
+fake_docker=$test_dir/ghostbox-docker
+state_dir=$test_dir/state
+invocations=$test_dir/invocations
+
+cleanup() {
+    GHOSTBOX_DOCKER="$fake_docker" \
+        GHOSTBOX_DOCKER_COMPOSE_STATE="$state_dir" \
+        "$COMPOSE" -f "$compose_file" down --timeout 1 >/dev/null 2>&1 || true
+    rm -rf "$test_dir"
+}
+trap cleanup EXIT HUP INT TERM
+
+cat >"$test_dir/.env" <<'EOF'
+TAG=16
+EOF
+
+cat >"$compose_file" <<'EOF'
+name: sample
+services:
+  database:
+    image: postgres:${TAG:-latest}
+    environment:
+      POSTGRES_PASSWORD: secret
+    volumes:
+      - ./data:/var/lib/postgresql/data
+  web:
+    image: example/web:latest
+    depends_on:
+      - database
+    command: [serve, --port, "80"]
+    environment:
+      - MODE=test
+    ports:
+      - "8080:80"
+EOF
+
+cat >"$fake_docker" <<'EOF'
+#!/bin/sh
+set -eu
+
+record=
+for argument in "$@"; do
+    record=$record${record:+|}$argument
+done
+printf '%s\n' "$record" >>"$GHOSTBOX_DOCKER_COMPOSE_TEST_LOG"
+
+if [ "$1" = pull ]; then
+    printf 'Pulled %s\n' "$2"
+    exit 0
+fi
+
+name=
+previous=
+for argument in "$@"; do
+    if [ "$previous" = --name ]; then
+        name=$argument
+        break
+    fi
+    previous=$argument
+done
+printf '%s ready\n' "$name"
+trap 'exit 0' HUP INT TERM
+while :; do sleep 1; done
+EOF
+chmod 755 "$fake_docker"
+
+run_compose() {
+    GHOSTBOX_DOCKER="$fake_docker" \
+        GHOSTBOX_DOCKER_COMPOSE_STATE="$state_dir" \
+        GHOSTBOX_DOCKER_COMPOSE_TEST_LOG="$invocations" \
+        "$COMPOSE" -f "$compose_file" "$@"
+}
+
+resolved=$(run_compose config)
+case "$resolved" in
+    *'image: postgres:16'*) ;;
+    *)
+        printf '%s\n' 'Compose interpolation did not resolve .env values' >&2
+        exit 1
+        ;;
+esac
+if [ "$(run_compose config --services)" != "$(printf 'database\nweb')" ]; then
+    printf '%s\n' 'Compose config did not list services in declaration order' >&2
+    exit 1
+fi
+
+run_compose pull database >/dev/null
+if [ "$(cat "$invocations")" != 'pull|postgres:16' ]; then
+    printf '%s\n' 'Compose pull did not call ghostbox-docker correctly' >&2
+    exit 1
+fi
+: >"$invocations"
+
+run_compose up -d web >/dev/null
+attempt=0
+while [ "$attempt" -lt 50 ]; do
+    if [ -f "$state_dir/sample/services/database.json" ] && \
+        [ -f "$state_dir/sample/services/web.json" ] && \
+        [ "$(wc -l <"$invocations" | tr -d ' ')" -eq 2 ]; then
+        break
+    fi
+    attempt=$((attempt + 1))
+    sleep 0.1
+done
+if [ "$attempt" -eq 50 ]; then
+    printf '%s\n' 'Compose services did not start' >&2
+    exit 1
+fi
+
+expected_database="run|--rm|--name|sample-database-1|--env|POSTGRES_PASSWORD=secret|--volume|$test_dir/data:/var/lib/postgresql/data|postgres:16"
+expected_web='run|--rm|--name|sample-web-1|--env|MODE=test|--publish|127.0.0.1:8080:80/tcp|example/web:latest|serve|--port|80'
+actual=$(cat "$invocations")
+expected=$(printf '%s\n%s' "$expected_database" "$expected_web")
+if [ "$actual" != "$expected" ]; then
+    printf 'service dependency order or run arguments are incorrect:\n%s\n' "$actual" >&2
+    exit 1
+fi
+
+status=$(run_compose ps)
+case "$status" in *'database'*'running'*'postgres:16'*'web'*'example/web:latest'*) ;; *)
+    printf '%s\n' 'Compose ps did not report running services' >&2
+    exit 1
+esac
+
+attempt=0
+while [ "$attempt" -lt 20 ]; do
+    logs=$(run_compose logs web)
+    case "$logs" in *'web | sample-web-1 ready'*) break ;; esac
+    attempt=$((attempt + 1))
+    sleep 0.1
+done
+if [ "$attempt" -eq 20 ]; then
+    printf '%s\n' 'Compose logs did not return service output' >&2
+    exit 1
+fi
+
+database_pid=$(/usr/bin/ruby -rjson -e 'puts JSON.parse(File.read(ARGV.fetch(0))).fetch("pid")' \
+    "$state_dir/sample/services/database.json")
+web_pid=$(/usr/bin/ruby -rjson -e 'puts JSON.parse(File.read(ARGV.fetch(0))).fetch("pid")' \
+    "$state_dir/sample/services/web.json")
+run_compose down --timeout 2 >/dev/null
+if [ -e "$state_dir/sample/services" ]; then
+    printf '%s\n' 'Compose down did not remove service state' >&2
+    exit 1
+fi
+for pid in "$database_pid" "$web_pid"; do
+    if kill -0 "$pid" 2>/dev/null; then
+        printf 'Compose down left service runner %s alive\n' "$pid" >&2
+        exit 1
+    fi
+done
+
+printf '%s\n' 'ghostbox-docker-compose tests passed'
diff --git a/scripts/test-ghostbox-docker.sh b/scripts/test-ghostbox-docker.sh
new file mode 100644
index 0000000..ebf78fe
--- /dev/null
+++ b/scripts/test-ghostbox-docker.sh
@@ -0,0 +1,59 @@
+#!/bin/sh
+
+set -eu
+
+ROOT=$(CDPATH='' cd -- "$(dirname "$0")/.." && pwd)
+WRAPPER=$ROOT/scripts/ghostbox-docker
+
+sh -n "$WRAPPER"
+
+help=$($WRAPPER --help)
+case "$help" in
+    *'Usage: ghostbox-docker COMMAND'*) ;;
+    *)
+        printf '%s\n' 'ghostbox-docker help does not use the packaged command name' >&2
+        exit 1
+        ;;
+esac
+
+case "$help" in
+    *'compose'*)
+        printf '%s\n' 'ghostbox-docker help advertises unsupported Compose functionality' >&2
+        exit 1
+        ;;
+esac
+
+test_dir=$(mktemp -d "${TMPDIR:-/tmp}/ghostbox-docker-test.XXXXXX")
+trap 'rm -rf "$test_dir"' EXIT HUP INT TERM
+
+fake_ghostbox=$test_dir/ghostbox
+packaged_wrapper=$test_dir/ghostbox-docker
+log=$test_dir/invocations
+cp "$WRAPPER" "$packaged_wrapper"
+cat >"$fake_ghostbox" <<'EOF'
+#!/bin/sh
+printf '%s\n' "$*" >>"$GHOSTBOX_DOCKER_TEST_LOG"
+case "$1" in
+    cn:image-store:default) printf '%s\n' '@image-store/default' ;;
+    cn:image-store:pull) printf '%s\n' '@image/pulled' ;;
+    *) exit 99 ;;
+esac
+EOF
+chmod 755 "$fake_ghostbox"
+
+output=$(GHOSTBOX_DOCKER_TEST_LOG="$log" "$packaged_wrapper" pull alpine)
+if [ "$output" != 'Pulled docker.io/library/alpine:latest (@image/pulled)' ]; then
+    printf 'unexpected pull output: %s\n' "$output" >&2
+    exit 1
+fi
+
+expected=$(printf '%s\n%s' \
+    'cn:image-store:default' \
+    'cn:image-store:pull @image-store/default docker.io/library/alpine:latest --platform linux/arm64')
+actual=$(cat "$log")
+if [ "$actual" != "$expected" ]; then
+    printf 'unexpected Ghostbox invocations:\n%s\n' "$actual" >&2
+    exit 1
+fi
+
+printf '%s\n' 'ghostbox-docker tests passed'