codename-11/hermes-relay/hermes-relay-desktop-setup

Hermes-Relay Desktop CLI Setup

Experimental. The desktop CLI at desktop/ is a preview-grade thin client. Pairing, chat, shell (PTY pipe to the host), and local tool routing (desktop_terminal / desktop_read_file / desktop_write_file / desktop_search_files / desktop_patch) all work end-to-end. Daemon mode, multi-client routing, and code-signed binaries are the v1.0 polish — see the ROADMAP.

The Hermes-Relay desktop CLI (hermes-relay) is a thin client that gives you remote access to a Hermes agent running on another machine. It pipes a full PTY shell (with the agent's native Ink TUI), streams structured chat events for scripting, and — uniquely — lets the remote agent execute tools on your local machine (read files, run shell commands, search the filesystem) through a round-trip over the same WSS relay the Android client uses. The agent brain stays on the host; your laptop is the hands.

When to Use

Invoke this skill when any of the following happens:

• User runs the /hermes-relay-desktop-setup slash command.
• User asks to "install the Hermes-Relay CLI", "set up hermes-relay on my laptop", "pair this desktop with my Hermes server", "hermes-relay shell isn't working", or anything equivalent.
• User is on a fresh machine and wants to connect to an existing Hermes-Relay host.
• User reports any of: hermes-relay command not found, Node version mismatch, auth timeouts, "No desktop client connected" errors, pasted-pairing-code mangled by bracketed paste, or desktop tools that "time out immediately" (seconds↔ms unit bug in pre-0.6 builds).

Do NOT use this skill to troubleshoot the relay server itself (that's hermes-relay-self-setup) or the Android client (that's hermes-relay-self-setup too). This skill is desktop-CLI-specific, running on the user's laptop/workstation.

Unique Capability: Live Local Diagnostics

This skill can invoke `desktop_terminal` to run commands on the user's own machine — a capability the Android skill can't match. Use it aggressively during install / pairing / troubleshooting:

User: "Install the hermes-relay CLI"
→ [desktop_terminal] node --version
   Result: v20.10.0  →  Too old
→ "Node 21+ required. Upgrade via https://nodejs.org, then I'll retry."
→ User upgrades
→ [desktop_terminal] node --version   →  v22.0.1   OK
→ [desktop_terminal] npm install -g @hermes-relay/cli
→ [desktop_terminal] hermes-relay --version   →  0.3.0-alpha.18   Success

Never guess the user's state — measure it. desktop_terminal is cheap; one call per check is the right cadence.

Prerequisites

1. The Hermes-Relay server is running on the host and reachable from this machine. Verify:

``bash curl -s http://<host>:8767/health ` Expect {"status":"ok","version":"1.1.0"} or later. If it fails, the user's server is down — stop here and run /hermes-relay-self-setup or /hermes-relay-doctor` on the host instead.

1. One of:

• Node.js ≥21 on this machine (for the built-in global WebSocket). Verify node --version ≥ v21. Older Node refuses to run.
• A prebuilt hermes-relay binary from GitHub Releases (no Node required). Use this path on Windows desktops where Node isn't already installed.

1. Network path from here to `<host>:8767`. If the user is roaming (work + home + coffee shop), multi-endpoint pairing (ADR 24) handles it automatically — no prerequisite here.

Procedure

A. Install

Three install methods in decreasing order of Node-flexibility. Pick the first the user can do.

A1. Binary (Windows — recommended, no Node required)

irm https://raw.githubusercontent.com/Codename-11/hermes-relay/main/desktop/scripts/install.ps1 | iex

• Downloads hermes-relay-win-x64.exe from the latest GitHub Release.
• Verifies SHA256 against the published SHA256SUMS.txt.
• Installs to %USERPROFILE%\.hermes\bin\hermes-relay.exe and adds that directory to the user PATH.
• The binary is currently unsigned (experimental phase). Windows SmartScreen may show "Windows protected your PC" on first launch. Click "More info" → "Run anyway", or pre-unblock via Unblock-File.

Pin a version: $env:HERMES_RELAY_VERSION='desktop-v0.3.0-alpha.1'; irm ... | iex.

Uninstall: delete %USERPROFILE%\.hermes\bin\hermes-relay.exe and remove the PATH entry from System Properties → Environment Variables → User → Path.

A2. Binary (macOS / Linux — recommended, no Node required)

curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/desktop/scripts/install.sh | sh

• Detects OS/arch (linux-x64, darwin-x64, darwin-arm64).
• Downloads the matching binary + SHA256 checksum from the latest release.
• Installs to $HOME/.hermes/bin/hermes-relay and appends that path to ~/.bashrc or ~/.zshrc if not already present.
• macOS Gatekeeper will quarantine the unsigned binary on first launch. If the user sees "cannot be opened because the developer cannot be verified", run once:

``bash xattr -dr com.apple.quarantine ~/.hermes/bin/hermes-relay ``

Pin a version: HERMES_RELAY_VERSION=desktop-v0.3.0-alpha.1 curl -fsSL ... | sh.

Uninstall: rm ~/.hermes/bin/hermes-relay and remove the PATH line from the shell rc.

A3. npm / npx (any platform with Node ≥21)

Once we publish to npm (not yet — experimental phase), this will be:

npm install -g @hermes-relay/cli

For now, install from a clone:

git clone https://github.com/Codename-11/hermes-relay
cd hermes-relay/desktop
npm install
npm run build
npm link

The npm link step drops hermes-relay into your npm global bin directory. Add that to your PATH if it isn't already (npm config get prefix shows where).

B. Verify the install

Run a one-off --version check:

hermes-relay --version

Expect 0.3.0-alpha.18 or later (depending on which release is current).

If the command is not found:

• Windows: open a new PowerShell (PATH updates don't apply retroactively), or run $env:Path += ';C:\Users\<you>\.hermes\bin' temporarily.
• macOS / Linux: source the rc file (source ~/.zshrc) or open a new terminal.
• npm path missing: export PATH="$(npm config get prefix)/bin:$PATH", then add permanently.

C. Pair

On the relay host, mint a fresh pairing invite:

# On the host (SSH in first if remote)
hermes-pair --ttl 600

Or, from any Hermes chat session on the host: /hermes-relay-pair.

You'll get a Copy/paste pairing invite section with a URL shaped like hermes-relay://pair?payload=.... That invite carries the relay URL, one-shot relay code, API host, and endpoint candidates.

On this machine (your laptop), either paste that URL into Hermes Relay Desktop → Pair → Paste invite, or run:

hermes-relay pair --pair-qr 'hermes-relay://pair?payload=...' --grant-tools

The CLI probes the invite endpoints, picks the highest-priority reachable route, exchanges the embedded relay.code for a session token, stores it in ~/.hermes/remote-sessions.json, and prompts for desktop-tool consent when --grant-tools is present.

Manual code pairing is still available when you only have a code:

hermes-relay pair --remote ws://<host>:8767

The CLI prompts for the 6-character code and will:

1. Disable bracketed-paste mode during the prompt (so pasted codes aren't wrapped in \x1b[200~...).
2. Strip ANSI + control chars defensively, clean to A-Z0-9, clamp to 6 chars.
3. Echo → using code: F3W7EY as a sanity check.
4. Connect to the relay, exchange the code for a session token, persist to ~/.hermes/remote-sessions.json (mode 0600).

On success:

✓ Paired. Token stored in ~/.hermes/remote-sessions.json
  Server: 1.1.0
  Relay:  ws://<host>:8767
  Route:  lan

Subsequent hermes-relay invocations reuse the stored token — no re-pair needed.

D. First smoke — structured event chat

Quickest sanity check:

hermes-relay chat "what time is it?"

The CLI streams back the agent's reply. Stderr gets Connecting... / Connected via LAN (plain) — server 1.1.0; stdout gets the answer. Redirecting stdout to a file (... > out.txt) captures only the reply.

E. Full Hermes TUI — shell mode

For the complete local-Hermes experience (the Axiom-Labs banner, Victor, the Ink status bar, slash commands, everything):

hermes-relay

(Bare invocation is shorthand for hermes-relay shell.)

The CLI:

1. Connects over WSS.
2. Prints Connected via LAN (plain) — server 1.1.0.
3. Prompts for one-time local-tool consent (see §F).
4. Attaches to the relay's terminal channel, which spawns (or re-attaches) a tmux session on the host.
5. Sends clear; exec hermes\n after a 350 ms settle — tmux's login shell replaces itself with hermes, which renders its native Ink TUI straight through to your terminal.

Escape keys:

• Ctrl+A . — detach (tmux preserved on the host — next hermes-relay re-attaches with full state)
• Ctrl+A k — kill the tmux session (destructive; fresh hermes on next run)
• Ctrl+A Ctrl+A — forward a literal Ctrl+A (for nested tmux)
• Ctrl+C — passes through to hermes (interrupts the agent, not the client)

F. Desktop tool consent — one-time per relay URL

On first shell or chat with tools enabled, the CLI shows:

Desktop tools are about to be exposed to the remote Hermes agent.
The agent can read/write files, run shell commands, and search your filesystem.
This is AGENT-CONTROLLED access. Only use with trusted Hermes installs.
Type 'yes' to enable, or rerun with --no-tools to disable.
> _

Only yes (case-insensitive) enables. Anything else (y, no, Enter, Ctrl+C) denies. Consent is stored per-URL in ~/.hermes/remote-sessions.json as toolsConsented: true and sticks across sessions.

Kill-switches:

• --no-tools on any subcommand suppresses the router entirely — the agent sees "no desktop client for tool X".
• hermes-relay pair --reset-pin (coming) wipes consent + cert pin; re-pair re-prompts.

G. Verify end-to-end tool routing

Inside hermes-relay shell, at the agent prompt:

use desktop_terminal to run "hostname" and show me the raw JSON output

Expect the agent to render:

{
  "stdout": "<YOUR-LOCAL-HOSTNAME>\r\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 70
}

The key signal: stdout contains your local hostname, not the server's. That proves the call routed from hermes → relay → WSS → this machine → shell exec → response back. If the agent instead sees the server's hostname (e.g., hermes-host), the tool is running on the server — check consent and /desktop/_ping from the host:

# On the host
curl -s "http://127.0.0.1:8767/desktop/_ping?tool=desktop_terminal"

{"connected": true, "advertised_tools": [...]} means routing works; the issue is upstream in Hermes. {"connected": false} means the client isn't attached or consent was denied.

Troubleshooting

hermes-relay: command not found

Your shell hasn't picked up the PATH change. Options:

• Windows: open a new terminal window.
• macOS/Linux: source ~/.bashrc (or ~/.zshrc) in the current session.
• Or run with the full path one time: ~/.hermes/bin/hermes-relay --version.

Node version 20 too old. Need >=21

You're on the npm/source install path with old Node. Either:

• Upgrade Node: https://nodejs.org → LTS or current, whichever is ≥21.
• Switch to the binary install (A1 / A2) which needs no Node.

auth timed out after 15000ms

The relay subprocess takes 15–30 s on first attach (hermes agent full-init). Bump the timeout for slow first connects:

HERMES_RELAY_AUTH_TIMEOUT_MS=30000 hermes-relay shell