Wire pid0 into ww run <image>, remove exec + TCP RPC#32
Merged
mikelsr merged 8 commits intofix/pid0-cleanupfrom Feb 20, 2026
Merged
Wire pid0 into ww run <image>, remove exec + TCP RPC#32mikelsr merged 8 commits intofix/pid0-cleanupfrom
mikelsr merged 8 commits intofix/pid0-cleanupfrom
Conversation
Replace the two-command daemon+client pattern (ww run / ww exec) with a single ww run <image> that boots pid0 directly from an image path. - Remove Exec subcommand and all supporting code (parse_tcp_multiaddr, pump_stdin_to_bytestream, pump_bytestream_to_stdout, etc.) - Delete src/rpc/server.rs (TCP accept loop on port 2021) - Remove dead ipfs/port fields from Cell and CellBuilder - Fix FHS path: <image>/main.wasm → <image>/bin/main.wasm - Remove legacy spawn_with_rpc_internal method - Wire CellBuilder with ChainLoader (IPFS + host FS) in CLI - Add doc comments to Cell, CellBuilder, and CLI help text
The old README documented flags (--volume, --ipfs, --preset) and workflows (two-terminal daemon+client) that no longer exist. Replace with current reality: single ww run <image> command, FHS image layout, architecture diagram, and build instructions for the staged guest pipeline.
Add boot/ to the FHS image layout spec. Each file is named with a base58btc-encoded libp2p peer ID and contains that peer's multiaddrs, one per line. The runtime will decode filenames via PeerId::from_str() and dial the listed addresses. Not yet wired into the runtime — specced in README, CellBuilder docs, and CLI help for now.
Each entry under svc/ is a nested image with its own FHS layout, spawned automatically at boot. The directory name is the service name. Services are images all the way down — they can carry their own boot/, etc/, and even nested svc/.
Captures the architectural insights from the ww-run-image work: capability-based security with no ambient authority, the runtime/pid0/children layer model, bidirectional capability flow (host -> guest -> network), the Membrane export pattern, and two-layer configuration (image config vs node config).
One config model: FHS. The image root pid0 sees is assembled from stacked layers (Stem base + positional overlays) via per-file union. Later layers override earlier; no deletes. Only the union must contain bin/main.wasm.
This was referenced Feb 16, 2026
Move generic membrane primitives (Epoch, EpochGuard, MembraneServer, SessionExtensionBuilder) from wetware/membrane into rs as a workspace crate. stem.capnp is now canonical in rs/capnp/. This consolidates the runtime workspace: membrane is consumed as a path dep by other rs crates, and as a git dep by stem/atom.
Add membrane crate to workspace
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This replaces the two-command daemon+client pattern (
ww run+ww exec) with a single command that boots pid0 directly from an image path:The daemon no longer opens a TCP port for external RPC clients. Instead, it loads the guest image itself and serves the Host capability over in-memory streams — same as
docker runloads and boots a container image directly.Image layout (FHS convention)
Images follow a simplified Filesystem Hierarchy Standard layout. This gives us a predictable, extensible structure whether the image lives on local disk or is fetched from IPFS:
Today only
bin/main.wasmis required. The other directories are reserved so we can later add support for:etc/— guest configuration (capability grants, resource limits, etc.)usr/lib/— shared WASM libraries that guests can link againstThis mirrors how OCI container images use FHS paths, making the layout immediately familiar. The
<image>argument can be either a local filesystem path or an IPFS path — theChainLoadertries IPFS resolution first, then falls back to the host filesystem.What changed
ww run <image>— now requires a positional<image>argument pointing to an FHS image directoryww execremoved — no more side-loading WASM over TCP; the daemon loads and runs pid0 itselfsrc/rpc/server.rs, port 2021) — Host RPC is now served exclusively over in-memory duplex streams between host and guestipfsandportfields, fixed entrypoint path from<image>/main.wasm→<image>/bin/main.wasm(FHS)spawn_with_rpc_internalremoved — only the data-streams code path remainsCell,CellBuilder, CLI help text, andsrc/rpc/mod.rsWhat stays the same
build_peer_rpc) — guests still bootstrap Cap'n Proto over data streamsExecutorImpl— pid0 can still spawn children viahost.executor().runBytes(wasm)peer.capnpschema — unchangedTest plan
cargo build— clean compile, zero warningscargo test --lib— 32/32 passmake guests images && cargo run -- run examples/images/pid0— e2e bootspawn_with_streams)