elizaos--eliza/plugins/plugin-nostr

@elizaos/plugin-nostr

Nostr decentralized messaging plugin for elizaOS agents. Gives an Eliza agent a Nostr identity and connects it to one or more relays, enabling encrypted direct messages (NIP-04), public note publishing (kind:1), and profile management (kind:0).

What it adds

• Encrypted DMs (NIP-04) — receive and send encrypted direct messages; routes through the MESSAGE connector action so the agent's planner needs no plugin-specific actions.
• Public notes (kind:1) — publish notes to connected relays; routes through the POST connector action. Supports relay feed reading and NIP-50 relay search where the relay implements it.
• Profile publishing (kind:0) — publish agent profile metadata (name, picture, nip05, etc.) to relays.
• Multi-relay redundancy — publishes to all configured relays; succeeds when at least one accepts the event.
• Multi-account support — run the agent under multiple Nostr identities simultaneously.

Enabling the plugin

Add @elizaos/plugin-nostr to the plugins array in the agent character file, or let the auto-enable engine activate it automatically when a connectors.nostr block is present in the agent config.

{
  "plugins": ["@elizaos/plugin-nostr"],
  "settings": {
    "NOSTR_PRIVATE_KEY": "your-private-key-hex-or-nsec",
    "NOSTR_RELAYS": "wss://relay.damus.io,wss://nos.lol,wss://relay.nostr.band",
    "NOSTR_DM_POLICY": "pairing"
  }
}

Configuration

Environment variables

Variable	Required	Default	Description
NOSTR_PRIVATE_KEY	Yes	—	Private key in hex (64 chars) or nsec1 bech32 format
NOSTR_RELAYS	No	damus.io, nos.lol, relay.nostr.band	Comma-separated relay WebSocket URLs
NOSTR_DM_POLICY	No	pairing	DM acceptance policy (see below)
NOSTR_ALLOW_FROM	No	—	Comma-separated pubkeys allowed to DM (required for allowlist policy)
NOSTR_ENABLED	No	true	Set to false to disable without removing config
NOSTR_ACCOUNTS	No	—	JSON array or object for multi-account configuration
NOSTR_DEFAULT_ACCOUNT_ID	No	"default"	Default account when multiple are configured

Character file override

Settings can be embedded directly in the character file under settings.nostr:

{
  "settings": {
    "nostr": {
      "privateKey": "...",
      "relays": ["wss://relay.damus.io", "wss://nos.lol"],
      "dmPolicy": "allowlist",
      "allowFrom": ["npub1...", "deadbeef..."],
      "profile": {
        "name": "my-agent",
        "nip05": "agent@example.com"
      }
    }
  }
}

For multiple accounts, use settings.nostr.accounts:

{
  "settings": {
    "nostr": {
      "accounts": {
        "main": { "privateKey": "...", "relays": ["wss://relay.damus.io"] },
        "alt":  { "privateKey": "...", "relays": ["wss://nos.lol"] }
      }
    }
  }
}

DM policies

Policy	Description
open	Accept DMs from any pubkey
pairing	Accept DMs and remember senders
allowlist	Only accept DMs from pubkeys in NOSTR_ALLOW_FROM
disabled	Ignore all incoming DMs

Nostr concepts

• Private key — signs events and decrypts messages. Never commit to version control; use env vars or a secrets manager.
• Public key — derived automatically from the private key. This is the agent's Nostr identity.
• npub / nsec — bech32-encoded formats for public/private keys. Both formats are accepted as input.
• kind:0 — profile metadata event.
• kind:1 — public text note.
• kind:4 — NIP-04 encrypted DM.

Security

• Generate keys with a trusted tool such as nostr-tools (generateSecretKey + getPublicKey).
• Start with a restrictive DM policy (allowlist) and relax as needed.
• Consider running a private relay for sensitive agent deployments.

Development

bun run --cwd plugins/plugin-nostr build
bun run --cwd plugins/plugin-nostr test
bun run --cwd plugins/plugin-nostr typecheck