Marmot
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
  • Start here

    • Documentation
  • Integration guides

    • Native apps · MarmotKit
    • Rust application runtime
    • C and native hosts
    • Bots and agents
    • Terminal and scripts
    • TypeScript quickstart
    • TypeScript storage
    • TypeScript networking
  • Reference

    • MarmotKit distribution
    • MarmotKit API
    • C API
    • Architecture
    • Upgrade guide

Documentation

MDK 0.17.0View source on GitHub

This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.

MDK — Marmot Development Kit

MDK is the Rust implementation of Marmot, an end-to-end encrypted group messaging protocol built on MLS (RFC 9420) with Nostr identity. It powers White Noise: the protocol engine, encrypted storage, Nostr transport, the app runtime behind the mobile bindings, the wn command-line app, and the wn-agent connector that brings AI agents into encrypted chats.

The protocol specification lives in marmot-protocol/marmot. This repository holds the implementation, its architecture notes, conformance tests, formal models, and release tooling.

Contents

  • Find your way
  • Chat with an AI agent
  • The wn command-line app
  • Build an app on MDK
  • How MDK is built
  • How convergence works
  • Crate map
  • Development
  • Releases
  • License

Find your way

I want to… Start here
Talk to Hermes, OpenClaw, Claude Code, Codex, OpenCode, Pi, or Goose from White Noise White Noise + Agents quickstart
Write your own bot or client against wn-agent Build your own client
Use White Noise from a terminal (CLI, daemon, TUI) wn guide
Integrate MDK into an iOS, macOS, or Android app MarmotKit integration guide
Integrate from C or another raw-FFI host C ABI guide
Upgrade an app to a new MDK release Version upgrade guides
Understand the Marmot protocol Marmot specification
Understand MDK's architecture Architecture index
Understand how clients agree on group state How convergence works
Contribute code Development
Cut a release Release guide

Chat with an AI agent

wn-agent gives an agent runtime its own White Noise identity and bridges encrypted Marmot chats to it over a local control socket (same-user by default, optional bearer token). You invite the agent from White Noise on your phone like any other contact; only accounts you allowlist can invite or message it.

Runtime Connector Docs
Hermes Gateway plugin integrations/hermes
OpenClaw Channel plugin integrations/openclaw
Claude Code Terminal harness integrations/claude
Codex Terminal harness integrations/codex
OpenCode Terminal harness integrations/opencode
Pi Terminal harness integrations/pi
Goose Terminal harness integrations/goose
Your own client wn-agent only Build your own client

The quickstart installs a checksum-verified release on macOS or Linux and gets you to a first encrypted chat. For how connectors share one machine, identities, and allowlists, see How the connectors fit together. The connector daemon itself is documented in crates/agent-connector.

The wn command-line app

wn manages accounts, relays, KeyPackages, chats, groups, and messages, and includes a terminal UI (wn tui). wnd is the background daemon that keeps accounts synced and serves the CLI and TUI. Install both from a checkout:

cargo install --path crates/cli --locked --bins

The wn guide covers configuration, a two-account quick start against local relays, the full command map, the daemon, the TUI, and JSON output for scripting. Explicit dev builds can link and list account devices through wn devices and persistent wnd, using --features dev-device-groups independently of policy-test timing. The explicit wn devices link reset --confirm action discards only the local hidden device-group copy before fresh code pairing; ordinary chat data and credentials survive, while admission and membership limits still apply. Ordinary release builds keep this off.

Build an app on MDK

Apps embed MDK through the multi-account app runtime (marmot-app), exposed as:

  • MarmotKit — UniFFI bindings for Swift (iOS, macOS) and Kotlin (Android). Start with the integration guide, then the complete method reference and distribution notes. Controlled device-group host test builds use the separate experimental constructor and artifact opt-in; ordinary constructors and release artifacts remain disabled.
  • Marmot C — a C ABI over the same runtime, with ownership and blocking-call rules in the C guide and every symbol in its reference.

Each release ships a concise release note and a detailed upgrade guide with required changes, new defaults, and optional features. The latest is 0.16.0 → 0.17.0; read every intervening guide when skipping releases. Read docs at the tag matching your binaries — master may describe unreleased APIs.

How MDK is built

MDK separates the protocol engine from storage, transport, and application concerns so each can be tested, replaced, and reasoned about on its own:

 apps (MarmotKit / C)    wn CLI · wnd · TUI    wn-agent ──► agent runtimes
            └────────────────┬─────┴──────────────┘
                     marmot-app        multi-account runtime, projections
                     marmot-session    account-device runtime over one encrypted session
                     cgka-engine       OpenMLS group state machine + commit convergence
                     storage-sqlite    SQLCipher persistence (one DB per account-device)

 transport-nostr                     the relay plane: shared relay sessions, delivery, directory fetches
 transport-nostr-peeler / -adapter   Nostr events ⇄ engine messages, relay I/O
 transport-quic-stream / -broker     transient live previews for agent replies
 marmot-account                      account homes, signing keys, secret storage
  • The engine is generic over a storage trait and knows nothing about Nostr; transport code lives in the peeler and adapter.
  • Nostr plays three roles — identity, app message format, and (pluggable) transport. See Nostr's role.
  • For the full picture, start with the executive summary, target architecture, and protocol boundary, all linked from the architecture index.

How convergence works

In Marmot, commits are the consensus log. Clients fetch from several relays, see messages in different orders, and may come back online holding commits from abandoned branches. Every honest client that receives the same valid messages must still land on the same epoch and group state. The engine — not relay order or timestamps — picks the canonical branch.

To understand… Read
The convergence model Distributed convergence
The engine's canonicalization contract Canonicalization contract
Temporal convergence and device-linking models Lifecycle models and implementation correspondence
How it is tested: scenarios, vectors, generated chaos, property tests Conformance simulator
Multi-process and container campaigns Campaign runner
Formal proofs and how they map to Rust tests Convergence model, pairing authentication
What the engine owns and leaves out cgka-engine

Crate map

Area Crate What it is
Engine cgka-engine OpenMLS-backed group state machine and commit convergence
traits (cgka-traits) Shared traits and cross-boundary types
Storage storage-sqlite SQLCipher persistence for engine, session, and simulator
fs-private Owner-only file, directory, and socket creation
media-store Encrypted per-file media store: file format and file lifecycle
Transport transport-nostr-peeler Nostr event ⇄ engine message boundary
transport-nostr-adapter Relay I/O behind an injectable client
transport-nostr The relay plane: per-account relay sessions, delivery and directory fetches
transport-quic-stream QUIC transport for live agent text previews
transport-quic-broker Memory-only preview broker (marmot-quic-broker); deployment
App marmot-session Account-device runtime over an encrypted engine session: publish, routing, KeyPackages; tests
marmot-account Account homes, signing keys, secret storage
marmot-pairing Device pairing: the code both screens show before a new device links (unreleased)
marmot-app Multi-account app runtime, projections and host background controls used by every front end
nostr-directory Directory of other people's public Nostr data: lookups, search, KeyPackage resolution
marmot-observability Diagnostics exporters: relay telemetry, product analytics and its consent state, audit delivery
marmot-markdown Odin CommonMark + Nostr parser with a Rust AST bridge
marmot-markdown-ast Owned Markdown types and serde implementations; compiled alongside the native parser
marmot-forensics Append-only JSONL forensic audit schema
Bindings marmot-uniffi MarmotKit: Swift and Kotlin bindings; native-host test recipe
marmot-uniffi-macros Runs MarmotKit's async exports on its own Tokio runtime
marmot-c C ABI bindings
Front ends cli (wn-cli) wn, wnd, and wn tui
Agents agent-connector The wn-agent connector daemon and its doctor setup check
agent-control Agent control protocol messages and framing
agent-stream-compose Live-preview stream composition
integrations/ Per-runtime plugins and terminal harnesses
Verification cgka-conformance-simulator Multi-client scenarios, vectors, chaos, property tests
convergence-campaign-runner Distributed container/VM campaigns
formal/tamarin Tamarin models for convergence and lifecycle
formal/pairing Symbolic pairing authentication and Welcome binding

Development

The toolchain is pinned in rust-toolchain.toml; most tasks run through just.

Builds that include marmot-markdown also require Odin dev-2026-10. The shared installer verifies pinned release checksums before extraction:

bash scripts/install-odin.sh "$HOME/.local/share/mdk-odin"
export ODIN="$HOME/.local/share/mdk-odin/odin"

See the Markdown crate for the compiler pin and native ownership boundary. CI and the campaign/integration container builds install this toolchain automatically.

<details> <summary>Nix / NixOS (x86_64 Linux)</summary>

From this checkout, enter the environment in flake.nix:

nix --extra-experimental-features 'nix-command flakes' develop

The FHS shell provides Clang, pkg-config, nextest, cargo-audit, cargo-llvm-cov, cbindgen, valgrind, Python with uv, Tamarin, Java for TLC and rustup. Rustup reads the toolchain and required components from rust-toolchain.toml. Cargo keeps its usual target/ output directory so the TUI recipes find the binaries they build. The packages are pinned by flake.lock; no global nix-ld configuration is required.

For a single command, use the app entrypoint rather than nix develop -c, whose arguments the FHS shell hook does not forward:

nix --extra-experimental-features 'nix-command flakes' run . -- rustc --version

The relay recipes need a separate docker compose command, provided by rootless Podman with Docker compatibility. The FHS shell replaces the host's /usr, so clients installed in /usr/bin are unavailable inside it. Run relay recipes outside the shell on those hosts, or install the client through Nix on the host.

</details>

just fast-ci                 # formatting, static gates, CI's two clippy passes; skips the `just test` matrix
cargo test -p <crate>        # targeted tests for the crate you changed
just ci                      # full local parity with GitHub CI (slow)

Pull requests run a pre-check of a few minutes: formatting, the static and contract gates (the tracing audit among them), dependency audit, workspace clippy, the WASM build, and the workspace tests with the precheck nextest profile. That profile stops each test after half a second and counts it as passed, so the pre-check fails on a test that fails quickly and leaves the slower ones to the queue. The merge queue runs the full matrix on the exact commit it merges: every workspace test with the ci nextest profile, the CLI and relay end-to-end suites, simulator lanes, C bindings, iOS clippy, Windows filesystem contracts, Tamarin, Hermes and installer checks. Required CI must pass there before a change lands. A queue run stops at its first failed job, so the queue ejects a failing change within minutes rather than after the whole run. Master pushes run CI only to refresh the Rust dependency caches that pull requests and merge groups restore, and only when Cargo.lock, a Cargo.toml, the toolchain pin, Cargo config or ci.yml changes.

Workspace test shards keep the runner's unused SDKs when at least 32 GiB is free; below that budget they reclaim SDK space before downloading the test archive. Builders still reclaim it unconditionally. Archive consumers verify the checksum and require the manifest's expanded size plus a 2 GiB disk reserve before extraction, regardless of whether cleanup ran.

To compare archive layouts before merge, run gh workflow run ci.yml --ref <branch> -f archive_layout_experiment=true on a branch at the exact revision under investigation. This also runs the normal manual CI suite. After merge, you can dispatch Archive layout experiment directly. The experiment builds once and compares fourteen full-archive slice:14 consumers with two binary-local groups of seven slices, balanced by selected test counts, not measured duration. Download the one-day diagnostics: compare archive bytes and creation time, download/extraction time, and test-duration skew within each layout. Compare paired runs; do not add medians from unrelated jobs. Main CI defaults stay unchanged until measurements show an improvement without worse tail latency or lost coverage.

Add ci:full and re-run all jobs to run the full matrix on a pull request, along with complete Android/Apple candidate packaging. ci:apple adds the iOS clippy lane and Apple packaging, and ci:android adds Android packaging; for packaging, re-run all candidate-workflow jobs or push a new commit. Ordinary PRs skip complete native candidate packaging, including Android target compilation and linking; use the opt-in when a change needs that signal before merging. Candidate packaging also runs on master when its inputs change, and the nightly release builds and validates the same packages on nights it does not skip. Existing nightly and weekly campaigns retain their wider coverage. Broker image publishing stays serialized per ref so an older build cannot overwrite a newer latest image.

Common targeted runs:

cargo test -p cgka-engine
cargo test -p cgka-conformance-simulator                            # scenarios, vectors, property tests
cargo test -p cgka-conformance-simulator --features conformance-slow  # wider property-test run
just tamarin                                                        # formal models
just flake-report                                                   # rank tests that failed an attempt in recent merge-queue runs
just flake-stress <package> '<filter>' [count]                      # rerun a filter with no retries to prove a flake fix
just test-timing-ratchet                                            # fail when test files gain sleeps or sub-second timeouts

The CLI's real-relay end-to-end tests need the local relay stack:

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

Notes:

  • Stack size. .cargo/config.toml sets RUST_MIN_STACK=4194304 for Cargo-launched tests and debug binaries; unoptimized OpenMLS can overflow the default 2 MiB thread stack. Export the same value if you run a debug binary directly.
  • WASM. just wasm-check is a compile-only gate for cgka-traits, cgka-engine, and transport-nostr-peeler on wasm32-unknown-unknown (rustup target add wasm32-unknown-unknown; set CC_wasm32_unknown_unknown to a Clang with a wasm32 backend if needed). It does not claim browser support for storage, the runtime, bindings, or the CLI.
  • Commits must be cryptographically signed.

Releases

MDK versions the whole workspace as one compatibility cohort and publishes separate artifact tracks from the same commit: the source snapshot (v<version>), the wn-agent connector (wn-agent-v<version>), MarmotKit bindings (marmotkit-v<version>), and the C bindings (marmotc-v<version>). The release guide is the checklist; per-release notes live in docs/release/.

Nightly pre-releases such as marmotkit-v0.14.0-nightly.20261020 are built every day from the newest master commit that passed CI. They are for testing only: pin a formal release for anything you ship, expect each nightly to be deleted after 30 days, and don't count on going back to an older nightly. See nightly builds.

License

MIT.

Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
©2025–2026 Internet Privacy Foundation. All rights reserved.
Marmot