Wetware lets you safely run code you didn't write, don't trust, and cannot see: third-party MCP servers, code your LLM produced at runtime, tools other agents handed you across the swarm. It's a decentralized operating system for multi-tool agent swarms.
Cells are WASM processes with no ambient node-control authority. They receive
a fixed WASI substrate: stdio, arguments/environment, clocks, randomness, an
image-root filesystem, and private writable /tmp. Known-CID reads additionally
depend on the execution context's root or cache wiring. See the
WASI host functions.
Node-control operations require explicitly granted, typed Cap'n Proto
capabilities. Those references can be attenuated to a method allowlist; the
restriction travels with the reference across local and libp2p RPC boundaries
and recursively confines capabilities returned through it. Argument- and
resource-level filtering remain separate, application-level designs. Least
privilege is enforced by the runtime, not delegated to a prompt or to the
model running inside the cell.
Production signing, IPFS publication, DNSLink and /install activation remain
held. The public /install endpoint is in maintenance; it is not a working
bootstrap path. The commands below use scripts/install.sh from a reviewed
checkout and require an available signed release CID, independently provisioned
public trust, and running Kubo. See installation.
sh scripts/install.sh --release "$RELEASE_CID"
# Start in the foreground; query /status from another terminal.
ww run --http-listen 127.0.0.1:2080
# In another terminal: curl http://localhost:2080/status{
"status": "ok",
"version": "0.1.0",
"peer_id": "12D3KooWRLf8DAFsNfbv3s2DjRMbUuPc8AYdcBfokZbz6kJ2aUss",
"listen_addrs": ["/ip4/127.0.0.1/tcp/2025", "/ip6/::1/tcp/2025", ...],
"peer_count": 216
}The status request reaches a WebAssembly cell running inside the Host. The
default Rust kernel installs this composition directly. The cell receives a
narrow Membrane containing only peerId and Stat.
- Explicit child Membranes. Each ordinary cell starts with one parent-selected
Membraneand no ambient node authority. Itsgraft()exposes only the typed fields and application-definedextrasthat the parent chose. Method restrictions remain attached to each capability reference and to capabilities reached through it. - Composable membranes. Tool A calls tool B which calls tool C. Each process boundary carries one explicit
Membrane. See examples/oracle/ for the runnable version. - Content-addressed code. Cells are identified by CID. The binary that ran is the binary you pinned; no swap-under-the-rug between generation and execution.
- WASM cell scale. ~10ms spawn, KB-scale binaries, language-agnostic via native
wasm32-wasip3components. Per-call sandboxing is only feasible because cells are cheap; microVM cold-start is too slow for that. - P2P capability sharing. A cell can export a typed capability to a peer over libp2p. Service names locate a stream; they do not authorize its caller. A deployer can publish a
Terminalthat authenticates a login identity and issues only the method authority selected for that identity.
Use a reviewed checkout and the signed-release prerequisites above. Before
running the command, set RELEASE_CID to the selected signed release and provision
the independent release keyring. Production activation remains held; the command
does not supply a release or trust anchor.
sh scripts/install.sh --release "$RELEASE_CID"The installer authenticates and installs the Host, baseline FHS, and identity.
The shell installer requires an explicit release CID.
For existing installations, ww upgrade supports authenticated IPNS selection
with an independently configured release identity and public keyring.
Installation does not register a daemon or configure name publication. Register
separately with ww daemon install, then start it through the native service manager.
Ordinary startup requires no native-upgrade admission. Automatic native replacement
supports managed GNU ARM64 Linux/systemd with a fixed loopback /readyz endpoint.
Qualification and production activation remain separate gates. See
native platform limits.
ww image update changes only the baseline and never restarts the Host.
ww uninstall preserves user state. UpgradeCoordinator authenticates, stages,
replaces, and recovers native software under the installation mutation lock.
See installation and recovery for ownership, migration,
service activation, and outstanding upgrade integration gates.
Or build from source:
ww doctor # check your dev environment
rustup toolchain install nightly-2026-08-30 --component rust-src
make # build everything (host + std + examples)Guest builds use the pinned native P3 toolchain. ww doctor reports missing
WASI SDK, component-ld, or wasm-tools dependencies. Current ww run boot
requires Kubo, including installed and local-image
boot. Kubo provides the image/content backend; Composer merges image
directories in-process, and provider routing uses Wetware's own swarm. Guest
compilation and pure/unit tests do not require a running Kubo daemon. See
deployment startup requirements.
Repository builds use committed Cargo lockfiles. See the lockfile policy and dependency-update workflow.
Commit source and small intentional fixtures, not compiled release artifacts.
python3 scripts/check_repository_artifacts.py checks committed Git bytes for
native binary headers, blobs over 1 MiB, and the retired historical fixture path.
Small archives are not inspected internally. Store build outputs outside Git.
ww run # boot the installed FHS
ww image check # validate static PID0 compatibility
ww run . # explicitly overlay the current directorymake examplesThe repository keeps the Rust example crates as buildable guest-component
references. The Rust PID0 installs only the default /status composition, so
the repository does not currently ship a generic runtime composition for these
examples.
Mounts use source[:/guest/target], for example ww run ./config:/etc/myapp.
Local sources freeze once at startup; Stem updates reuse those exact snapshots.
Use explicit local paths (./app, /path, or ~/app). Bare ww run does not
mount CWD. It uses the installed FHS at ~/.ww/fhs; --fhs-root selects another
baseline directory.
ww run starts a libp2p node on port 2025 and merges any image layers
into a virtual FHS filesystem. Precedence, from lowest to highest, is installed
baseline, authoritative Stem head, frozen namespace images, then frozen CLI
operations. The Host selects PID0 from /boot/kernel.wasm in that exact effective
root for every epoch. Invalid selected kernels fail without an alternate-kernel
fallback.
ww build places the application component at
bin/<project-directory>.wasm. ww push imports that image tree and reports its
IPFS directory-root CID. The Host does not use the application component as PID0
input. See the image lifecycle.
PID0 and ordinary children both receive a Membrane. PID0 receives a broad
root implementation. Each child receives the exact narrow implementation that
its parent passes to Executor.spawn(). Repeated graft() calls cannot add
authority because each server returns only its held references. After an epoch
transition, delegated host capabilities stay stale until an authorized ancestor
explicitly re-delegates fresh references or respawns the child.
doc/architecture.md is the canonical reference; doc/capabilities.md is the capability surface.
WASM processes ("cells") have no ambient node-control authority and receive
the WASI substrate described above. Async RPC Cells use the granted P3
transport. WW_CELL_MODE identifies separate application
plumbing:
| Mode | stdio carries | Host wiring |
|---|---|---|
vat |
application-defined | Serves an existing guest capability |
raw |
raw libp2p stream bytes | Long-lived byte/session listener |
http |
CGI env vars + stdin/stdout | Stateless WAGI request adapter |
| (absent) | process input/output | Process-local P3 RPC; PID0 receives a Membrane |
| Port | Service |
|---|---|
| 2025 | libp2p swarm |
| 2026 | Local HTTP admin (/healthz, metrics, peer ID, listen addrs); disable with --with-http-admin off |
| 2080 | HTTP/WAGI |
cd examples # from the repository root
ww init myapp # scaffold a new cell project
cd myapp && ww build # compile to WASM
ww push . --ipfs-url http://localhost:5001 # publish to IPFSThe Rust PID0 does not automatically compose arbitrary guest components from an image. A published guest requires an application-specific composition path.
- Architecture map: interactive map of the current host, authority, cell, and network paths; see the maintenance guide for updates
- Positioning: the JTBD-anchored category claim and audience
- Architecture: design principles and capability flow
- Capabilities: the capability model and Cap'n Proto schemas
- CLI reference: full command-line usage
- Release rehearsal: disposable genuine-artifact and consumer qualification
- Image layout: FHS convention, mounts, on-chain coordination
- Provider routing: independent discovery and host-PeerID announcement capabilities
- Keys & identity: Ed25519 identity management
- RPC transport: transport plumbing and scheduling model
- Guest runtime: async runtime for WASM guests
- Runtime topology: host service threads and filesystem lifecycle
- Local observability: reproduce a Cell incident and follow metrics, logs, and traces in Grafana
- Replay protection: epoch-bound authentication
- Examples: echo, counter, oracle, chess, discovery, and snap-hello-rs