Documentation
This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.
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
wncommand-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.tomlsetsRUST_MIN_STACK=4194304for 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-checkis a compile-only gate forcgka-traits,cgka-engine, andtransport-nostr-peeleronwasm32-unknown-unknown(rustup target add wasm32-unknown-unknown; setCC_wasm32_unknown_unknownto 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.