Setup guide

Fetch plugin for Hermes

Pair the Fetch app to your Hermes Agent, get a push the moment a turn finishes or your agent needs you, and make fetch a delivery target for scheduled and proactive messages.

Overview

Fetch is the iOS app that gives your Hermes Agent a phone. The Fetch plugin is a single Hermes package that pairs the app to your agent — like linking WhatsApp Web — then notifies you when a turn finishes or the agent blocks on an approval, and registers fetch as a delivery channel for cron jobs and webhooks.

Everything runs through a hosted relay, so there’s no Apple Developer account, no .p8 on your machine, no edits to Hermes core, and no inbound port or browser tab to keep open. This host only ever stores an anonymous per-agent id and secret.

Prerequisites

You’ll need two things before you start:

Hermes Agent with the CLI
The hermes command available on the machine running your agent. See Hermes Agent.
The Fetch iOS app
Installed on your iPhone. Join the beta to get the TestFlight link.

Install the plugin

Run these three commands on the machine that hosts your agent.

Install and enable the plugin

hermes plugins install brentmwarner/hermes-fetch-plugins/fetch-plugin --enable

Restart the gateway so the hooks load
Hooks load once at agent startup. Restart a separately-managed hermes dashboard too, if you run one.
```
hermes gateway restart
```
Run setup and choose Fetch
Hermes generates a relay link and QR code to pair your phone.
```
hermes setup
```

Restart required after install.The notification hooks only load when the agent starts, so the gateway restart in step 2 is what turns them on.

Pair your phone

In setup, choose Fetch. Open the app on your iPhone and scan the QR code — or paste the generated link — to pair, then allow notifications when prompted.

Pairing reaches your agent through the hosted relay, so there’s no inbound port to open, no Tailscale, and no browser tab to keep alive. Relay setup starts a headless local Hermes runtime automatically and keeps a reverse tunnel open after hermes setup exits, so your phone can reach the agent without a public dashboard URL.

Send messages to Fetch

Once paired, fetch is a first-class messaging and delivery target. Your agent can message you directly:

send_message(target="fetch", text="Deploy finished — all green.")

And you can schedule proactive pushes with cron:

hermes cron create "every 15m" "Send my summary to Fetch." --deliver fetch

Target a named channel to keep a conversation together. fetch:world-cup resolves to a stable thread in the app, so repeated deliveries append to the same conversation instead of starting a new one. Bare --deliver fetch uses your home channel.

hermes cron create "every 15m" "Summarize the World Cup" --deliver fetch:world-cup

Make your agent reach out

On a fresh install with no other platform configured, Fetch is your agent’s default place to reach you — no Telegram bot or other API setup required. To nudge it to message you on its own, add a line to ~/.hermes/SOUL.md:

You can reach me on my phone through Fetch. For anything time-sensitive or worth knowing while I’m away from the terminal — finished work, blockers, a heads-up, scheduled summaries — send it to the fetch channel.

Configuration

Most users set nothing — Fetch setup configures delivery and the reverse tunnel for you, and the default hosted relay is https://push.tryfetchapp.com. The optional knobs below are all prefixed HERMES_FETCH_.

Variable	Default	Purpose
`HERMES_FETCH_RELAY_URL`	hosted relay	Point at a different or locally-run relay.
`HERMES_FETCH_RELAY_REGISTRATION_TOKEN`	none	Enrollment token, if your relay requires one.
`HERMES_FETCH_TUNNEL_ENABLED`	enabled by setup	Keep the agent-side reverse tunnel active for relay pairing.
`HERMES_FETCH_TUNNEL_DISABLE_DASHBOARD_AUTOSTART`	unset	Opt out if you manage the local Hermes dashboard/API process yourself.

Notes & limits

Every surface notifies
Because the trigger fires in the agent core, a reply you type anywhere — phone, web dashboard, or terminal — pushes your phone. The relay de-dupes a short window and the app suppresses the banner for the thread you’re already viewing.
Quiet on silent stalls
A push fires when a turn ends with a real response, or when the agent blocks on an approval or clarifying question. Tool-only, interrupted, or empty turns don’t notify.
One key, off your machine
The relay holds the single Fetch APNs key and is the only component that talks to Apple. Your host stores only an anonymous agent_id and agent_secret, minted automatically on first use.