# Documentation

> MDK 0.17.0 · [Read on Marmot](https://marmot.build/docs/) · [Version-pinned source](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/README.md)

## MDK — Marmot Development Kit

MDK is the Rust implementation of [Marmot](https://github.com/marmot-protocol/marmot), an end-to-end encrypted group messaging protocol built on [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420) 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](https://github.com/marmot-protocol/marmot). This repository holds the implementation, its architecture notes, conformance tests, formal models, and release tooling.

## Contents

*   [Find your way](https://marmot.build/docs/#find-your-way)
*   [Chat with an AI agent](https://marmot.build/docs/#chat-with-an-ai-agent)
*   [The `wn` command-line app](https://marmot.build/docs/#the-wn-command-line-app)
*   [Build an app on MDK](https://marmot.build/docs/#build-an-app-on-mdk)
*   [How MDK is built](https://marmot.build/docs/#how-mdk-is-built)
*   [How convergence works](https://marmot.build/docs/#how-convergence-works)
*   [Crate map](https://marmot.build/docs/#crate-map)
*   [Development](https://marmot.build/docs/#development)
*   [Releases](https://marmot.build/docs/#releases)
*   [License](https://marmot.build/docs/#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](https://marmot.build/docs/agents.html) |
| Write your own bot or client against `wn-agent` | [Build your own client](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/custom-client.md) |
| Use White Noise from a terminal (CLI, daemon, TUI) | [`wn` guide](https://marmot.build/docs/cli.html) |
| Integrate MDK into an iOS, macOS, or Android app | [MarmotKit integration guide](https://marmot.build/docs/native-apps.html) |
| Integrate from C or another raw-FFI host | [C ABI guide](https://marmot.build/docs/c-interface.html) |
| Upgrade an app to a new MDK release | [Version upgrade guides](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/integration/README.md) |
| Understand the Marmot protocol | [Marmot specification](https://github.com/marmot-protocol/marmot) |
| Understand MDK's architecture | [Architecture index](https://marmot.build/docs/architecture.html) |
| Understand how clients agree on group state | [How convergence works](https://marmot.build/docs/#how-convergence-works) |
| Contribute code | [Development](https://marmot.build/docs/#development) |
| Cut a release | [Release guide](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/release.md) |

## 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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/hermes/marmot/README.md) |
| OpenClaw | Channel plugin | [integrations/openclaw](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/openclaw/marmot/README.md) |
| Claude Code | Terminal harness | [integrations/claude](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/claude/marmot/README.md) |
| Codex | Terminal harness | [integrations/codex](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/codex/marmot/README.md) |
| OpenCode | Terminal harness | [integrations/opencode](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/opencode/marmot/README.md) |
| Pi | Terminal harness | [integrations/pi](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/pi/marmot/README.md) |
| Goose | Terminal harness | [integrations/goose](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/goose/marmot/README.md) |
| Your own client | `wn-agent` only | [Build your own client](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/integrations/custom-client.md) |

The [quickstart](https://marmot.build/docs/agents.html) 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](https://marmot.build/docs/agents.html#how-the-connectors-fit-together). The connector daemon itself is documented in [`crates/agent-connector`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/agent-connector/README.md).

## 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:

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

The [`wn` guide](https://marmot.build/docs/cli.html) 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](https://marmot.build/docs/cli.html#device-linking-dev-builds) 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`](https://marmot.build/docs/rust-runtime.html)), exposed as:

*   **MarmotKit** — UniFFI bindings for Swift (iOS, macOS) and Kotlin (Android). Start with the [integration guide](https://marmot.build/docs/native-apps.html), then the [complete method reference](https://marmot.build/docs/native-api.html) and [distribution notes](https://marmot.build/docs/distribution.html). Controlled device-group host test builds use the separate [experimental constructor and artifact opt-in](https://marmot.build/docs/native-apps.html#experimental-device-group-test-builds); 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](https://marmot.build/docs/c-interface.html) and every symbol in its [reference](https://marmot.build/docs/c-api.html).

Each release ships a concise [release note](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/release/) and a detailed [upgrade guide](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/integration/README.md) with required changes, new defaults, and optional features. The latest is [0.16.0 → 0.17.0](https://marmot.build/docs/upgrading.html); 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:

```text
 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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/overview/nostr-role.md).
*   For the full picture, start with the [executive summary](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/overview/executive-summary.md), [target architecture](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/overview/target-architecture.md), and [protocol boundary](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/overview/protocol-boundary.md), all linked from the [architecture index](https://marmot.build/docs/architecture.html).

## 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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/distributed-convergence.md) |
| The engine's canonicalization contract | [Canonicalization contract](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/docs/marmot-architecture/cgka-engine-canonicalization-contract.md) |
| Temporal convergence and device-linking models | [Lifecycle models and implementation correspondence](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/formal/liveness/README.md) |
| How it is tested: scenarios, vectors, generated chaos, property tests | [Conformance simulator](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/cgka-conformance-simulator/README.md) |
| Multi-process and container campaigns | [Campaign runner](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/convergence-campaign-runner/README.md) |
| Formal proofs and how they map to Rust tests | [Convergence model](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/formal/tamarin/README.md), [pairing authentication](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/formal/pairing/README.md) |
| What the engine owns and leaves out | [`cgka-engine`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/cgka-engine/README.md) |

## Crate map

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

## Development

The toolchain is pinned in [`rust-toolchain.toml`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/rust-toolchain.toml); most tasks run through [`just`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/Justfile).

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

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

See the [Markdown crate](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/crates/marmot-markdown/README.md#build-requirements) for the compiler pin and native ownership boundary. CI and the campaign/integration container builds install this toolchain automatically.

&lt;details> &lt;summary>Nix / NixOS (x86\_64 Linux)&lt;/summary>

From this checkout, enter the environment in [`flake.nix`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/flake.nix):

```bash
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`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/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`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/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:

```bash
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.

&lt;/details>

```sh
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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/.github/workflows/archive-layout-experiment.yml) 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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/release.md#nightly-builds) 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:

```sh
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:

```sh
just relay-up
just e2e-test
just relay-down
```

Notes:

*   **Stack size.** [`.cargo/config.toml`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/.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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/release.md) is the checklist; per-release notes live in [`docs/release/`](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/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](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/release.md#nightly-builds).

## License

[MIT](https://github.com/marmot-protocol/mdk/blob/4df811aea99269b437a6023be9446a5141e93cbe/LICENSE).
