Quick Start

The recommended setup uses the Hermes Web Dashboard and two clearly separated QR actions: first add the standard upstream connection, then pair Relay for the capabilities Hermes does not yet expose upstream.

Recommended path

One app. Two QR codes. Three milestones.

01

Install Android

Use Google Play for the everyday app. Choose Sideload only for Device Control.

02

Connect Hermes

Scan Connect mobile app. This adds the standard Dashboard/Gateway connection.

03

Pair Relay

Scan Pair new device. This unlocks Relay capabilities with a separate grant.

The QR codes are intentionally separate: connecting Hermes does not silently grant Relay access.

Upstream first, Relay encouraged

Chat, sessions, Manage, sign-in, and standard voice use the unmodified Hermes Dashboard/Gateway. The Relay plugin is an encouraged extension for Terminal and TUI, notifications, media handoff, desktop tools, Relay sessions, enhanced voice, and optional Device Control. When upstream Hermes provides a compatible surface, Hermes-Relay prefers it instead of duplicating it.

Recommended full setup

1. Install the Android app

For most people, install the Google Play build. It updates automatically and includes the everyday Hermes experience plus Relay capabilities that do not require Android Device Control.

Choose the signed Sideload APK only when you also want Hermes to read and operate the phone screen. Compare the builds and verify the APK →

2. Start Hermes and install the Relay extension

The Dashboard/Gateway must be running and reachable from the phone:

hermes dashboard

For the recommended full setup, install and start Relay on the Hermes host:

hermes plugins install Codename-11/hermes-relay/plugin --enable
hermes relay doctor
hermes relay start --no-ssl

Use --no-ssl only on a trusted LAN or VPN. For away-from-home access, Tailscale is the recommended route. Refresh or restart the Dashboard/Gateway plugin catalog after installation; a Relay page should appear before you continue.

Relay still runs as its own supervised loopback service, but current Android pairing normally reaches it through the Dashboard's existing address. Port 8767 is therefore an internal/advanced compatibility detail rather than a second address most users must configure.

3. Add the standard Hermes connection by QR

1. Open the Hermes Web Dashboard in a browser.
2. Open Relay and click Connect mobile app.
3. In Android, open Connect and choose Scan Hermes setup QR.
4. Scan the Dashboard QR and sign in if prompted.

This tokenless QR contains only the Dashboard address. The app verifies it and uses the upstream Dashboard/Gateway for Chat, sessions, Manage, sign-in, and standard voice. It does not contain a password, cookie, API key, or Relay pairing code.

4. Pair Relay by QR

Back in the Web Dashboard's Relay page:

1. Click Pair new device and leave mode on Auto unless you need a specific route.
2. In Android, open Settings → Connections → Pair Hermes Relay → Scan QR.
3. Scan the one-time QR and confirm the routes and session duration.

The QR is single-use and normally advertises the Dashboard-origin Relay ingress, plus any configured direct compatibility routes. It can carry LAN, Tailscale, and public candidates so the phone can choose the best reachable route. Pairing unlocks Terminal/TUI, notifications, media handoff, Relay sessions, enhanced voice, desktop-tool handoff, and—on the Sideload build—Device Control.

5. Confirm success and talk

You are ready when:

• Chat · Ready appears and the Chat header has a green connection pulse.
• Manage and Voice are ready, or show the one sign-in action they need.
• Relay · Paired appears when you completed step 4.

Open Chat and send a message. Pairing Relay is encouraged for the complete experience, but an unavailable Relay must not block upstream Chat, Manage, or standard voice.

Other supported paths

Use upstream Hermes without Relay

In Android Connect, choose Find Hermes on LAN. If discovery cannot find the host, choose Enter your Hermes address and enter the Dashboard URL you open in a browser, normally http://<host>:9119. Sign in when prompted.

This path provides Chat, sessions, Manage, and standard voice without installing the Relay plugin. You can pair Relay later from Settings → Connections.

Generate the QR from a terminal

On the Hermes host, run:

hermes pair

The command prints connection details, a scannable one-time QR, a PNG path, and a pasteable hermes-relay://pair?... invite. Scan the QR from Android. This is the same pairing contract used by the Web Dashboard.

No camera or QR available

• Standard connection: enter the Dashboard address manually in Android.
• Relay code: create Pair new device in the Web Dashboard, then use Android's Enter a Relay pairing code path with the shown URL and code.
• Phone-generated code: choose Show Relay code in Android, run the shown hermes pair --register-code <code> command on the host, then tap Connect.

Detailed Android setup and security notes → · Dashboard and Desktop plugin pairing → · Troubleshooting →