Sovereign Nostr identity for AI agents and humans. 238 tools. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, or any MCP client.
npx nostr-bray
click to copy
Pubkeys prove ownership. They do not prove identity, reputation, or intent. Every Nostr user, human or AI, runs into the same three gaps.
Anyone can claim to be anyone. Impersonation is trivial. Without verifiable attestations, there is no way to tell a real person from a bot or an impostor.
Your Web of Trust lives in your head. There is no machine-readable social graph distance, so every feed is a flood and moderation is all-or-nothing.
You can post publicly or encrypt to one person. There is no way to share content with a trusted tier (members, subscribers, crew) without bespoke infrastructure.
Lose your nsec, lose your identity forever. No recovery, no recourse. Your entire social graph, reputation, and history, gone.
If forced to hand over your key, the attacker gets everything. There is no way to comply under duress while signalling the situation.
AI agents share your key or generate throwaway ones. No hierarchy, no recovery, no context separation. The agent's actions are indistinguishable from yours.
Bray combines three independent trust signals into a single, unified surface. Each dimension answers a different question.
Not workarounds. Proper cryptographic primitives across three axes: who you are, how close you are, and what you can see.
Seven Signet tools let any agent fetch, vouch, challenge, and enforce identity claims. Policy checks gate access by verification tier. No hand-rolled logic required.
SignetTrust scores derived from your social graph weight every interaction. Filter spam by graph distance. Endorse peers. Surface content from people you actually know.
trust-scoreEight Vault tools create Dominion-encrypted content channels. Tiered keys are derived per epoch. Revoke a member's access and their old keys cannot decrypt new content.
VaultOne master secret generates unlimited child key pairs via nsec-tree. Derive personas for work, personal, anonymous use, each cryptographically independent.
nsec-treeSplit your master secret into BIP-39 word shards. Distribute them to trusted parties. Any threshold subset reconstructs the original. No single point of failure.
shamir-wordsNIP-17 gift wrapping hides sender, recipient, and conversation metadata. No opt-in required; it is the default for every DM.
NIP-17Configure an alternative identity that activates under coercion. Indistinguishable from a normal persona switch. The attacker cannot tell you have complied under duress.
canary-kitPrivate keys are cryptographically zeroed from memory on identity eviction and process shutdown. LRU cache ensures minimal key material exposure at any given moment.
IdentityContextEvery tool operates as the active identity. Switch persona, and your posts, DMs, attestations, and payments all follow. No configuration changes needed.
Create, derive, switch, prove, backup, restore, and migrate Nostr identities. Guided setup, Shamir recovery, NIP-05 lookup and verification.
Posts, DMs, contacts, profiles, notifications, feeds, Blossom media, and NIP-29 groups. Name-based lookups across your contact graph. Scheduled posting with cron support.
Verifiable attestations, ring signatures for anonymous proofs, spoken verification tokens, linkage proofs, deep attestation and ring analysis.
Lightning payments via Nostr Wallet Connect. Send, receive, invoice, check balances, decode bolt11. Per-identity wallet configuration.
Per-identity relay lists with NIP-65 management. Query events with NIP-50 search, NIP-45 counting, NIP-42 authentication, relay intelligence and health monitoring.
Duress personas for coercion resistance, plus CANARY liveness proofs for dead-man's-switch assurance.
Media uploads to Blossom servers. Upload, list, delete, mirror, verify, repair, discover servers, and manage storage.
NIP-29 group chat. Fetch metadata, read messages, send to groups, list members.
Publish and read community-proposed Nostr Implementation Possibilities (kind 30817).
Encode, decode, encrypt, verify, filter, fetch. NIP-44 encryption, NIP-49 key encryption, event verification.
Progressive identity verification. Fetch badges, issue vouches, run challenges, enforce policy. Four tiers from self-declaration to cryptographic attestation.
Epoch-based encrypted access control via Dominion. Create content tiers, manage members, rotate keys, and revoke access, all without a server or a database.
Labels, mute lists, pin lists, follow sets, and bookmarks. Content moderation building blocks for agents that need to curate, filter, or organise.
Pedersen commitments and zero-knowledge range proofs. Prove properties about values (age, balance, reputation) without revealing the values themselves.
Discover, probe, call, and publish L402/x402 paid services. Lightning-gated API access with automatic payment negotiation.
Model-agnostic AI-to-AI collaboration over encrypted Nostr DMs. Send tasks, check inboxes, return results, publish and discover capabilities via NIP-89.
Dispatch lets AI agents send tasks to other AI agents, check for incoming work, and return results. All communication is NIP-17 gift-wrapped. Discovery uses NIP-89 application handlers. 13 tools, model-agnostic, works across any MCP client.
Stop converting between formats. Pass a display name, a NIP-05 address, an npub, or a raw hex pubkey to any tool that takes an identity. Bray resolves it for you.
dm-send --to "alice"
dm-send --to "alice@nos.social"
dm-send --to "npub1..."
dm-send --to "ab12..."
Bray implements or integrates with these Nostr Implementation Possibilities. Not just read support; full signing, encryption, and verification where the NIP requires it.
Schedule posts, articles, and DMs with cron expressions or specific timestamps. Events are signed immediately with your current identity, then held until the scheduled time. No background process required on your machine.
# post at a specific time npx nostr-bray post "good morning" --at "2026-04-01T09:00:00Z" # post on a cron schedule npx nostr-bray post "weekly update thread" --cron "0 9 * * MON" # schedule via MCP (any AI agent) post-schedule content="launching tomorrow" at="2026-04-01T12:00:00Z"
Use bray as an MCP server for AI agents (Claude, ChatGPT, Gemini, Cursor, Windsurf) or as a standalone CLI. The MCP server exposes all 238 tools; the CLI surfaces the most common operations. Both share the same handlers, identity engine, and security guarantees.
// claude_desktop_config.json // Option A: Heartwood or NIP-46 bunker (safest) { "mcpServers": { "nostr": { "command": "npx", "args": ["nostr-bray"], "env": { "BUNKER_URI": "bunker://<pubkey>?relay=wss://relay.damus.io" } } } } // Option B: file-based secret // Replace BUNKER_URI with: // "NOSTR_SECRET_KEY_FILE": "~/.nostr/secret.key", // "NOSTR_RELAYS": "wss://relay.damus.io"
# start your bunker (runs in background) npx nostr-bray bunker & # connect to it export BUNKER_URI="bunker://<pubkey>?relay=wss://relay.damus.io" # go npx nostr-bray whoami npx nostr-bray post "hello from bray" npx nostr-bray persona work npx nostr-bray prove blind
Bray assumes a hostile environment. Every default is the most private option. Every key operation has a zeroing path. Secrets never appear in tool responses.
Gift-wrapped DMs hide sender, recipient, and metadata. NIP-04 requires explicit opt-in via environment variable.
Best with Heartwood (dedicated signing appliance with nsec-tree derivation), then any NIP-46 bunker, then ncryptsec, then key file. Your private key never leaves your signer.
Private keys are cryptographically zeroed from memory on LRU eviction and process shutdown. Minimal exposure window.
Tool responses never return raw private keys. Mnemonics are returned only during identity creation (store securely). Shamir shards are written to files, not returned as text.
Secrets loaded from files are scrubbed from process.env immediately after parsing. No lingering plaintext in memory.
NIP-65 relay list events are signature-verified before use. Relay information documents are validated against NIP-11.
Bray stands on existing Nostr tooling. It does not replace nostr-tools or nak. It adds a narrow, opinionated identity layer on top.
838 stars · 1.2M monthly npm downloads
Our primary dependency. Handles event creation, signing, NIP-44 encryption, relay connections, and most protocol-level heavy lifting. If you are building a Nostr client in JavaScript, nostr-tools is the standard.
by fiatjaf (the Nostr protocol creator) · Go
The definitive Nostr Swiss Army knife. Covers far more ground than bray: MuSig2 collaborative signing, built-in relay with negentropy sync, FUSE filesystem, NIP-60 Cashu wallet, smart outbox routing, PoW mining, NIP-86 relay admin, and a full bunker with persistence and QR codes. If you want a power-user CLI for Nostr, nak is it.
A narrow set of capabilities that revolve around one theme: trust-aware Nostr for AI and humans.
All bundled into a single MCP server with 238 tools, so an AI agent gets a complete trust-aware Nostr identity out of the box without stitching together multiple tools.
# no install needed, npx runs it directly npx nostr-bray --help # or install globally npm install -g nostr-bray
Three options, safest first:
# RECOMMENDED: NIP-46 bunker (key never touches bray) # Terminal 1: start the bunker with your key npx nostr-bray bunker # Terminal 2: connect to it export BUNKER_URI="bunker://<pubkey>?relay=wss://relay.damus.io" npx nostr-bray whoami
# GOOD: file-based secret (protected by file permissions) echo "nsec1..." > ~/.nostr/secret.key chmod 600 ~/.nostr/secret.key export NOSTR_SECRET_KEY_FILE="~/.nostr/secret.key" export NOSTR_RELAYS="wss://relay.damus.io,wss://nos.lol"
# QUICK (testing only): env var export NOSTR_SECRET_KEY="nsec1..." export NOSTR_RELAYS="wss://relay.damus.io,wss://nos.lol"
# check your identity npx nostr-bray whoami # derive a work persona npx nostr-bray persona work # post as that persona npx nostr-bray post "hello from my work identity" # create a shamir backup npx nostr-bray backup-shamir --shares 5 --threshold 3