Skip to main content
relayapp connects an agent running on your computer to a Relay conversation. Relay carries messages, approval cards, and final replies; Claude Code, Codex, Hermes Agent, or OpenClaw keeps running locally with its own credentials, tools, files, and session state.

​
The 60-second path

1

Install and pair

Scan the terminal QR code or enter its short code in Relay. Pairing creates a normal Relay agent, returns its Agent Token only to this computer, and pins your Relay user id as the only default sender allowed to drive it.
2

Start an engine bridge

Claude and Codex use adapters bundled at exact versions in relayapp. Hermes uses the hermes acp command already installed on your machine; check it first with hermes acp --check.
3

Text the new agent

A message, or a quick burst of messages, becomes one turn. Relay shows the agent typing while it works, posts one final reply, and presents supported tool permission requests as owner-only Allow/Deny cards.

​
Four supported integrations

OpenClaw is intentionally not an ACP engine preset. Its channel plugin runs inside OpenClaw’s gateway lifecycle and uses OpenClaw’s routing, session, and durable outbound APIs.

​
Claude Code

​
Headless ACP bridge

relayapp launches its exact bundled @agentclientprotocol/claude-agent-acp entrypoint directly with Node, without a shell or a mutable npx latest lookup. Conversation-to-session bindings survive bridge restarts when the adapter supports session loading. Claude must already be authenticated on the computer. Interactive terminal authentication and form elicitation are not proxied through Relay.

​
Native channel plugin

The installer validates the bundled marketplace, copies it into the paired account’s private runtime directory, installs relay@relayapp-bundled, and writes the token, API origin, and owner pin to an owner-only channel .env. It refuses to replace a different configured identity.
Claude Code channels are a research preview. Custom channels require the development-channel flag unless an organization explicitly allowlists the plugin; Team and Enterprise organizations must also enable channels. Channel events arrive only while that Claude session remains open.
The plugin follows Claude’s MCP channel contract: it emits notifications/claude/channel, exposes retry-safe reply and acknowledge tools, and relays permission notifications. Claude currently supplies only a bounded permission input preview. Relay offers remote Allow only when that preview is complete JSON below Claude’s truncation boundary; otherwise the phone can deny and approval must happen locally.

​
Codex

​
Headless ACP bridge

The exact bundled @agentclientprotocol/codex-acp adapter drives Codex’s app-server protocol. Relay preserves streamed text, per-conversation session bindings, cancellation, and permission options. For file-change approvals, the bridge combines Codex’s earlier tool-call diff with the later permission request so the phone sees the exact old and new text. If the operation cannot be represented in full, Relay denies instead of offering a blind Allow.

​
Project-scoped Codex integration

This merges without clobbering user configuration:
  • [mcp_servers.relay] and a completion notify command in ~/.codex/config.toml;
  • a PermissionRequest hook in ~/.codex/hooks.json;
  • a local opt-in for this project root in ~/.relayapp/codex-notify.json.
Other projects remain suppressed until you opt them in separately. Codex may ask you to trust a newly installed hook handler. MCP sends require a caller-stable send_id, so an unknown-outcome retry can reuse the same Relay idempotency key without posting twice.

​
Hermes Agent

Install and authenticate Hermes using its official setup, then verify its ACP surface before starting Relay:
Relay launches hermes acp shell-free and leaves Hermes configuration, provider credentials, and ~/.hermes/state.db under Hermes ownership. The current Hermes ACP server supports persisted session load and resume, streamed assistant and reasoning content, tool activity, diffs, cancellation, plan updates, and permission choices.
Hermes waits 60 seconds for an ACP permission decision, so Relay uses a 55-second phone window and denies on timeout or transport failure.
The reference implementation audited for this release is Hermes Agent 0.18.2. relayapp doctor reports the installed version and runs hermes acp --check; the readiness check, rather than an unverified version-string cutoff, decides whether the local installation can start. Installing and upgrading Hermes stays entirely in your hands.

​
OpenClaw

The installer persists the bundled OpenClaw plugin archive, runs OpenClaw’s plugin installer, adds only the Relay plugin/channel fields to ~/.openclaw/openclaw.json, and stores the token in an owner-only file. Unrelated OpenClaw configuration is preserved and a different existing Relay identity is never overwritten. The plugin follows OpenClaw’s current channel SDK: setup discovery stays network-free, installed packages load built JavaScript runtime entrypoints, inbound events use stable ingress and envelope helpers, and replies use the durable outbound path. Its present product scope is direct conversations and text. Media is represented by a placeholder until Relay exposes agent attachment downloads; reactions and receipts do not start agent turns.

​
Pairing and credential boundary

Pairing is a device-code flow:
  1. The CLI creates a short-lived pairing and long-polls it with a poll token.
  2. Claiming creates a Relay agent owned by your account.
  3. Relay returns that agent’s Agent Token only to the waiting CLI.
  4. The CLI stores the token with owner-only permissions and records the owner user id returned by GET /v1/agents/me.
Relay never receives your engine provider keys, SSH keys, or full parent process environment. ACP subprocesses receive only platform basics, engine/provider variables for the three supported engines, and variables you explicitly add through RELAYAPP_ENGINE_ENV.

​
Approval and delivery safety

  • Only the pinned Relay owner can create prompts or answer approval cards by default. A non-owner message is dropped before its content is interpreted.
  • Each approval is a durable create-once file. The exact operation must fit in the security preview; incomplete or oversized operations are denied.
  • The event cursor advances atomically with the durable pending queue. A crash cannot acknowledge an event that was never recorded.
  • Agent/tool turns are at-most-once. A durable attempt marker prevents a crash from silently repeating a deploy, deletion, command, or external send.
  • Completed replies use a durable outbox and stable idempotency key, so delivery can retry without rerunning the agent turn.
  • Event long-polling is exclusive per Agent Token and mutually exclusive with webhooks. Give every active consumer its own Relay agent/token.

​
Diagnose

doctor verifies Node, pairing and owner pinning, token permissions, API reachability, durable state, exact Claude/Codex adapter entrypoints, and the installed Hermes binary/readiness check. A 401 is terminal and requires re-pairing; it is never retried forever.

​
Local files

​
Next steps