WEFT_OS/docs/architecture.md

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 <app_id> and <session_id> as arguments. Resolves weft-app://<app_id>/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, waits for READY, spawns weft-app-shell, manages the per-session IPC relay, and supervises child processes. Handles graceful termination and cgroup resource limits (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 <app_id> <session_id> [--preopen ...] [--ipc-socket ...]
        ├── weft-app-shell <app_id> <session_id>
        └── weft-file-portal <socket> [--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/<id>/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

<app_id>/
  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
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)