clawft

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.

FeatureWhat It Enables
nativeTokio runtime, native I/O
exochainChain, TreeManager, Gate, RVF persistence
tilezeroTileZeroGate (three-way gate with receipts)
clusterClusterService with raft consensus
meshMesh networking (quic adds the QUIC transport)
eccECC cognitive substrate
os-patternsSelf-healing, dead-letter queue, metrics (requires exochain)
wasm-sandboxWasmtime-based tool runner
containersContainer lifecycle management

The feature flags guide has the full list and the per-crate defaults.

Phase Roadmap (K0-K6)

PhaseNameStatusScope
K0Kernel FoundationCompleteBoot state machine, event logging, config, errors
K1Process and SupervisionCompletePID allocation, process table, agent supervisor, RBAC
K2IPC and CommunicationCompleteMessage envelopes, A2A routing, pub/sub, cron, health, services
K2bHardeningCompleteChain-logged lifecycle, signal handling, DashMap safety
ExoChainCryptographic AuditCompleteHash chain, resource tree, gate backends
K3WASM SandboxCompleteWasmtime runner, fuel metering, sandbox config
K3cECC Cognitive SubstrateCompleteCausal DAG, cognitive tick, HNSW, impulse queue
K4ContainersCompleteContainer lifecycle, config validation, health propagation
K5App FrameworkCompleteManifest parsing, app lifecycle, agent spawning
K6Mesh NetworkingShippedTransport 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 abstraction

Running Tests

scripts/build.sh test    # workspace tests
scripts/build.sh check   # fast compile check
scripts/build.sh gate    # full phase gate, run before committing

Documentation Map

On this page