Hermes Link Quick Start

Hermes Link is the local companion service that lets HermesPilot App securely connect to the Hermes Agent running on your own computer. After pairing, the App can continue chats, send files, use voice input, manage Profiles, view devices, check logs, inspect usage, and see update status.

Check where you install it

Hermes Link and Hermes Agent must be installed and run inside the same system environment.

Do not install Link on the host while Hermes Agent runs in Docker, WSL, or another virtual environment. Do not install Link in WSL while Hermes Agent runs on the Windows host. In those split setups, Link usually cannot read the same Hermes config, .env, Profiles, or local 127.0.0.1 API, so the App may fail to connect or send messages.

Need public direct access first?

If you want your phone to reach Hermes Link directly over the internet, jump to Public Direct Access.

Before You Start

• Hermes Agent is installed and works in the current system environment.
• The computer can reach HermesPilot Server and Relay for pairing and fallback routes.
• HermesPilot App is signed in.
• Node.js is 20.0.0 or newer.

Step 1: Install Link

On the computer that hosts Hermes, run the recommended command for your system.

macOS / Linux / WSL

curl -fsSL https://hs.clawpilot.me/install/install.sh | bash

If this machine does not have curl but has wget, use:

wget -qO- https://hs.clawpilot.me/install/install.sh | bash

Windows PowerShell

irm https://hs.clawpilot.me/install/install.ps1 | iex

The install script reads the current public Link version from HermesPilot Server and installs that version. If the Server check is unavailable, it falls back to the latest npm package. After installing, the script runs diagnostics and tries to restart Hermes Link so the background service switches to the new version.

If you prefer manual npm installation, expand this npm command

npm install -g @hermespilot/link

After installation, you will have a new hermeslink command.

If the install succeeds but hermeslink doctor says command not found, Link is usually installed but npm's global bin directory is not on your current shell PATH. The installer will try to explain the exact cause; you can also run this PATH-independent diagnostic first:

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

On macOS, Linux, WSL, and other Unix-like environments, the common temporary fix is:

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

After confirming it works, add the same line to ~/.zshrc, ~/.bashrc, or the shell profile you actually use. On Windows, add the directory printed by npm prefix -g to your user Path, then open a new terminal.

Do not mix Windows npm inside WSL

If npm prefix -g inside WSL points under /mnt/c/..., you are probably calling Windows Node/npm from the WSL shell. That installs the hermeslink shim on the Windows side, may not make it visible to WSL, and can put Link and Hermes Agent in different system environments. Install Linux Node.js inside WSL, or run both Hermes Agent and Hermes Link on the Windows host.

Step 2: Generate the pairing QR code

Then run:

hermeslink pair

pair runs a preflight check first: Link must be able to access the current Hermes home, config.yaml, .env, and the Hermes API Server. When the check passes, the terminal shows a QR code and a manual pairing code.

The QR code is valid for 10 minutes by default and expires immediately after a successful claim. After the first successful pairing, Link starts in the background and enables boot autostart.

Step 3: Scan it in the App

Open HermesPilot App, go to the Hermes Link connection screen, and scan the QR code from the terminal.

After pairing succeeds, the App saves this Link. The App prefers LAN first, then can fall back to public direct or Relay routes when LAN is unavailable.

Public Direct Access

If your phone is often away from the same LAN and you want a more direct route than Relay, you can prepare a public entry point for Hermes Link.

Hermes Link listens on port 52379 by default. Whether you use home broadband or a cloud server, external traffic must ultimately reach port 52379 on the machine that runs Link.

• Home broadband / consumer router: Configure port forwarding so WAN port 52379 forwards to LAN port 52379 on the computer running Hermes Link. It is a good idea to keep that computer on a fixed LAN IP so the forwarding rule does not break after DHCP changes.
• Cloud server / remote host: Check both the cloud security group and the operating system firewall, and make sure inbound access to 52379 is allowed in both places. Many "the port is open but it still does not work" cases come from opening only one layer.

For safety, do not leave an unprotected 52379 port exposed to the public internet long-term. A better setup is to add TLS, access control, or a VPN / Tailscale / WireGuard layer first, then save your public domain, fixed public IP, or VPN address in HermesPilot App as the custom address.

When the public endpoint is ready, use Manual connect in the App: enter the pairing code from hermeslink pair, then save your public address as the custom address. The App will prefer that custom route afterward.

Common commands

hermeslink status
hermeslink start
hermeslink stop
hermeslink autostart on
hermeslink autostart off
hermeslink doctor
hermeslink logs
hermeslink logs -n 100
hermeslink logs -f
hermeslink logs --error -n 20
hermeslink logs --warn -n 50
hermeslink logs --all --level debug -f
hermeslink logs flush
hermeslink logs flush --all
hermeslink config set log-level <warn|error|info|debug>

Common uses:

• Check Link and Hermes status: hermeslink status
• Start the background service: hermeslink start
• Stop the background service: hermeslink stop
• Enable or disable boot autostart: hermeslink autostart on/off
• Print log file paths: hermeslink logs
• Print recent logs: hermeslink logs -n 100
• Follow logs: hermeslink logs -f
• Filter by severity: hermeslink logs --error -n 20, hermeslink logs --warn -n 50; short forms -e / -w also work
• Read all sources while troubleshooting: hermeslink logs --all --level debug -f
• Clear Link logs: hermeslink logs flush clears service and daemon logs; use hermeslink logs flush --all to include Gateway logs
• Change the log level: hermeslink config set log-level <warn|error|info|debug>; use info for normal use, warn or error for less noise, and debug when troubleshooting pairing, connectivity, or request forwarding. Run hermeslink restart afterward if you want the running daemon to apply the new write level immediately

What You Can Do After Pairing

• Continue conversations with your local Hermes Agent and receive streaming replies.
• Send images, PDFs, audio, and other files from your phone to Hermes.
• Use voice input to hand tasks to Hermes.
• Review Link, Gateway, Server, devices, logs, and usage status.
• Manage Hermes Profiles, default models, cron jobs, skills, tool permissions, and memory settings.
• Check update status for Hermes Agent and Hermes Link.

WSL, Docker, and Virtualized Environments

If you use WSL, Docker, or a virtual machine, the core rule still applies: Link and Hermes Agent must run in the same system environment.

Docker

When Hermes Agent runs in Docker while Link runs on the host, container 127.0.0.1, filesystem paths, and Hermes home are not the same as the host environment, so Link can easily read the wrong config or fail to reach Gateway.

If you insist on Docker, run Link in the same container environment and make sure the Link port is exposed to the App. This varies by setup, so native installation is usually simpler.

Windows WSL

WSL uses NAT networking by default. According to Microsoft WSL networking documentation, Windows can usually reach Linux apps through localhost. LAN devices do not automatically get access to services inside WSL, so you typically need port forwarding, firewall rules, or the newer mirrored networking mode.

If Link runs inside WSL, a phone on the same Wi-Fi may still fail to reach WSL port 52379. Prefer these options:

1. If possible, install both Hermes Agent and Link natively on the Windows host.
2. If they must run inside WSL, prefer the Relay route.
3. If you want LAN direct access to Link inside WSL, update to a Windows/WSL version that supports mirrored networking, then create or edit %UserProfile%\.wslconfig:

[wsl2]
networkingMode=mirrored

Save the file, then run in PowerShell:

wsl --shutdown

Start WSL again, then run:

hermeslink config set lan-host <Windows LAN IP>
hermeslink restart

If mirrored networking is not available, you can use Windows netsh interface portproxy and allow the port through Windows Firewall. This requires maintaining WSL's dynamic IP, which may change after WSL restarts, so it is usually less stable than Relay.

References:

• Microsoft WSL Networking
• Microsoft WSL advanced settings configuration

If the First Connection Fails

• Run hermeslink status and confirm Link is still running.
• Run hermeslink doctor and confirm Hermes Gateway/API Server is available.
• Confirm the App and Link use the same HermesPilot Server.
• Confirm Link and Hermes Agent are in the same system environment, with no host/Docker/WSL split.
• If the network address changed, run hermeslink config set lan-host <computer IP reachable from phone>, then pair again or restart Link.
• If LAN stays unreachable, use the Relay route first.