Skip to content
wetwarePublic

Latest commit

 

History

1,513 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wetware

CI

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.

Run an authenticated release

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.

Features

  • Explicit child Membranes. Each ordinary cell starts with one parent-selected Membrane and no ambient node authority. Its graft() exposes only the typed fields and application-defined extras that 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-wasip3 components. 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 Terminal that authenticates a login identity and issues only the method authority selected for that identity.

Quickstart

Install

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.

Run a node

ww run                    # boot the installed FHS
ww image check            # validate static PID0 compatibility
ww run .                  # explicitly overlay the current directory

Build the example cells

make examples

The 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.

How it works

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.

Cell modes

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

Standard ports

Port Service
2025 libp2p swarm
2026 Local HTTP admin (/healthz, metrics, peer ID, listen addrs); disable with --with-http-admin off
2080 HTTP/WAGI

Publishing a cell

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 IPFS

The Rust PID0 does not automatically compose arbitrary guest components from an image. A published guest requires an application-specific composition path.

Learn more

Releases

Packages

Used by

Contributors

Languages