White Noise

June 27, 2026 · View on GitHub

A secure, private, and decentralized chat app built on Nostr, using the MLS protocol under the hood.

Overview

White Noise aims to be the most secure private chat app on Nostr, with a focus on privacy and security. Under the hood, it uses the Messaging Layer Security (MLS) protocol to manage group communications in a highly secure way. Nostr is used as the transport protocol and as the framework for the ongoing conversation in each chat.

This crate is the core library that powers our Flutter app. It is front-end agnostic and also ships a Unix-style command-line interface — see CLI below.

Status

CI

The Spec

White Noise implements the Marmot protocol, which brings MLS group messaging to Nostr.

CLI

White Noise ships a Unix-style CLI split into two binaries (both gated behind the cli cargo feature):

  • wnd — long-running daemon that owns the Whitenoise singleton (database, Nostr client, MLS state, relay subscriptions). Listens on a Unix domain socket.
  • wn — thin, stateless client. Sends one JSON request over the socket and prints the response. Supports streaming commands, --json output, and multi-account flows (--account <npub> or WN_ACCOUNT).

Install both binaries to ~/.cargo/bin:

just install-cli
# or, equivalently:
cargo install --path crates/whitenoise-cli

Or build from source without installing:

cargo build --release -p whitenoise-cli --bin wn --bin wnd

Quick tour:

wn daemon start              # spawn wnd in the background (or run `wnd` directly to foreground it)
wn create-identity           # create a Nostr keypair
wn login                     # log in with an nsec (reads the secret from the terminal)
wn groups list               # see your MLS groups
wn messages subscribe <id>   # stream live messages from a group

See crates/whitenoise-cli/src/cli/README.md for the full command reference, IPC protocol, and architecture notes.

Releases

Coming soon

Building White Noise Yourself

White Noise is a standard rust crate. Check it out and use it like you would any other crate.

  1. Clone the repo: git clone https://github.com/marmot-protocol/whitenoise-rs.git and cd whitenoise-rs.

In addition, there are extensive integration tests in the codebase that run through much of the API and functions. Run it with the following

just int-test

Check formatting, clippy, and docs with the following:

just check

Check all those things and run tests with precommit

just precommit

Contributing

To get started contributing you'll need to have the Rust toolchain installed (version 1.90.0 or later) and Docker.

  1. Clone the repo: git clone https://github.com/marmot-protocol/whitenoise-rs.git and cd whitenoise-rs.

  2. Install recommended development tools: just install-tools (optional but recommended)

  3. Start the development services (two Nostr relays, a Blossom server, and a local Transponder instance):

    just docker-up

  4. Now you can run the integration tests with just int-test.

just docker-up will auto-generate dev/transponder/.env if it is missing, wait for the local stack to become ready, and put a local-only test key there for the Transponder container. The file is gitignored and should not be committed.

Development Tools

We recommend installing additional cargo tools for enhanced development experience:

just install-tools

This installs:

  • cargo-nextest: Faster parallel test runner
  • cargo-audit: Security vulnerability scanner
  • cargo-outdated: Check for outdated dependencies
  • cargo-llvm-cov: Code coverage reporting
  • cargo-msrv: Verify minimum Rust version
  • cargo-deny: License and dependency checker
  • cargo-expand: Macro expansion tool

See docs/DEVELOPMENT_TOOLS.md for detailed usage instructions.

Formatting, Linting, and Tests

Before submitting PRs, please run the precommit command:

just precommit

Or for a quicker check (without integration tests):

just precommit-quick

Available development commands:

just check           # Run format, clippy, and doc checks
just fmt             # Format code
just test            # Run all tests (uses nextest if available)
just test-cargo      # Force cargo test (slower)
just coverage        # Generate coverage report
just audit           # Security audit
just outdated        # Check for outdated dependencies
just deny-check      # Check licenses and dependencies

Test Coverage

Prerequisites: Docker must be running for coverage tests.

# Start required services
just docker-up

# Generate coverage
just coverage        # Generate lcov.info report
just coverage-html   # Generate HTML report

# View HTML report
open target/llvm-cov/html/index.html

Coverage is automatically tracked in CI as part of the test suite. PRs that decrease coverage will be blocked.

License

White Noise is free and open source software, released under the Gnu AGPL v3 license. See the LICENSE file for details.