Post-quantum messaging. Private by design. Future by default.

Install · Use · Desktop apps · Security · Documentation

Noctweave

Noctweave is a self-hosted toolkit for adding encrypted messaging to an application. It includes a Swift protocol core, a Linux/Docker relay, a working JavaScript client, and a headless CLI. Relays route and store encrypted envelopes; message plaintext and private identity keys stay with clients.

There are no hosted accounts, developer-operated relays, or required central notification services. You choose where every component runs.

Install And Try It

The quickest path uses Docker for the relay and a browser for two local clients.

1. Get the source

git clone https://github.com/luizwidmer/Noctweave.git
cd Noctweave

You need Docker and Node.js 20 or newer. Swift and Bun are only required for the native packages and desktop launchers.

2. Start a relay

export NOCTWEAVE_ADMIN_TOKEN="$(openssl rand -hex 32)"

docker build -t noctweave-relay NoctweaveRelayServer
docker run --rm --name noctweave-relay \
  -p 9339:9339 \
  -p 9340:9340 \
  -p 127.0.0.1:9090:9090 \
  -e NOCTWEAVE_ADMIN_TOKEN \
  -v noctweave-relay-data:/data \
  noctweave-relay \
  --host 0.0.0.0 \
  --port 9339 \
  --http-port 9340 \
  --admin-port 9090 \
  --data-dir /data

The messaging endpoint is http://127.0.0.1:9340. Open the authenticated operator console at http://127.0.0.1:9090/admin/ and enter the generated token.

3. Open two clients

cd NoctweaveJS
npm install
npm run dev:client

Open two independent profiles:

• Alice
• Bob

Set the relay to http://127.0.0.1:9340, create both identities, exchange contact codes, and send a message.

Use The Tools

I want to…	Start here
Run a relay	NoctweaveRelayServer/
Build a browser or Node client	NoctweaveJS/
Integrate from Swift	NoctweaveCore/
Script identities and messages	NoctweaveCLI
Review the wire protocol	Protocol specification

Relay

The relay supports raw TCP, HTTP/HTTPS, WebSocket/WSS, SQLite persistence, attachments, groups, federation, optional IPFS offload, and an authenticated operator console. A solo relay works without federation.

For production deployment, reverse proxies, federation, secrets, and storage, use the relay guide and operator hardening guide.

NoctweaveJS

Run the working browser client:

cd NoctweaveJS
npm install
npm run dev:client

Use the library from an application:

import {
  BrowserLocalStorageStore,
  EncryptedNoctweaveStore,
  NoctweaveRelayClient
} from "@noctweave/js-client";

const relay = new NoctweaveRelayClient("https://relay.example");
const backend = new BrowserLocalStorageStore({ namespace: "my-app:noctweave" });
const store = new EncryptedNoctweaveStore(backend, {
  keyBytes: await loadApplicationKey() // exactly 32 bytes
});

await relay.health();
await store.set("selectedRelay", relay.endpoint);

See the NoctweaveJS guide for browser storage, database adapters, encrypted state, WASM setup, pairing, and interoperability.

NoctweaveCLI

swift run --package-path NoctweaveCore NoctweaveCLI help
swift run --package-path NoctweaveCore NoctweaveCLI health \
  --relay http://127.0.0.1:9340
swift run --package-path NoctweaveCore NoctweaveCLI init \
  --display-name Alice \
  --relay http://127.0.0.1:9340

The CLI supports relay diagnostics, encrypted local identities, contact import and export, direct and group messaging, attachments, continuity events, and identity rotation. See the CLI usage guide.

Desktop Apps

Noctweave includes source-built Electrobun launchers. Electrobun uses the operating system WebView instead of bundling Chromium. Build on each operating system and architecture where the app will run.

Relay launcher:

cd NoctweaveRelayServer
bun install --frozen-lockfile
bun run desktop:icons
bun run desktop:dev

JavaScript client:

cd NoctweaveJS
bun install --frozen-lockfile
bun run desktop:dev

These launchers are convenience tools for local use and evaluation. No official prebuilt desktop binaries are published yet.

What Is Included

• NoctweaveCore — Swift protocol models, cryptographic flows, ratchets, relay primitives, federation logic, and tests.
• NoctweaveRelayServer — Linux/Docker relay, SQLite storage, operator Web UI, federation, and optional IPFS attachment storage.
• NoctweaveJS — browser/Node transports, encrypted stores, a working messaging client, and post-quantum WASM bindings.
• NoctweaveCLI — headless identity, relay, messaging, group, and attachment workflows.
• AgentGuides and AgentSkills — bounded guidance for integrating clients and operating relays through automation.

Foundations And Dependencies

Noctweave builds on established open-source components rather than maintaining custom cryptographic implementations or shipping a browser runtime:

• Open Quantum Safe liboqs supplies ML-KEM-768 and ML-DSA-65. The Docker build pins liboqs 0.15.0 to an immutable commit; Swift uses the vendored XCFramework; JavaScript uses a bounded WASM profile.
• Electrobun packages the optional desktop client and relay launcher with native system WebViews.
• CryptoKit and WebCrypto provide symmetric cryptography where appropriate.
• SQLite provides persistent relay storage; IPFS is an optional encrypted-blob offload target, not an anonymity layer.

Exact versions, hashes, and supply-chain requirements are recorded in the dependency and SBOM policy.

Security Status

Noctweave is pre-1.0 and has not received an independent external audit.

Implemented	Not claimed
ML-KEM/ML-DSA protocol profile	Protection from a compromised operating system
End-to-end encrypted payloads and attachments	Global anonymity
Signed identity continuity and replay rejection	Formal MLS proof
Bounded parsers, stores, and discovery inputs	Single-server cryptographic PIR
Relay ciphertext-only payload storage	Guaranteed closed-app delivery

Review the security requirements, internal audit, and roadmap before production use.

Build And Test

swift build --package-path NoctweaveCore
swift test --package-path NoctweaveCore
swift build --package-path NoctweaveRelayServer
swift test --package-path NoctweaveRelayServer
(cd NoctweaveJS && npm test)

Run the combined public checks with scripts/run-tests.sh. Run release, SBOM, dependency, Docker, and optional container-scan checks with scripts/verify-release.sh.

Documentation

Technical detail lives in focused documents:

• Protocol specification
• Relay OpenAPI schema
• Wire format and test vectors
• Core public API
• Federation protocol and operations
• Relay hardening
• Whitepaper
• Visual identity

Contributing

Contributions to the public protocol, relay, CLI, JavaScript implementation, tests, documentation, and examples are welcome. Read CONTRIBUTING.md for scope, testing, and path-specific license requirements.

License

Noctweave is a multi-license repository. The nearest license file governs:

Path	License
NoctweaveCore/, NoctweaveCLI, NoctweaveRelayServer/	AGPL-3.0-or-later
NoctweaveCore/COMMERCIAL-LICENSE.md	Optional commercial terms for NoctweaveCore
NoctweaveJS/	Apache-2.0
NoctweaveJS/examples/	MIT
NoctweaveDocumentation/, docs/assets/	CC-BY-SA-4.0

See NOTICE, LICENSE, and COMMERCIAL-LICENSE.md for the repository-level summary.