WeftOS Overview
The WeftOS kernel: process management, IPC, governance, cryptographic audit trails, mesh networking, and the node daemon that hosts them.
WeftOS is the kernel abstraction layer for clawft. It sits between the CLI/API surface (clawft-weave, clawft-cli) and the core agent runtime (clawft-core), providing OS-like abstractions for agent orchestration: process management, inter-process communication, governance, cryptographic audit trails, and resource namespacing.
What is WeftOS
WeftOS treats AI agents as first-class OS processes. Each agent receives a PID, a set of capabilities, an IPC inbox, and resource limits -- all managed by a central kernel that boots, supervises, and shuts down the agent fleet.
The kernel is implemented in the clawft-kernel crate and was built in phases (K0 through K6) that added capabilities from basic boot and process management through mesh networking. Since 0.8.x the weaver daemon runs one kernel per project under a per-user daemon, and joins machines into a mesh (ADR-103). Cogs, the cogbus data-plane broker, workload placement and the tailnet router sit on top of the kernel; see the release notes for when each arrived.
Platform Identity
WeftOS is an agent operating system kernel -- a Rust-native runtime that manages AI agents as first-class processes under constitutional governance. Every action is auditable via cryptographic hash chains, every capability is checked at the gate, and every decision is logged to a tamper-evident ExoChain.
Design Principles
Composition, not rewrite. The kernel wraps existing clawft primitives (MessageBus, SandboxEnforcer, AgentLoop, Platform trait) into a unified coordination layer. No existing code is forked or duplicated.
Incremental adoption. The kernel is opt-in. Existing weft commands work without kernel activation. Feature flags gate heavy dependencies (Wasmtime, Docker, mesh networking) so the default binary stays lean.
Kernel wraps AppContext. The central Kernel<P: Platform> struct wraps AppContext<P> in a boot sequence with a state machine (Booting -> Running -> ShuttingDown -> Halted), adding process tracking, service lifecycle, IPC, and health monitoring on top.
Chain-anchored governance. Every significant state change is logged to an append-only hash chain (ExoChain) using SHAKE-256, creating a tamper-evident audit trail. Governance rules are anchored to the chain at genesis and cannot be modified.
Cognitive platform. WeftOS is not merely an agent orchestrator -- it is a cognitive platform where every kernel instance is a node in a distributed nervous system. From embedded devices to GPU servers, all run the same Kernel<P: Platform>, differentiated only by boot-time calibration and Platform trait implementation.
Feature Flags and Build Configurations
clawft-kernel enables native, exochain, cluster, tilezero, ecc, mesh, quic and workload-runtime by default (crates/clawft-kernel/Cargo.toml, default). The weftos crate is thinner: its default is native only, and the other flags are opt-in.
| Feature | What It Enables |
|---|---|
native | Tokio runtime, native I/O |
exochain | Chain, TreeManager, Gate, RVF persistence |
tilezero | TileZeroGate (three-way gate with receipts) |
cluster | ClusterService with raft consensus |
mesh | Mesh networking (quic adds the QUIC transport) |
ecc | ECC cognitive substrate |
os-patterns | Self-healing, dead-letter queue, metrics (requires exochain) |
wasm-sandbox | Wasmtime-based tool runner |
containers | Container lifecycle management |
The feature flags guide has the full list and the per-crate defaults.
Phase Roadmap (K0-K6)
| Phase | Name | Status | Scope |
|---|---|---|---|
| K0 | Kernel Foundation | Complete | Boot state machine, event logging, config, errors |
| K1 | Process and Supervision | Complete | PID allocation, process table, agent supervisor, RBAC |
| K2 | IPC and Communication | Complete | Message envelopes, A2A routing, pub/sub, cron, health, services |
| K2b | Hardening | Complete | Chain-logged lifecycle, signal handling, DashMap safety |
| ExoChain | Cryptographic Audit | Complete | Hash chain, resource tree, gate backends |
| K3 | WASM Sandbox | Complete | Wasmtime runner, fuel metering, sandbox config |
| K3c | ECC Cognitive Substrate | Complete | Causal DAG, cognitive tick, HNSW, impulse queue |
| K4 | Containers | Complete | Container lifecycle, config validation, health propagation |
| K5 | App Framework | Complete | Manifest parsing, app lifecycle, agent spawning |
| K6 | Mesh Networking | Shipped | Transport traits, discovery, cross-node IPC, replication; QUIC transport since 0.8.0 |
Architecture Diagram
+---------------------------------------------------------------+
| CLI / API Surface |
| clawft-cli (weft) clawft-weave (weaver) |
+-------------------------------+-------------------------------+
|
v
+---------------------------------------------------------------+
| clawft-kernel (WeftOS) |
| |
| +----------+ +-----------+ +--------+ +-----------+ |
| | K0: Boot | | K1: Proc | | K2:IPC | | ExoChain | |
| | State | | Table + | | A2A | | Chain + | |
| | Machine | | Supervisor| | Topics | | Tree + | |
| | | | RBAC | | Cron | | Gate | |
| +----------+ +-----------+ +--------+ +-----------+ |
| |
| +----------+ +-----------+ +--------+ +-----------+ |
| | K3: WASM | | K4: | | K5:App | | K6: Mesh | |
| | Sandbox | | Container | | Framwk | | Network | |
| | Runner | | Manager | | Manifst| | Discovery | |
| +----------+ +-----------+ +--------+ +-----------+ |
| |
| +---------------------------------------------------+ |
| | K3c: ECC Cognitive Substrate | |
| | CausalGraph | CognitiveTick | HNSW | CrossRef | |
| +---------------------------------------------------+ |
+-------------------------------+-------------------------------+
|
v
+---------------------------------------------------------------+
| clawft-core |
| Agent loop, MessageBus, Pipeline, Sessions, Tools |
+-------------------------------+-------------------------------+
|
v
+---------------------------------------------------------------+
| clawft-platform clawft-types clawft-llm |
| (native/browser) (shared types) (LLM providers) |
+---------------------------------------------------------------+Crate Dependencies
clawft-cli weft binary (user-facing CLI)
clawft-weave weaver binary (operator CLI + daemon)
| |
v v
clawft-kernel OS abstractions (WeftOS)
|
v
clawft-core Agent loop, message bus, pipeline, sessions
|
v
clawft-platform Platform traits (native / browser)
clawft-types Shared domain types and config
clawft-llm LLM provider abstractionRunning Tests
scripts/build.sh test # workspace tests
scripts/build.sh check # fast compile check
scripts/build.sh gate # full phase gate, run before committingDocumentation Map
- Architecture -- 5-layer kernel architecture deep dive
- Kernel Phases -- detailed K0-K6 phase breakdown
- Boot Sequence -- kernel lifecycle and state machine
- Process Table -- PID allocation and process management
- IPC -- inter-process communication and A2A messaging
- Capabilities -- RBAC and capability-based access control
- ExoChain -- cryptographic audit trail
- Governance -- three-branch constitutional governance
- WASM Sandbox -- tool sandboxing with Wasmtime
- Containers -- container integration
- App Framework -- application manifests and lifecycle
- Mesh Networking -- multi-node networking
- Discovery -- peer discovery protocols
- Clustering -- cluster management and distributed state
- Security -- security model overview
- ECC -- Ephemeral Causal Cognition cognitive substrate
- Decisions -- symposium design decisions
- Kernel Guide -- developer guide