@hermespilot/link
v1.4.0
Published
Hermes Link companion service and CLI for connecting hermes-agent through HermesPilot
Maintainers
Readme
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
- Hermes Agent 0.21.5 or newer on the same machine, with working shared Dashboard and Profile-scoped APIs. Link discovers and reuses the official local backend; it does not start an isolated backend per Profile. The separate API Server (usually
127.0.0.1:8642) remains in use for some management features.
Chats held by another client are routed to their existing backend when it supports shared access. A private third-party backend must release its chat first. Stopping or restarting Link does not stop a shared Dashboard. Upgrading Link cleans verified legacy Link-owned processes without migrating chat history, Profiles or pairing credentials.
Install
npm install -g @hermespilot/linkThe package installs the hermeslink command. It does not start the service automatically during installation. npm installation itself only checks Node.js; Hermes Link checks that Hermes Agent is 0.21.5 or newer before start, restart, daemon startup, and pairing. A failed restart compatibility check happens before the old Link daemon is stopped.
Use the standard installation command across supported Node.js versions. Keep optional dependencies and their installation scripts enabled: Node.js 20/22/23 use better-sqlite3, while Node.js 24+ default to the built-in SQLite driver and retain better-sqlite3 as a fallback. Skipping optional dependencies can break an older Node.js installation or remove that fallback after a Node version change.
The upstream prebuild-install dependency currently emits a deprecation warning; this warning alone does not mean installation failed. An npm allow-scripts warning means an installation script needs approval under that npm configuration. Link's preinstall only rejects unsupported Node.js versions; better-sqlite3 needs its own install script to prepare the native driver. If npm reports blocked scripts, follow its package-specific approval instructions and reinstall; allowing Link's script alone does not enable the SQLite driver's script.
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 --installOn 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 status --verbose
hermeslink login
hermeslink pair
hermeslink start
hermeslink stop
hermeslink autostart on
hermeslink autostart off
hermeslink doctor
hermeslink doctor --verbose
hermeslink logs
hermeslink logs -f
hermeslink logs -n 100
hermeslink logs flushhermeslink 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.
hermeslink status shows a short summary of the service, pairing, autostart, chat connection, local storage and remote connection. Items needing attention include next steps. Use status --verbose for paths, PID, Link ID, ports, SQLite/Node versions and detailed connection state. status --json retains the machine-readable fields. An idle chat connection connects automatically when needed; this status does not verify that the Hermes host is available. Use hermeslink doctor to check chat readiness.
hermeslink doctor shows a short health summary and ensures the HermesPilot Link plugin is installed and enabled, including recovery from an earlier automatic disable by Link. Explicit user disables are preserved. Doctor does not restart a running Hermes host; when the plugin needs loading, it asks you to restart the host after tasks finish. Use --verbose for paths, IDs, ports, driver details and diagnostic errors, or --install for installation/PATH checks without plugin changes. Installation checks follow the running Link package's global installation directory when available, even if the current npm prefix has changed.
Doctor diagnoses existing services without starting or restarting Hermes, creating a Link identity, or changing Profile/plugin configuration. Its JSON-RPC check runs in the daemon environment when the local diagnostic endpoint is available; otherwise it explicitly reports a CLI self-check. Profile API checks follow the same independent-port or shared /p/<profile>/v1 route as ordinary requests. Verbose plugin results describe configuration and files. An idle status reports Link's cached connection state and does not establish whether the Hermes host is running. Invalid published Python runtime commands include a specific parse reason and bounded, redacted launcher output in the local log.
Version checks use the selected Hermes installation's official Python runtime and version formatter with update checks disabled. This keeps a slow update lookup from buffering the version banner past Link's timeout. Older installations without that formatter retain the CLI fallback; a malformed published runtime command remains an error. Reading a version does not save a launcher path; successful startup preflight does. Version probe timeouts have their own diagnostic code.
If Hermes Dashboard login protection is enabled, run hermeslink login on the same computer as Hermes Link. Link discovers or prepares the shared Dashboard, opens Hermes' official browser login flow, and stores its access and refresh credentials in ~/.hermeslink/hermes-dashboard-auth.json (0600). It never stores the Dashboard password. Credentials are bound to the verified Hermes data folder, automatically refreshed when needed, and reused across Dashboard restarts or port changes when the auth provider still accepts them. Each chat connection obtains a fresh single-use WebSocket ticket. The browser callback is local to that computer, so opening the URL on a phone cannot complete the login for Link. A Dashboard that does not advertise native_pkce needs an Hermes update before this flow is available; expired or revoked refresh credentials require running hermeslink login again.
Link verifies the newly authorized Dashboard before replacing saved credentials; a cancelled login or failed verification preserves the previous login. Password-only login uses the local Dashboard and does not depend on its public address. Once a refresh credential is explicitly rejected, that Link process stops submitting it to the same backend generation; a new login or backend generation permits verification again. Shared-backend reconnection verifies an existing replacement process and does not restart Hermes or resend chat messages.
When Hermes has a public Dashboard URL configured, OAuth browser sign-in uses that URL so the callback keeps the same browser origin. Password-only sign-in stays local, even when the public site is offline. Link continues exchanging credentials and making ordinary requests through the verified local Dashboard.
After the first successful QR claim, hermeslink pair starts Hermes Link in the background and enables autostart. Pairing additional devices preserves the user's setting; use hermeslink autostart on or hermeslink autostart off to manage it. Successful start and restart commands also maintain existing enabled autostart settings, including after an upgrade. Disabling autostart does not stop the running Link service. Autostart does not configure launchd/systemd restart policies; a deliberate stop lasts until the next login/boot cycle.
System tasks invoke a fixed Shell or PowerShell launcher under ~/.hermeslink/autostart/ (or HERMESLINK_HOME). The launcher records only verified aliases of the selected Node installation and the selected Link package directory. It checks Node 20+ and the package before starting the supervisor; it never searches another npm installation, sources shell profiles, or downloads a replacement runtime. Homebrew stable symlinks survive ordinary Node upgrades. Version managers without a verified stable alias stay bound to their selected runtime; if that runtime or its Link package is removed, repair the installation and run hermeslink autostart on again.
macOS LaunchAgents and Windows user-scoped scheduled tasks run after user sign-in. Windows tasks allow battery operation and have no execution time limit; Startup is a fallback when task registration is unavailable. Linux prefers a user systemd service. It starts without sign-in only when the administrator has enabled user lingering; Link does not change that policy. XDG autostart is a fallback only in a detected graphical session. WSL and containers additionally need their host to start the environment. Headless Linux without user systemd needs a host-managed service.
hermeslink autostart status (also --json) reports configuration, system registration, runtime/package readiness, trigger, and the last system task result. status --verbose and doctor --install include these details without changing settings; default status summarizes autostart and keeps issues visible. WSL/container host startup reminders appear only in those environments. For early startup failures, run hermeslink logs --daemon -n 50; this includes logs/autostart.log. To refresh an old configuration without rebooting, run hermeslink autostart on. Updating registration does not terminate an active supervisor; a running macOS job reads the new definition on the next login.
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 runIf Hermes Agent is configured through ~/.hermes/.env, Link follows the same API_SERVER_* overrides when calling the local API Server.
When upgrading from a legacy Link version, Link cleans up only backend processes whose registration, command, and process identity it can verify. Dead registrations are removed; registrations with a proven reused PID are audited and removed without signalling the current process. Unreadable registrations, uncertain ownership, or failed cleanup are preserved and reported as warnings in Link logs and upgrade output, rather than blocking the upgrade. Link never kills unverified processes by name.
A successful App-triggered upgrade confirms the running Link version and Link identity, not that the Hermes chat backend is ready. A failure to stop the Link daemon, start the replacement, or verify it still fails the upgrade. If chat remains unavailable after a cleanup warning, check hermeslink logs and the reported Hermes backend conflict before stopping any process manually. This behavior uses the existing update states and log output, so it does not require an App upgrade.
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.
The default local log level is info, recording info, warn, and error. Existing explicit settings are preserved. Set HERMESLINK_LOG_LEVEL=warn or persist hermeslink config set log-level warn to suppress info. A running daemon keeps the configured level it started with, so run hermeslink restart after changing log-level. Console administrators can temporarily enable debug for 15 minutes without restarting, then it automatically returns to the original level. This changes local recording only and never triggers an upload. hermeslink logs filters displayed lines by the current configured level by default, and --level debug can inspect lower-level history.
Console's Link list provides 查看日志 for manual reads of hermeslink.log and its rotations. Queries use the existing Relay control channel, support exact levels and Shanghai date/time ranges, and return at most 100 entries and 128 KiB per request. Only the administrator's current page holds returned logs. Server and Relay do not store their contents. Link must be online and support link_log_query_v1. Hermes and daemon text logs are excluded. Rotation can remove older records, and previously unrecorded info or debug entries cannot be recovered.
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.
