Hermes Link

Hermes Link is a secure companion service for hermes-agent. It provides the hermeslink CLI and a local service layer that lets HermesPilot App connect to a Hermes Agent running on the user's own computer or server.

Requirements

• Node.js 20.0.0 or newer
• A local hermes-agent setup on the same machine. HermesPilot Link uses the Hermes Agent API Server on 127.0.0.1:8642.

Install

npm install -g @hermespilot/link

The package installs the hermeslink command. It does not start the service automatically during installation.

If your shell cannot find hermeslink right after install, your npm global bin directory is probably not on PATH, or npm was run from a different environment than your shell. You can run the install diagnostic without relying on PATH:

npx --yes @hermespilot/link doctor --install

On Unix-like systems, the most common temporary fix is:

export PATH="$(npm prefix -g)/bin:$PATH"

You can also invoke the installed binary directly with $(npm prefix -g)/bin/hermeslink. In WSL, if npm prefix -g points under /mnt/c/..., you are probably using Windows Node/npm from inside WSL. Install Linux Node.js inside WSL, or run both Hermes Agent and Hermes Link on the Windows host instead of mixing the two environments.

Common commands

hermeslink --version
hermeslink status
hermeslink pair
hermeslink start
hermeslink stop
hermeslink autostart on
hermeslink autostart off
hermeslink doctor
hermeslink logs
hermeslink logs -f
hermeslink logs -n 100
hermeslink logs flush

hermeslink pair requires HermesPilot Server and Relay to be available. The terminal side does not ask for a HermesPilot account; the App must be logged in before it scans or claims a pairing session.

After the first successful QR claim, hermeslink pair starts Hermes Link in the background and enables boot autostart. Pairing additional devices does not rewrite boot autostart settings; use hermeslink autostart on or hermeslink autostart off to manage that setting explicitly. Boot autostart does not configure launchd/systemd restart policies; if the user stops Hermes Link, the operating system should not automatically relaunch it until the next login/boot autostart cycle.

When the Hermes API Server is needed, Link prepares its configuration and waits for an existing Gateway. Automatic recovery never interrupts a live process or rotates credentials after a 401. A stopped official systemd/launchd service is started through Hermes CLI; custom or ambiguous service definitions require the user to manage them. Without an installed service or a live process, Link may start a detached Gateway. Link never invokes --replace. Reloads require a responding API and verified process identity; they use the installed service or gracefully stop only the exact registered Link-owned PID before starting again. If startup cannot be distinguished from failure, Link returns a diagnostic instead of interrupting it. If Hermes Agent is missing or too old to provide /v1/responses, Link returns an actionable error and the user should run:

hermes update
hermes gateway run

If Hermes Agent is configured through ~/.hermes/.env, Link follows the same API_SERVER_* overrides when calling the local API Server.

CLI output follows the current system language when it is Chinese or English. You can override it for a single command with HERMESLINK_LANG=zh-CN or HERMESLINK_LANG=en.

Set HERMESLINK_LOG_LEVEL=warn to suppress debug and info logs in published builds; warn is the default. You can also persist it with hermeslink config set log-level warn. A running daemon keeps the log write level it started with; run hermeslink restart after changing log-level if you need the write level to take effect immediately. hermeslink logs filters displayed lines by the current configured level by default, and --level debug can be used to inspect lower-level history.

By default Link fetches the shared model capability catalog from the Console-managed R2 object at https://hs.clawpilot.me/model-capabilities/catalog.json. Set MODEL_CATALOG_URL only when you need to override that URL for local development or emergency migration. Link refreshes it quietly on service startup and near local midnight; if the URL is unavailable, it uses the bundled model-capabilities/catalog.json template as a fallback. See .env.example for the local development shape.

Runtime data

Hermes Link keeps its local identity and runtime state under:

~/.hermeslink/

Uninstalling the npm package does not remove this directory, so the same Link ID can be reused after reinstalling.

Service logs are written as rotated JSONL files under ~/.hermeslink/logs/hermeslink.log. hermeslink logs prints the relevant paths, hermeslink logs -n 100 prints recent lines, and hermeslink logs -f follows service and daemon logs without depending on a platform-specific tail command. Use hermeslink logs --error -n 20, hermeslink logs --warn -n 50, or hermeslink logs --level debug to choose the displayed severity. hermeslink logs flush clears active and rotated service/daemon logs; use hermeslink logs flush --all to include Gateway logs. A paired App can read the same service log stream through GET /api/v1/logs using the normal Link access token.

Hermes Link also maintains a small Hermes skill under ~/.hermeslink/hermes-skills/hermes-link/SKILL.md. On start, successful pairing, and Profile creation, Link registers ~/.hermeslink/hermes-skills in each existing Hermes Profile's skills.external_dirs, so Hermes can understand what Hermes Link is and help diagnose HermesPilot mobile connection issues.