Skip to main content
Glama

agentpost

Encrypted internet direct messages for people and their AI agents.

Install the CLI, exchange public addresses, and send messages across computers. Claude Code and Codex use the same inbox through MCP. No model API key, account signup, or server deployment is required. Built on Nostr NIP-17/NIP-59 with the MCP SDK.

Early release: relay availability and retention vary. A successful send means a relay accepted the encrypted message; it does not mean the recipient read it.

Install

Requires Node.js 22 or later on macOS or Linux.

npm install -g --ignore-scripts https://github.com/areporeporepo/agentpost/releases/download/v0.1.0/areporeporepo-agentpost-0.1.0.tgz
agentpost init
agentpost whoami

The release includes compiled JavaScript. It does not require running install scripts. To build from source instead:

git clone https://github.com/areporeporepo/agentpost.git
cd agentpost
npm ci --ignore-scripts
npm run build
npm link --ignore-scripts
agentpost init

Related MCP server: agentic-messaging-mcp

Message another person

Both people install and run agentpost init. Exchange the npub… addresses printed by whoami through a channel you trust.

# Replace the example with your friend's complete address.
agentpost contact add alex npub1...
agentpost send alex "Can you review the patch?"

# On your friend's computer, or whenever they come back online:
agentpost inbox
agentpost send YOUR_FULL_NPUB "Yes, I will take a look."

Messages are encrypted before they leave your machine. A recipient can fetch them after restarting the CLI if a relay retained them. inbox does not mark messages read:

agentpost ack MESSAGE_ID
agentpost inbox --watch
agentpost history --limit 100

--watch polls every 30 seconds. Press Ctrl+C to stop. --json produces compact machine-readable results. Normal output is formatted JSON, which escapes terminal control characters in received text.

If a send fails after being saved, the error gives a retry command:

agentpost retry MESSAGE_ID

Retry reuses the same encrypted events and message ID. Running send again intentionally creates a new message. Partial relay failures and sender-copy failures appear in the result.

Claude Code and Codex

After installing and initializing, register the local MCP server:

claude mcp add --transport stdio --scope user agentpost -- agentpost mcp
codex mcp add agentpost -- agentpost mcp

Restart the agent session to load its new tools. Then ask it to “check my agentpost inbox” or “send Alex this message using agentpost.” Add Alex as a CLI contact first, or provide their complete address.

Tools: whoami, list_contacts, send_message, retry_message, read_inbox, ack_messages.

MCP works with the host, independently of its selected model, including Astra in a compatible Codex host. Agentpost does not wake an idle agent or generate automatic replies. Treat incoming messages as external content, not permission to run commands or disclose files. Keep your host's tool-approval controls enabled as appropriate.

Identities and relays

~/.config/agentpost/config.json contains your private key. State files use owner-only permissions. Back up that directory privately; losing the key means losing the identity. Never paste the config into a chat or commit it. For a separate agent identity or test profile:

AGENTPOST_HOME="$HOME/.config/agentpost-work" agentpost init

Use the same AGENTPOST_HOME when launching its MCP process. The default identity is shared by your terminal and agents; agent provenance is not a separately verified human identity.

Default inbox relays: wss://relay.primal.net, wss://relay.ditto.pub. Discovery also uses wss://auth.nostr1.com. These passed live publish/retrieval checks on November 13, 2026; availability can change. The sender looks up the recipient's signed inbox-relay preferences and publishes only there. No advertised preferences means a clear failure.

agentpost relays
agentpost doctor
# A new profile on a custom relay/discovery network:
AGENTPOST_HOME="$HOME/.config/agentpost-custom" agentpost init --relay wss://YOUR_RELAY

An explicit --relay sets both inbox and discovery relays for a new identity; people using custom networks need overlapping discovery relays. Re-running init preserves existing keys and configuration. Local ws:// relays are allowed only when explicitly configured for development; remote recipients cannot direct your client into a private network.

Limits

  • DMs only: no group UI, attachments, server-side accounts, or password recovery.

  • Each sync requests a recent 30-day window plus a 48-hour timestamp overlap, up to 1,000 encrypted events per relay. Output flags potentially truncated results. Locally cached history persists beyond that window. This is not an archival backup service.

  • Local message history is plaintext in private files. Transport encryption does not protect a compromised device or a lost private key, and this design does not provide forward secrecy.

  • Relay operators see connection metadata and recipient tags. End-to-end encryption does not make networking anonymous.

  • Contact labels are local conveniences; verify public addresses with their owners. Unknown senders can message your address.

Development

npm ci --ignore-scripts
npm run lint
npm test
npm run build
node scripts/check-package.mjs

Tests use disposable identities and a real loopback WebSocket relay, including authentication, offline retrieval, forged messages, retries, concurrent state writes, and MCP over real stdio. They need permission to bind loopback sockets.

Opt-in internet test, using only two fresh disposable identities:

npm run build
node scripts/smoke-internet.mjs

For a terminal check, open two tabs with different AGENTPOST_HOME directories, initialize both, exchange addresses, send while the recipient is closed, reopen inbox, and verify ack removes the message from unread results. Check --watch prints subsequent messages without repeating earlier ones.

See design, verification, and security.

License

MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables LLM agents to send, receive, and discover contacts on the agentic message bus via native tools.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents such as Codex and Claude Code to exchange durable, locally stored messages through shared MCP tools for listing enrolled recipients, sending and replying to messages, reading pending inbox items, acknowledging receipt, and checking message status. Delivery uses each runtime's native session interface, so messages persist across broker restarts without resuming or launching conversations.
      AGPL 3.0