# WEFT OS Architecture ## Overview WEFT OS is a Wayland compositor and application runtime where every app is a WebAssembly component served via a Servo-rendered WebView. The system has no ambient authority: capabilities are declared in `wapp.toml`, verified at install time, and enforced at runtime. ## Components ### weft-compositor Smithay-based Wayland compositor. Implements the `zweft-shell-unstable-v1` protocol extension, which allows shell clients (servo-shell, app-shell) to register their surfaces as typed shell slots. Supports DRM/KMS and winit (software/dev) backends. ### weft-servo-shell System UI host. Renders one WebView pointing at `system-ui.html` using the embedded Servo engine (feature-gated behind `servo-embed`). Connects to the compositor as window type `panel`. Dispatches the `zweft_shell_manager_v1` event queue each frame. Forwards navigation gestures received from the compositor to `weft-appd` over WebSocket. ### weft-app-shell Per-application Servo host. Spawned by `weft-appd` after the Wasm runtime signals READY. Takes `` and `` as arguments. Resolves `weft-app:///ui/index.html` and injects the `weftIpc` WebSocket bridge into the page. Registers with the compositor as window type `application`. Exits when the appd session ends. ### weft-appd Session supervisor. Listens on a Unix socket (MessagePack protocol) and a WebSocket port (JSON). For each session: spawns `weft-runtime` and waits for its READY, spawns `weft-app-shell` (`WEFT_APP_SHELL_BIN` is required) and waits for its READY, and only then reports the session running (`APP_READY`). A child reports readiness by printing `READY ` on stdout, where the token is a random per-session value appd passes in `WEFT_READY_TOKEN`; Wasm guests and pages share those stdout streams but cannot read the token, so their output cannot fake readiness. Each wait times out after 30 seconds. If either child fails to start, fails to become ready or exits, or the session is terminated, the whole session is stopped: both children, the file portal, the compositor association and any image mount are released. Manages the per-session IPC relay and applies cgroup resource limits to the runtime via systemd-run when available. ### weft-runtime WASI Preview 2 + Component Model execution host (Wasmtime 30). Loads `app.wasm` from the installed package directory. Provides host imports for `weft:app/notify`, `weft:app/ipc`, `weft:app/fetch`, `weft:app/notifications`, and `weft:app/clipboard`. Preopens filesystem paths according to capabilities declared in `wapp.toml`. ### weft-pack Package management CLI. Subcommands: `check` (validate wapp.toml + wasm module), `sign` (Ed25519 signature), `verify` (verify signature), `generate-key`, `install`, `uninstall`, `list`, `build-image` (EROFS dm-verity), `info`. ### weft-file-portal Per-session file proxy. Runs as a separate process with a path allowlist derived from preopened directories. Accepts JSON-lines requests over a Unix socket. Blocks path traversal. Used by apps that require file access without direct WASI preopens. ### weft-mount-helper Setuid helper binary. Calls `veritysetup` and mounts EROFS images for dm-verity-protected packages. ## Process Topology ``` systemd ├── weft-compositor (user) ├── weft-servo-shell (user, after compositor) └── weft-appd (user, after compositor + servo-shell) └── per-session: ├── weft-runtime [--preopen ...] [--ipc-socket ...] ├── weft-app-shell └── weft-file-portal [--allow ...] ``` ## IPC | Channel | Protocol | Purpose | |---|---|---| | weft-appd Unix socket | MessagePack | appd ↔ other system daemons | | weft-appd WebSocket (:7410) | JSON | system-ui.html ↔ appd (gesture events, app lifecycle) | | per-session IPC socket | newline-delimited JSON | weft-runtime ↔ weft-app-shell (weft:app/ipc) | | weft-file-portal socket | JSON-lines | weft-runtime ↔ file proxy | ## Capability Enforcement Capabilities are declared in `wapp.toml` under `[package] capabilities`. `weft-pack check` validates that only known capabilities are listed. At runtime, `weft-appd` reads capabilities and maps them to WASI preopened directories and host function availability: | Capability | Effect | |---|---| | `fs:rw:app-data` | Preopen `~/.local/share/weft/apps//data` as `/data` | | `fs:read:app-data` | Same, read-only | | `fs:rw:xdg-documents` | Preopen `~/Documents` as `/xdg/documents` | | `net:fetch` | Enables `weft:app/fetch` host function | | `sys:notifications` | Enables `weft:app/notifications` host function | ## Package Format ``` / wapp.toml — manifest (id, name, version, capabilities, runtime.module, ui.entry) app.wasm — WASI Component Model binary ui/ index.html — entry point served by weft-app-shell signature.sig — Ed25519 signature over SHA-256 of (wapp.toml + app.wasm) ``` Package store roots (in priority order): 1. `$WEFT_APP_STORE` (if set) 2. `~/.local/share/weft/apps/` 3. `/usr/share/weft/apps/` ## Environment Variables | Variable | Default | Description | |---|---|---| | `WEFT_RUNTIME_BIN` | — | Path to `weft-runtime` binary | | `WEFT_APP_SHELL_BIN` | — | Path to `weft-app-shell` binary; required to launch apps | | `WEFT_READY_TOKEN` | set by appd | Per-session readiness token passed to `weft-runtime` and `weft-app-shell` | | `WEFT_FILE_PORTAL_BIN` | — | Path to `weft-file-portal` binary | | `WEFT_MOUNT_HELPER` | — | Path to `weft-mount-helper` binary | | `WEFT_APP_STORE` | — | Override package store root | | `WEFT_APPD_SOCKET` | — | Unix socket path for weft-appd | | `WEFT_APPD_WS_PORT` | `7410` | WebSocket port for weft-appd | | `WEFT_EGL_RENDERING` | — | Set to `1` to use EGL rendering in Servo shell | | `WEFT_DISABLE_CGROUP` | — | Set to disable systemd-run cgroup wrapping | | `WEFT_FILE_PORTAL_SOCKET` | — | Path forwarded to app runtime for file portal | | `XDG_RUNTIME_DIR` | — | Standard XDG runtime dir (sockets written here) |