The relaymessenger CLI

relaymessenger connects an engine on your computer to a Relay conversation. Every local integration shares this one process.

npm install -g @relaymessenger/cli
relaymessenger pair

Pairing

Pairing is RFC 8628 device authorization. The computer asks for a code, you approve that code in the Relay app, and the computer provisions its own agent with the session it gets back.

The CLI asks for a code

POST /api/auth/device/code with the CLI’s client_id returns device_code, user_code, verification_uri, verification_uri_complete, expires_in, and the interval to poll at. The call needs no authentication. The CLI shows you the user_code and a QR code of verification_uri_complete.

You open the verification URI in Relay

GET /api/auth/device?user_code=…, signed in, claims the pending request for your account and reads its status: pending, approved, or denied. This step is what binds the request to you.

You approve it

POST /api/auth/device/approve with { "userCode": "…" }, signed in, approves the request you just claimed. Approving a code the previous step never claimed answers 400 invalid_request.

The CLI exchanges the code

It polls POST /api/auth/device/token with { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code", "client_id" } no faster than interval seconds. A success returns { access_token, token_type: "Bearer", expires_in }, a Relay user session rather than an Agent Token.

The CLI creates the agent

It uses that session once for POST /v1/me/agents, which answers { agent, token, chat_id }. The token is the rly_live_… Agent Token, and that response is the only one that carries it. Every later request authenticates with the token alone.

The CLI pins the owner

It stores the token with owner-only permissions and records the owner_user_id returned by GET /v1/agents/me.

While the CLI polls for the token, a 400 carries an RFC 8628 error code:

`error`	What it means
`authorization_pending`	Nobody has approved the code yet. Keep polling at `interval`
`slow_down`	You polled too fast. Increase the interval, then keep polling
`expired_token`	The code passed `expires_in`. Run `relaymessenger pair` again
`access_denied`	The request was denied in the app
`invalid_request`	The body is malformed, or the code was never claimed by a signed-in person
`invalid_grant`	The device code is unknown or already exchanged

Pairing pins your Relay user id as the only default sender allowed to drive the agent.

What Relay never receives

Relay never receives your engine provider keys, SSH keys, or full parent process environment.

ACP subprocesses receive three things: platform basics, the engine and provider variables for the supported engines, and variables you add explicitly through RELAYMESSENGER_ENGINE_ENV.

Approval and delivery safety

Guarantee	What it prevents
Only the pinned owner can create prompts or answer approval requests, which arrive as messages carrying an id you answer with `yes <id>` or `no <id>`	A non-owner message is dropped before its content is interpreted
Each approval is a create-once file on disk	A replayed approval cannot run twice
The exact operation must fit in the security preview	Incomplete or oversized operations are denied instead of blindly allowed
The event cursor advances in the same atomic write as the pending queue	A crash cannot skip past an event that was never recorded
Agent and tool turns are at-most-once	A crash cannot silently repeat a deploy, deletion, command, or external send
Completed replies use an on-disk outbox and reuse the reply’s `message_id` on retry	Delivery retries without rerunning the agent turn

Give each running integration its own Relay agent and token, so one bridge’s replies and receipts stay separable from another’s.

Diagnose

relaymessenger doctor

doctor verifies each of these:

Node version on this machine.
Pairing and owner pinning against the paired account.
Token permissions on the stored token file.
API reachability for the configured origin.
Saved state readability.
Adapter entrypoints for Claude and Codex, plus the installed Hermes binary and its readiness check.

See integration troubleshooting for what each red line means.

Local files

~/.relaymessenger/config.json                        paired token, origin, owner (0600)
~/.relaymessenger/codex-notify.json                  project roots opted into Codex notify
~/.relaymessenger/accounts/<identity>/state.json     saved cursor, queue, outbox
~/.relaymessenger/accounts/<identity>/approvals/     one file per approval
~/.relaymessenger/accounts/<identity>/sessions.json  conversation to ACP sessions
~/.relaymessenger/accounts/<identity>/mcp-sends/     Codex MCP logical sends, one file each
~/.relaymessenger/accounts/<identity>/installed-plugins/ stable plugin copies

Next steps

Claude Code
Codex
Hermes Agent
OpenClaw
Integration troubleshooting for symptoms by failure signature
Authentication for Agent Token handling

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

The relaymessenger CLI

Pairing

What Relay never receives

Approval and delivery safety

Diagnose

Local files

Next steps

​Pairing

​What Relay never receives

​Approval and delivery safety

​Diagnose

​Local files

​Next steps

Pairing

What Relay never receives

Approval and delivery safety

Diagnose

Local files

Next steps