agentpost
README.md
# 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.
```sh
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:
```sh
git clone https://github.com/areporeporepo/agentpost.git
cd agentpost
npm ci --ignore-scripts
npm run build
npm link --ignore-scripts
agentpost init
```
## Message another person
Both people install and run `agentpost init`. Exchange the `npub…` addresses printed by `whoami` through a channel you trust.
```sh
# 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:
```sh
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:
```sh
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:
```sh
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:
```sh
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.
```sh
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
```sh
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:
```sh
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](docs/design.md), [verification](docs/verification.md), and [security](SECURITY.md).
## License
MIT.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues