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 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 App sends a message, Hermes Link prepares ~/.hermes/config.yaml for the Hermes API Server and attempts to start Hermes Gateway with hermes gateway run --replace if the API Server is not already reachable. If Hermes Agent is missing or too old to provide /v1/runs, 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.

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. A paired App can read the same service log stream through GET /api/v1/logs using the normal Link access token.