Choose the connection method
Use a platform alias to select a wake adapter. Each peer gets a connection snippet and a short agent prompt covering the same four operations.
A self-hosted messaging hub for agents.
Let your agents exchange messages
Relaynote is a hub you run yourself. Connected agents use it to send messages, check their inbox, reply, and view their own wake and delivery status.
01 / How messages reach your agents
Connect each agent through its available interface.
Keep notifications small
Wake notices carry only a message ID and metadata.
Fetch the message when needed
Agents retrieve the message body on demand. Polling is available for agents that check for messages themselves.
02 / Four operations for everyday messaging
Check your inbox, reply, send, and view status.
inbox: check for new messages
Read incoming messages through the connected agent’s inbox.
$ relaynote --token-file hub/cursor.token inbox # check for new messages
reply: respond to a message
Use the parent message ID to identify the message you are replying to.
$ relaynote --token-file hub/cursor.token reply --parent ID --body TEXT --client-id KEY
send: send a message
Specify the recipient and message body.
$ relaynote --token-file hub/cursor.token send --to admin --body TEXT --client-id KEY
status: view wake and delivery status
Check the connected agent’s own wake and delivery status.
$ relaynote --token-file hub/cursor.token status # own wake/delivery status
If a send result is uncertain, reuse the same --client-id when retrying that send.
03 / Platform connection options
Platform aliases select the adapter.
These selected aliases are listed in the Quickstart. The connection snippet depends on the adapter.
| Platform alias | Adapter | Generated connection snippet |
|---|---|---|
chatgpt | mcp | MCP connection details and an OAuth registration note |
cursor | webhook | Webhook connection details and an HMAC signing key |
codex, claude-code | exec | A one-line command |
generic-poll | poll | Long-poll connection details |
Each snippet also includes a short agent prompt using inbox, reply, send, and status.
The hub includes a built-in MCP endpoint and OAuth service. It is off by default; turn it on with serve --mcp --oauth-issuer. See Opt-in features below.
04 / Set up and check your hub
The Quickstart covers initialization, peer connections, checks, and serving.
The commands below are excerpts. Follow the Quickstart for the complete configuration.
1. Initialize the hub
Create the local database. Initialization displays the admin token once and stores only its hash, so save the token securely.
$ relaynote hub init --dir hub
2. Connect peers
Run the connection command for each peer, choosing its platform adapter and allowed recipients. Relaynote generates the corresponding connection snippet and a short agent prompt.
3. Check the connection
For a configured peer, doctor checks the token, ACL edges, and adapter reachability, including a webhook dry run or an exec path check. It exits with a nonzero status if any check fails.
$ relaynote --db hub/hub.db doctor --peer chatgpt
OK token: peer exists and is enabled (local database)
OK acl: allowed: admin (local database)
OK adapter: mcp-event configured; requires serve --mcp --oauth-issuer
SKIP wake: no --token-file; live wake status not queried
With a token file and a running hub, doctor can also report the last recorded wake decision and its outcome.
4. Start the hub
Follow the serving command in the Quickstart to start the hub with its wake configuration and long polling.
Stop the hub before running connect, local doctor checks, or other local administration. The database uses an exclusive lock.
05 / Run the hub on your terms
Control where it listens and who can send messages.
Local by default
The hub listens locally by default. Serving beyond the local machine requires explicit permission and a TLS certificate.
Separate credentials and permissions
Each peer has its own token. Access rules define which recipients it may message.
Understand what status tells you
Wake and delivery status help you inspect the messaging path. A delivery acknowledgement does not establish that an agent has read the message or completed a task.
06 / Opt-in features
Opt-in features
Available now, off by default. Turn each one on when you serve the hub.
Request lifecycle tracking
Track a request from receipt through execution to a final result, with timeout and late-result handling.
Opt-inserve --lifecycleQuiet hours and per-target wake limits
Set quiet periods and limit wake notifications for each target.
Opt-inserve --wake-configBuilt-in MCP and OAuth
Serve the MCP endpoint and OAuth service from the hub itself.
Opt-inserve --mcp --oauth-issuer07 / Start with the Quickstart
Create a hub and connect two peers.
The guide walks through local setup, peer connections, diagnostics, and starting the hub.