MDK - Marmot Development Kit

Rust implementation workspace for the Marmot protocol.

This repository contains the Marmot engine and production-shaped integration layers:

• OpenMLS-backed CGKA engine and conformance simulator;
• SQLCipher-backed account/device storage;
• account, app-runtime, CLI, daemon, and TUI surfaces;
• Nostr transport adapter and peeler;
• QUIC agent stream preview transport and broker;
• agent control protocol, stream composition, and wn-agent connector;
• UniFFI bindings used by app runtimes;
• Tamarin models and architecture notes that map implementation behavior back to the protocol.

The canonical Marmot protocol specification lives in marmot-protocol/marmot. This repository keeps implementation architecture, conformance, diagnostics, and release material.

Start Here

If you want to use White Noise with an existing agent runtime, start with the White Noise + Agents quickstart. It covers Hermes, OpenClaw, Claude Code, Codex, OpenCode, and Pi from install through the first encrypted chat.

If you are developing Marmot itself, read these files in order:

1. crates/cgka-engine/README.md - what the engine owns and what it leaves out.
2. crates/cgka-conformance-simulator/README.md - how scenarios, vectors, generated chaos, and property tests work.
3. docs/marmot-architecture/index.md - implementation architecture map.
4. formal/tamarin/README.md - how the formal model maps back to Rust tests.

Client integrations start with the binding integration guide, complete method reference, and C ABI guide. Version-specific upgrade steps live in the integration guides. The latest is 0.10.4 → 0.11.0; read every intervening guide when skipping releases. Release checklists and the companion-document requirement live in release.md.

Repository Map

Primary implementation areas:

• crates/cgka-engine - OpenMLS-backed CGKA engine and local group state machine.
• crates/cgka-conformance-simulator - multi-client scenarios, generated chaos, reports, property tests, and vectors.
• crates/traits - shared traits and cross-boundary types.
• crates/fs-private - restrictive-by-construction local file, directory, and socket creation helpers.
• crates/storage-sqlite - SQLCipher-backed persistence for session, engine integration, tests, and simulator runs.
• crates/transport-nostr-peeler - Nostr event to engine-message boundary and MLS envelope peeling.
• crates/transport-nostr-adapter - Nostr transport adapter core behind an injectable relay-client boundary.
• crates/transport-quic-stream - raw QUIC transport binding for transient agent text stream previews.
• crates/transport-quic-broker - memory-only QUIC pub/sub broker for forwarding live preview records.
• crates/cgka-session - account-device session wrapper over Engine<SqliteAccountStorage>.
• crates/marmot-account - app-core home, account records, key storage, and transport adapter orchestration.
• crates/marmot-app - multi-account app runtime bridge used by the CLI, daemon, TUI, and bindings.
• crates/marmot-uniffi - UniFFI bindings over the app runtime.
• crates/marmot-markdown - CommonMark and nostr display parser for app messages.
• crates/marmot-wallet - Cashu wallet storage: SQLCipher driver under CDK's SQL wallet database.
• crates/marmot-forensics - append-only JSONL forensic audit schema and recorder traits.
• crates/agent-control - marmot.agent-control.v2 control-protocol DTOs and newline-delimited JSON framing.
• crates/agent-stream-compose - reusable live-preview stream composition over the QUIC broker publisher.
• crates/agent-connector - local wn-agent connector daemon bridging agent control and stream composition.
• crates/cli - CLI app surface plus wnd daemon and wn tui.
• integrations/hermes/marmot - Hermes gateway plugin for the local wn-agent control socket.
• integrations/openclaw/marmot - OpenClaw channel plugin for the local wn-agent control socket.
• integrations/claude/marmot - Claude Code terminal harness for the local wn-agent control socket.
• integrations/codex/marmot - Codex terminal harness for the local wn-agent control socket.
• integrations/opencode/marmot - OpenCode terminal harness for the local wn-agent control socket.
• integrations/pi/marmot - Pi terminal harness for the local wn-agent control socket.
• integrations/terminal-harness - shared hardened runtime for terminal-harness connectors.

Reference and model support:

• docs/marmot-architecture - architecture notes, engine contracts, and current-state docs.
• docs/quic-broker-deployment.md - local Compose and GHCR/VM deployment notes for marmot-quic-broker.
• formal/tamarin - Tamarin proofs for convergence selector, lifecycle boundaries, delivery-order behavior, and proof-to-test mapping.

Test Commands

Use the smallest command that covers your change.

# Engine boundary tests.
cargo test -p cgka-engine

# Simulator scenarios, vectors, and default property-test counts.
cargo test -p cgka-conformance-simulator

# Wider simulator property-test run.
cargo test -p cgka-conformance-simulator --features conformance-slow

# Fast pre-push gate (formatting, naming, compile checks, clippy; skips tests).
just fast-ci

# Full workspace checks.
just fmt-check
just check
just clippy
just test

MDK also maintains a compile-only browser WASM boundary for cgka-traits, cgka-engine, and transport-nostr-peeler. Install the Rust target, ensure CC_wasm32_unknown_unknown names a Clang binary with a wasm32 backend when the system Clang lacks one, and run:

rustup target add wasm32-unknown-unknown
just wasm-check

This gate does not run browser acceptance tests and does not claim browser support for SQLCipher storage, the app runtime, bindings, CLI, or daemon.

The repository's .cargo/config.toml supplies a 4 MiB RUST_MIN_STACK for Cargo-launched tests and debug binaries. Unoptimized OpenMLS group construction and tree deserialization can exceed Rust's platform-default 2 MiB spawned-thread stack through the composed app runtime. If you launch a built debug binary directly instead of through Cargo, export the same RUST_MIN_STACK=4194304 value first.

The CLI real-relay E2E tests use local Nostr relays. Start the repo-owned relay stack before running them:

just relay-up
just e2e-test
just relay-down

Formal model checks:

just tamarin