Hermes Local Device Setup

Run Hermes on a separate local device instead of the daily machine. This workflow assumes the main machine and target Ubuntu or homelab device are on the same network. The main machine connects over SSH, while Hermes runs on the controlled target device.

Set connection variables

Set these variables on the main machine. Use the remote username and the local IP address or hostname of the device where Hermes will run.

export LAB_USER="your_remote_user"
export LAB_HOST="your_lab_ip_or_hostname"
export LAB_SSH="$LAB_USER@$LAB_HOST"

Update the target device

SSH into the target device and update the base system before installing Hermes.

ssh $LAB_SSH

sudo apt update
sudo apt upgrade

Reboot if kernel, systemd, libc, GPU, or browser-related packages changed. SSH back in after the reboot.

sudo reboot

ssh $LAB_SSH

Install base dependencies

Install the basic tools Hermes needs on the target device.

sudo apt update
sudo apt install -y curl git ca-certificates tmux nodejs npm

Install browser automation dependencies

Install Chromium dependencies for browser automation on the target device.

sudo npx playwright install-deps chromium

Install Hermes

Run the Hermes installer on the target device.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Add ~/.local/bin to PATH, reload the shell, then check the Hermes install.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

hermes doctor

Start Hermes

Command	Use
hermes	Start classic CLI mode
hermes --tui	Start TUI mode
hermes -c	Resume the latest session
hermes --tui -c	Resume the latest session in TUI mode

Classic CLI mode is usually better for copy and paste.
TUI mode is useful if classic CLI has terminal display issues.

Stop a frozen Hermes process

First try Ctrl+C in the active SSH terminal. If Hermes does not respond, open another SSH terminal to the target device and kill the process.

pkill -f hermes

hermes

Manage Hermes sessions

# List sessions
hermes sessions list

# List more sessions
hermes sessions list --limit 50

# Resume a session by title or ID
hermes --resume "SESSION_TITLE_OR_ID"

# Short form
hermes -r "SESSION_TITLE_OR_ID"

# Rename a session
hermes sessions rename SESSION_ID "new-session-title"

# Delete a session
hermes sessions delete SESSION_ID

# Delete without confirmation
hermes sessions delete SESSION_ID --yes

Expose a local dev site to Hermes

Use an SSH reverse tunnel when a local app is running on the main machine and Hermes needs to inspect it from the target device.

ssh -N -R 3000:localhost:3000 $LAB_SSH

Hermes running on the target device can then inspect the local app through this address.

http://127.0.0.1:3000

File locations

Hermes runs on the target Ubuntu or homelab device.
The main machine connects to the target device over SSH.
Use the target device terminal for Hermes sessions.