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.
curl -sSL https://wetware.run/install | sh
# Run the platform service activation command printed by the installer.
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 second command hit a WebAssembly cell running inside the daemon. 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.
curl -sSL https://wetware.run/install | shThe installer verifies and installs the Host plus fhs/boot/kernel.wasm and
fhs/bin/status.wasm. It creates identity only when absent and prints the
platform service activation command. Installation does not start the service.
See installation and recovery for manual activation,
managed-file ownership, and incomplete-install recovery. ww perform upgrade
is disabled; use the current installer for Host replacement.
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.
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
- 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
- Replay protection: epoch-bound authentication
- Examples: echo, counter, oracle, chess, discovery, and snap-hello-rs