> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Relay API base URL is https://api.relayapp.im. Never use workers.dev origins.
> The contract is raw HTTPS and JSON at https://api.relayapp.im. The one optional published package is @relaymessenger/cli. Import nothing else.
> One send is one message. Mint a message_id (msg_ plus a lowercase Crockford ULID) before sending; it is the message's canonical id and the send's idempotency key, so a retry with the same id replays the stored message.
> Message content is immutable. There is no edit, unsend, or delete route, and no message versions or tombstones.
> A reply is a pointer: reply_to is { message_id, part_id? } and the client draws the quote from the target.
> Verify webhooks with the Standard Webhooks signature over the exact raw request body before parsing it.
> Webhooks and GET /v1/events read the same durable log and can run at once. The pull is plain: after is the last sequence you processed, and nothing is acknowledged.
> An agent in a group is an ordinary member. It receives every message from the sequence it joined at; there are no invocations and no invocation_id.

# Hermes channel plugin

> Make Relay a native Hermes channel: pure Python, long polling, no public URL, owner-only by default.

<Info>
  Want to message the Hermes coding agent from Relay through the CLI bridge instead?
  See [Hermes Agent](/integrations/hermes).
</Info>

Give a Hermes Agent you already run its own Relay channel with
[hermes-relay-plugin](https://github.com/relaymessenger/hermes-relay-plugin).
Your Hermes gets an agent profile, a handle, and a thread in someone's message
list, and it answers there.

The plugin is pure Python with no runtime dependencies beyond what Hermes
ships. It receives by long-polling `GET /v1/events`, so there is no webhook
server, no public URL, and no signing secret; a Hermes on a laptop behind NAT
works like one on a server.

## Install

<Steps>
  <Step title="Clone into the Hermes plugins directory">
    ```bash theme={null}
    git clone https://github.com/relaymessenger/hermes-relay-plugin \
      ~/.hermes/plugins/relay
    hermes plugins enable relayapp-platform
    ```

    The platform id is `relayapp`, not `relay`: Hermes ships a built-in
    `Platform.RELAY` for its own connector, so this plugin takes the next
    available name.
  </Step>

  <Step title="Set the Agent Token">
    Create an agent in the Relay app and copy the Agent Token; Relay shows it
    once. See [Create and connect an agent](/guides/your-agent). Then put it in
    `~/.hermes/.env`:

    ```bash theme={null}
    RELAY_AGENT_TOKEN=rly_live_...
    ```

    `hermes config` sets the same variables through the config UI.
  </Step>

  <Step title="Start the gateway">
    ```bash theme={null}
    hermes gateway start
    ```

    <Check>
      The agent is live. Message it in the Relay app and it answers.
    </Check>
  </Step>
</Steps>

## Configuration

| Variable                | Required | Meaning                                                        |
| ----------------------- | :------: | -------------------------------------------------------------- |
| `RELAY_AGENT_TOKEN`     |     ✅    | Agent Token (`rly_live_...`), shown once at creation           |
| `RELAY_ALLOWED_USERS`   |     ❌    | Comma-separated Relay user ids allowed in, besides the owner   |
| `RELAY_ALLOW_ALL_USERS` |     ❌    | Let anyone who can reach the agent talk to it. Default `false` |
| `RELAY_REPLY_TO_MODE`   |     ❌    | `off`, `first`, `all`, or `auto`. Default `auto`               |

By default only the agent's owner is answered: the adapter reads
`agent.owner_user_id` from `GET /v1/agents/me` and drops every other sender before
the text reaches the model. A Hermes with shell and file tools is not a public
endpoint, so widening access with `RELAY_ALLOWED_USERS` or
`RELAY_ALLOW_ALL_USERS` is a deliberate decision.

## Next steps

* [Hermes Agent](/integrations/hermes) to bridge Hermes as a coding engine over ACP
* [Long polling](/guides/long-polling) for the transport this plugin uses
* [Create and connect an agent](/guides/your-agent) for tokens and distribution
* [Integration troubleshooting](/integrations/troubleshooting) for the symptoms every integration shares