> ## 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.

# Connect Hermes

> Run a Hermes Agent as a Relay contact.

Hermes is an external agent runtime. Relay supplies the contact identity, conversation, events, and message API; Hermes continues to own the model, tools, memory, and process.

Relay ships a Hermes **platform plugin** using the same mechanism as Hermes' Telegram and Discord channels. It long-polls Relay's event log (no webhook, no public URL, works behind NAT), replies with idempotent sends, and streams long answers natively through Relay's draft lifecycle. Install it from the Relay repo:

<Steps>
  <Step title="Install the plugin">
    Copy the plugin into your Hermes install's platform directory:

    ```bash theme={null}
    git clone --depth 1 https://github.com/companion-inc/relay /tmp/relay
    cp -r /tmp/relay/integrations/hermes/relay \
      ~/.hermes/hermes-agent/plugins/platforms/relay
    ```
  </Step>

  <Step title="Create the agent and configure the token">
    In the Relay app choose **Create your own**, name your contact, and copy its one-time Agent Token. Then add to `~/.hermes/.env`:

    ```bash theme={null}
    RELAY_AGENT_TOKEN=relay_agt_live_...
    # optional
    RELAY_API_URL=https://api.relayapp.im
    RELAY_HOME_CHANNEL=cnv_...   # cron / notification delivery target
    ```
  </Step>

  <Step title="Restart the gateway">
    ```bash theme={null}
    hermes gateway restart   # or: systemctl --user restart hermes-gateway
    ```

    The gateway log shows `[Relay] Connected as @yourhandle (agt_…)`.
  </Step>

  <Step title="Pair yourself">
    Text your new contact in Relay. Hermes replies with a one-time pairing code; approve it on the machine running Hermes:

    ```bash theme={null}
    hermes pairing approve relay <CODE>
    ```

    From then on you're recognized automatically, and gateway slash commands (`/whoami`, `/platform list`) work inside the Relay conversation.
  </Step>
</Steps>

Keep `RELAY_AGENT_TOKEN` in the Hermes process environment or its secret manager. It authenticates as the Relay contact and should not be committed to source control.

## Pick a delivery mode

Like Telegram's Bot API, Relay offers two interchangeable ways to receive messages. Use exactly one at a time:

* **Long polling** (`GET /v1/events?timeout=25`): no public inbound URL required. Right for machines behind NAT, home labs, and local development. This is what the Hermes plugin uses.
* **[Webhook](/webhooks)** (`POST /v1/webhook`): Relay pushes signed events to your HTTPS endpoint. Right for hosted runtimes with a public URL.

Both carry the same event envelope and both are at-least-once: deduplicate by `event_id` either way.