Remote Access to Hermes Agent

Remote Access to Hermes Agent — Deploy the Desktop App and Connect to a Remote Backend

Agent Daily · Step-by-Step Guide · June 2026
Remote Access to Hermes Agent — architecture diagram showing laptop connecting through network to remote server
📖 Tutorial 🏷 Hermes Agent · Remote Access · Desktop App · Tailscale

📋 Overview

Hermes Agent is designed to live wherever makes sense — a $5 VPS, a home server, a beefy GPU machine, or a cloud VM you never SSH into yourself. The Desktop App (available on macOS, Windows, and Linux) can connect to a remote Hermes backend, giving you a native, polished UI on your laptop while all the heavy lifting — tool execution, cron jobs, skills, memory — runs on the remote machine.

This guide walks you through the complete setup: installing Hermes on a remote server, configuring it to accept connections, securing the channel with Tailscale (or SSH tunnels), and connecting the Desktop App from your local machine. By the end, you'll have a setup where you can chat with your remote Hermes from anywhere, with full access to all its tools and capabilities.

💻
Your Laptop
Desktop App
→
🔒
Tailscale / SSH
Encrypted tunnel
→
🖥️
Remote Server
hermes dashboard --tui

1 The Big Picture

The Hermes architecture separates the agent backend (the Python process that runs conversations, executes tools, manages memory and skills) from the frontend (the UI you interact with). All frontends — CLI, TUI, Desktop App, Web Dashboard, Telegram, Discord — talk to the same backend and share state.

For remote access, the Desktop App connects to the backend's Dashboard API — a web server that exposes:

  • /api/status — health check and backend info
  • /api/ws — WebSocket for real-time chat
  • /api/pty — pseudo-terminal WebSocket for the embedded TUI

The connection is authenticated via a session token that you pin on the backend and paste into the Desktop App. The backend must be started with --tui to enable the chat WebSockets.

💡 Key insight: You can start a session on your laptop's Desktop App, close it, continue via Telegram on your phone, and resume later from the CLI on the server itself. All frontends share sessions, skills, and memory.

2 Prerequisites

Remote Machine (Server / VM)

  • OS: Linux (Ubuntu 22.04+, Debian 12+, or any modern distro), macOS, or WSL2
  • RAM: 2 GB minimum (4 GB+ recommended for heavy tool use)
  • Disk: 5 GB free space for Hermes + dependencies
  • Network: Outbound internet access (for API calls to LLM providers)
  • Shell: bash

Local Machine (Laptop)

  • OS: macOS, Windows, or Linux
  • Network: Ability to reach the remote machine (VPN, SSH, or direct network)

Accounts & Keys

  • An LLM provider API key (OpenRouter, Anthropic, OpenAI, etc.) — you'll configure this on the remote machine
  • A Tailscale account (free for personal use — recommended for secure access)

3 Install Hermes on the Remote Machine

SSH into your remote server and run the one-line installer:

# SSH into your remote machine ssh user@your-server-ip # Install Hermes Agent curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installer handles everything: Python 3.11, Node.js 22, uv, ripgrep, ffmpeg, and the Hermes source code. It clones the repo into ~/.hermes/hermes-agent/, creates a virtual environment, and adds hermes to your PATH.

After installation, run the setup wizard:

# Interactive setup — configure your model provider, API keys, etc. hermes setup # Or use Nous Portal for one-click setup (model + tools in one OAuth) hermes setup --portal

Verify the installation:

# Check everything is working hermes doctor # Quick test — ask a one-shot question hermes chat -q "What is 2+2?"
✅ Tip: If you're on a headless server with no browser, use hermes setup and manually paste API keys. The --portal OAuth flow needs a browser redirect.

4 Configure the Remote Backend for Desktop Connection

The Desktop App connects to the Hermes Dashboard — a web server that exposes the agent's API. You need to:

Step 4.1 — Create a Stable Session Token

By default, Hermes generates a random token on every boot and injects it directly into the served HTML — there's nothing to copy. For remote connections, you pin a token yourself:

# Generate a cryptographically random token TOKEN=$(openssl rand -base64 32) # Save it to the Hermes secrets file echo "HERMES_DASHBOARD_SESSION_TOKEN=$TOKEN" >> ~/.hermes/.env # Secure the file chmod 600 ~/.hermes/.env # Print the token — copy this for the Desktop App echo "Your session token: $TOKEN"
⚠️ Keep this token safe. Anyone with it can run commands, read your API keys, and interact with your agent. Treat it like a password.

Step 4.2 — Start the Dashboard with Required Flags

Three flags are mandatory for remote Desktop App connections:

hermes dashboard --tui --no-open --insecure --host 0.0.0.0 --port 9119
FlagWhy It's Needed
--tuiEnables the /api/ws and /api/pty WebSockets the Desktop App uses for chat. Without it, the app connects but chat stays dead.
--no-openPrevents trying to open a browser (headless server has none)
--insecureRequired for non-loopback bind. Without it, Hermes enables the OAuth gate which ignores session tokens entirely
--host 0.0.0.0Listen on all interfaces (or use your Tailscale IP for tighter security)
--port 9119The port the Desktop App will connect to (default: 9119)
⚠️ --insecure exposes a port that can run agent commands and read your .env (API keys, secrets). Never expose it to the open internet. Always use a VPN (Tailscale) or SSH tunnel.

5 Secure the Connection with Tailscale VPN

Tailscale creates a secure, encrypted mesh VPN between your devices. It's free for personal use (up to 100 devices) and takes under 5 minutes to set up. This is the recommended way to secure your Hermes remote connection.

Step 5.1 — Install Tailscale on Both Machines

# On the REMOTE server (Linux) curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up # On your LOCAL laptop # macOS: download from https://tailscale.com/download # Windows: download from https://tailscale.com/download # Linux: curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up

After logging in on both machines, they'll be on the same private network (your "tailnet"). You can find each machine's Tailscale IP with:

tailscale ip -4 # Example output: 100.64.0.5

Step 5.2 — Bind Hermes to the Tailscale IP

Instead of binding to 0.0.0.0 (all interfaces), bind specifically to the Tailscale IP so only your tailnet can reach it:

# Get the server's Tailscale IP TS_IP=$(tailscale ip -4) # Start the dashboard bound to Tailscale only hermes dashboard --tui --no-open --insecure --host $TS_IP --port 9119
✅ This is the safest approach: even if someone scans your public IP, port 9119 won't respond. Only devices on your Tailscale network can reach it.

Step 5.3 — Tailscale MagicDNS (Optional)

Tailscale's MagicDNS lets you use friendly hostnames instead of IPs:

# Instead of http://100.64.0.5:9119, use: http://my-server.tail12345.ts.net:9119

6 Run as a Persistent systemd Service

You want the dashboard to survive reboots, SSH logouts, and crashes. The cleanest way is a systemd user service.

Step 6.1 — Create the Service File

mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/hermes-dashboard.service << 'EOF' [Unit] Description=Hermes Agent Dashboard (Remote Backend) After=network-online.target Wants=network-online.target [Service] Type=simple EnvironmentFile=%h/.hermes/.env ExecStart=%h/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main dashboard --tui --no-open --insecure --host 0.0.0.0 --port 9119 Restart=on-failure RestartSec=10 WorkingDirectory=%h [Install] WantedBy=default.target EOF

Step 6.2 — Enable and Start

# Enable linger so services run after SSH logout sudo loginctl enable-linger $USER # Reload systemd, enable, and start systemctl --user daemon-reload systemctl --user enable hermes-dashboard.service systemctl --user start hermes-dashboard.service # Check status systemctl --user status hermes-dashboard.service
💡 Important: loginctl enable-linger is critical — without it, your user services die when you close the SSH session. This is the #1 reason people's gateway/dashboard services mysteriously stop.

Step 6.3 — View Logs

# Follow live logs journalctl --user -u hermes-dashboard -f # Last 50 lines journalctl --user -u hermes-dashboard -n 50

7 Install the Desktop App on Your Laptop

The Hermes Desktop App is a native Electron application available for macOS, Windows, and Linux.

Option A — Download the Installer (Recommended)

Download the latest installer from hermes-agent.nousresearch.com or from GitHub Releases.

  • macOS: DMG (signed and notarized)
  • Windows: NSIS installer or MSI
  • Linux: AppImage, .deb, or .rpm

Option B — CLI Install with Desktop

If you already have Hermes CLI installed locally:

# Add the desktop app to an existing Hermes installation hermes desktop # Or include desktop during a fresh install curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --include-desktop
✅ Note: When using the Desktop App in remote mode, you don't need Hermes CLI installed locally at all. The app ships its own backend resolution and can work purely as a remote client.

8 Connect the Desktop App to Your Remote Backend

This is the moment everything comes together.

Step 8.1 — Open Settings

In the Desktop App, navigate to Settings → Gateway → Remote gateway.

Step 8.2 — Enter Connection Details

  • Remote URL: http://<tailscale-ip>:9119 (or http://my-server.tail12345.ts.net:9119 if using MagicDNS)
  • Session token: paste the token you generated in Step 4.1

Step 8.3 — Test and Connect

  1. Click "Test remote" — this verifies the backend is reachable and the token is accepted
  2. If the test passes, click "Save and reconnect"
  3. The Desktop App switches to the remote backend — you're now chatting with your remote Hermes
💡 The token is stored encrypted in the app's local config. On subsequent launches, you don't need to re-enter it. Leave the token field blank when editing to keep the saved one.

Alternative: Environment Variables

You can also configure the connection without the UI:

# Set both variables (they must be set together) export HERMES_DESKTOP_REMOTE_URL="http://100.64.0.5:9119" export HERMES_DESKTOP_REMOTE_TOKEN="your-token-here" # Launch the desktop app hermes desktop

9 Alternative: SSH Tunnel (No VPN Required)

If you don't want to use Tailscale, you can create an SSH tunnel to forward the dashboard port to your local machine. This works with any SSH access and requires no additional software.

Step 9.1 — Start the Dashboard on Localhost Only

On the remote server, bind to 127.0.0.1 instead of 0.0.0.0:

# On the REMOTE server — bind to localhost only hermes dashboard --tui --no-open --insecure --host 127.0.0.1 --port 9119

Step 9.2 — Create the SSH Tunnel

On your local machine, forward the remote port to a local port:

# Forward remote port 9119 to local port 9119 ssh -N -L 9119:127.0.0.1:9119 user@your-server-ip
FlagMeaning
-NDon't execute a remote command (tunnel only)
-L 9119:127.0.0.1:9119Forward local:9119 → remote:127.0.0.1:9119

Step 9.3 — Connect the Desktop App

In the Desktop App settings, use:

  • Remote URL: http://localhost:9119
  • Session token: same token from Step 4.1
✅ Advantage: SSH tunnels require no extra software and encrypt everything through SSH. Disadvantage: you must keep the tunnel open (consider using autossh for automatic reconnection).

Auto-Reconnecting Tunnel with autossh

# Install autossh sudo apt install autossh # Debian/Ubuntu brew install autossh # macOS # Auto-reconnecting tunnel autossh -M 0 -N -L 9119:127.0.0.1:9119 user@your-server-ip

10 Alternative: Web Dashboard (Browser-Only)

If you don't want to install the Desktop App, you can access the same interface through a web browser. The Hermes Web Dashboard serves the same agent experience as a web page.

Once the dashboard is running on the remote (Steps 3–6), simply open your browser and navigate to:

http://<tailscale-ip>:9119

The web dashboard provides:

  • Chat tab — embedded TUI with full agent capabilities (requires --tui flag)
  • Admin panel — manage config, sessions, cron jobs, skills, and gateway channels
  • Settings — modify providers, models, and tools from the browser
FeatureDesktop AppWeb Dashboard
Multi-conversation tabs✅❌
File browser✅❌
Native voice mode✅Limited
Preview rail✅❌
Drag-and-drop files✅❌
Works anywhere (no install)❌✅
Admin panelVia settings✅ Full
Auto-update✅N/A

11 Troubleshooting

❌ "Test" fails with 401 Unauthorized

  • The token in the Desktop App doesn't match HERMES_DASHBOARD_SESSION_TOKEN in ~/.hermes/.env
  • You're bound to a non-loopback address without --insecure — the OAuth gate is on and ignores session tokens
  • Verify manually:
curl -s -H "X-Hermes-Session-Token: YOUR_TOKEN" http://<host>:9119/api/status # Should return JSON, not a 401

❌ App says "Ready" but chat does nothing

  • The backend was started without --tui. The /api/status probe passes, but the chat WebSocket is refused.
  • Fix: restart the backend with --tui (or set HERMES_DASHBOARD_TUI=1 in the environment)

❌ Connection refused / times out

  • Backend bound to 127.0.0.1 (default) — change to 0.0.0.0 or the Tailscale IP
  • Firewall blocking port 9119 — open it: sudo ufw allow 9119/tcp
  • Tailscale not connected on one or both devices

❌ "No token to copy"

This is expected! Hermes never surfaces the default ephemeral token. You must create one yourself (see Step 4.1). There's nothing to "find" in the logs or config — you mint it.

❌ Service dies after SSH logout

You forgot loginctl enable-linger. Run:

sudo loginctl enable-linger $USER

❌ Desktop App boot failure

Check the desktop log:

hermes logs gui -f # Or directly: cat ~/.hermes/logs/desktop.log

12 Security Best Practices

  • Never expose port 9119 to the public internet. The --insecure flag disables the OAuth gate, leaving only the session token as protection. Always use Tailscale or SSH tunnels.
  • Use strong tokens. The openssl rand -base64 32 command generates 256-bit tokens. Don't use weak or guessable strings.
  • Secure ~/.hermes/.env. This file contains your API keys and session token. Keep it at chmod 600 (owner read/write only).
  • Use Tailscale ACLs for multi-user environments. You can restrict which Tailscale users can reach the Hermes port.
  • Rotate tokens periodically. Generate a new token, update ~/.hermes/.env, restart the service, and update the Desktop App.
  • Enable redact_secrets (on by default) so API keys don't leak into conversation logs.
  • Consider a reverse proxy (nginx, Caddy) with TLS if you need HTTPS. Caddy with a Tailscale certificate is the simplest path.
💡 The gold standard setup: Tailscale VPN + bind to Tailscale IP + systemd service + strong session token. This gives you encrypted transport, zero public exposure, automatic reconnection, and persistent uptime.

🎯 Key Takeaways

🔑 Key Takeaways

  • Hermes separates backend from frontend — install the heavy backend on a remote server, use the lightweight Desktop App as your local interface.
  • Three mandatory flags: --tui (enables chat WebSockets), --insecure (for non-loopback bind), and --host (bind address).
  • You mint your own token — Hermes never surfaces its default ephemeral one. Generate with openssl rand -base64 32 and pin in ~/.hermes/.env.
  • Tailscale is the recommended secure channel — free, encrypted, zero-config mesh VPN. Bind to the Tailscale IP for maximum security.
  • SSH tunnels work too — no extra software needed, just ssh -NL 9119:127.0.0.1:9119. Use autossh for auto-reconnect.
  • systemd + linger = persistent service — survives SSH logouts, reboots, and crashes.
  • All frontends share state — start a session in the Desktop App, continue on Telegram, resume from CLI. Skills, memory, and sessions are universal.
  • Web Dashboard as fallback — no install needed, just open a browser to your remote dashboard URL.
  • Never expose --insecure to the public internet — always tunnel through Tailscale or SSH.

🔗 Resources & Links