Enter your search text in the box above

Select a result to preview

Hermes Desktop Setup — Decision Guide

#ai-agents #automation

Hermes Desktop Setup — Decision Guide

A decision-tree approach to installing and configuring the Hermes Agent desktop app, synthesized from five in-depth walkthroughs. Pick your path based on your model source, risk tolerance, and what you want Hermes to do for you.

Quick-Start: Minimum Viable Setup (10 minutes)

If you just want Hermes running with defaults and a working model:

  1. Download the desktop app from hermesagent.com
  2. Pick a provider — if you already pay for OpenAI/Codex, sign in with that. If not, the Nous Research subscription is purpose-built for Hermes.
  3. Start a session — type "hello" and confirm you get a response
  4. Done. You're functional. Everything below is optimization.

UI Tour: Where Everything Lives

Before diving into settings, orient yourself in the desktop app. Tonbi's mental model: the desktop app is a control room, not a chat box — it can point to any Hermes instance on the network, and everything you need to manage the agent is in one place.

Element What It Does
Sessions Chronological list of all conversations. Click to switch. Right-click to pin, rename, or group by workspace.
Artifacts Files the agent has created (images, code, documents). Browse without leaving the app.
Messaging Connect Telegram, Discord, Slack, WhatsApp — configure bot tokens and user IDs here.
Skills & Tools Enable/disable individual skills and tool sets. Also where you manage cron jobs — create, edit, pause, view history.

Bottom Panel

Element What It Shows
Model selector Current model. Click to switch between providers and models on the fly.
Context meter How full the context window is (e.g., "6%"). Watch this on long sessions.
Session counter Turn count for the current session.
Gateway indicator Shows whether you're connected to local or remote gateway.
Terminal button Opens an integrated terminal at the workspace directory.
Updates indicator Hermes updates frequently — the bell icon lights up.

Chat Area

Decision 1: Which Model Provider?

This is the single biggest lever affecting cost, capability, and privacy. Match your situation:

I want to... Best choice Why
Use my existing Codex/OpenAI subscription Codex Near-unlimited GPT-5.5 at no extra per-token cost. Best value if you're already paying $100-200/mo.
Support open-source, get best Hermes integration Nous Research subscription Purpose-built for Hermes. Igor's #1 recommendation. Revenue supports open model research.
Run entirely on my own hardware, zero API costs Local Ollama Point Hermes at a local endpoint (http://localhost:11434/v1). Requires ≥ 64K context window — most Ollama models default to 2048. See the context fix below.
Access 200+ models under one API key, tier by cost OpenRouter + Porto router AI LABS' choice for team use. Porto auto-routes tasks to the right tier (cheap for simple, powerful for complex).
Maximum power, cost is secondary Anthropic (Claude Opus) Note: Anthropic's subscription ToS disallows this use. API key only. Igor: only worth auxiliary offloading to cheaper models for background tasks.

The Local Ollama 64K Context Fix

Most Ollama models ship with a 2048-token context window. Hermes needs 64,000 tokens minimum to give your agent tools. Without this fix, the agent will respond "I can't access anything" or hallucinate.

# 1. Create a Modelfile
ollama show gemma4:12b --modelfile > Modelfile.gemma4

# 2. Add this line:
# PARAMETER num_ctx 65536

# 3. Create the variant
ollama create gemma4-64k -f Modelfile.gemma4

# 4. Point Hermes at it
hermes config set model.default_model gemma4-64k

Decision 2: Essential Settings (What to Configure First)

These settings have the highest impact-to-effort ratio. Sources agree on most; disagreements are noted.

Personality & Transparency

Setting Recommendation Why
Personality Concise or Technical Igor: "Everything else I dislike." Avoids verbose/chatty output.
Reasoning blocks ON Igor: lets you see the model's thinking and spot errors before it acts. Transparency > speed.
Timezone Set it So "tomorrow 8am" means your 8am.

Safety: Pick Your Philosophy

Two camps exist. Neither is wrong — pick based on your model and risk tolerance.

Philosophy Approval Mode Who Recommends When to Use
YOLO Off or Smart Igor, AI LABS (with --yolo flag) You're using a smart frontier model (GPT-5.5, Claude Opus 4.5+). These models rarely make catastrophic mistakes. Igor: "The graph looks like this — as intelligence goes up, mess-up rate goes to near zero."
Measured Smart Default for most users You want the agent to ask before destructive operations (file deletion, shell commands) but not pester you for routine work.

Igor's blunt take: "I don't believe secure mode actually exists. You can't sandbox your agent to zero risk through approval prompts. If you want real isolation, use Docker for the execution backend — not approval mode."

Memory

Setting Recommendation Consensus
Persistent memory ON Unanimous. This is Hermes' killer feature — the agent builds user.md and memory.md autonomously over time.
User profile ON Unanimous. Tells the agent who you are and how you work.
Memory budget Leave default Auto-prunes stale entries to keep context small.
Auto-memory ON AI LABS keeps it on even though it costs tokens — team-wide context sharing via Slack is worth it. If you're solo and cost-sensitive, you could turn it off, but you lose the self-evolving nature.

Context Engine

Setting Default Recommendation Source
Compressor ON Keep ON Unanimous — compresses long conversations to avoid context window bloat
Compression threshold 50% 50-75% AI LABS: lower it to compress sooner (save tokens). Tonbi: 75% matches Codex/Claude Code standard. Decision: start at 50%, raise only if you notice context loss
Target ratio 20% 20% or lower How much uncompressed tail carries over. Lower = fewer tokens per message. AI LABS lowered theirs on OpenRouter.

Voice

Igor: "I recommend you completely skip it." Wanderloots and Tonbi both noted built-in voice exists but didn't recommend it. All three creators prefer external tools — the built-in voice works but isn't a strength of the desktop app yet.

Recommended alternative: Handy — a free, open-source, cross-platform speech-to-text app that runs entirely offline. Press a keyboard shortcut (default: Ctrl+Z), speak, release, and your words appear in any text field — including the Hermes chat input. Uses Whisper and Parakeet models locally on your device. No cloud, no subscription, no API keys. Ideal for dictating prompts to Hermes without sending audio anywhere.

Decision 3: Productivity Boosters (By What You Want)

"I want to keep costs predictable"

From AI LABS' systematic team audit:

Action Setting Impact
Cap output max_tokens Prevents rambling responses that waste tokens
Limit turns max_turns: 60 (default 150) Stops the agent spinning on stuck problems. "150 turns of confused looping burns real money."
Prevent loops hard_stop: true Kills sessions where the agent isn't making progress
Cron job caps Set max_turns per cron job No limit by default — runaway background jobs are the #1 hidden cost
Auxiliary models Point to cheaper model Background tasks (vision, search, compression, skill scanning) default to your expensive main model. Offload to DeepSeek or Gemini Flash.
Sub-agent model Set cheaper model Every sub-agent spawns its own context window. Each spawn costs tokens.
Track spend hermes insights 30-day breakdown by tool, skill, and session. Also: Hermes stores all token data in a SQLite DB — any agent can query it.

"I want to keep things fast"

Action How
Trim unused tools Hermes ships with 17+ tools. Disable any you never use via Settings → Tools or hermes tools disable <name>. Fewer tools = smaller context per message = faster responses.
Trim unused skills 90+ skills pre-installed. Each one's header (name + description) sits in context permanently. Disable Minecraft skills, CAD tools, trading workflows — anything outside your actual work.
Disconnect unused MCP servers Each MCP server brings its own tool definitions into the context window.
Set tool search to auto Loads tool definitions only when the agent actually needs them — like Claude's tool search.
Use ephemeral system prompts One-time session instructions via HERMES_EPHEMERAL_SYSTEM_PROMPT instead of permanent context files.

"I want separate work and personal setups"

Use Profiles (Wanderloots + Igor):

Igor's take: "Profiles are separation of context — like separation of concerns in software engineering. Powerful, but adds complexity. Only use if you genuinely need strict isolation."

Wanderloots' approach: simply ask Hermes to set up profiles for you — "create two profiles, one for local and one for cloud" — and it handles the cloning.

"I want quick commands for repetitive tasks"

From AI LABS and Tonbi:

Command What it does
/compress Start a fresh session from a summary — saves tokens, keeps context
/undo Step back one message. Better than re-prompting — undo, then give a fresh prompt explaining what went wrong
/fix-aux <provider> <model> Repoint all 9 auxiliary model slots in one command (custom quick command)
hermes prompt-size See exactly what's in your system prompt — skills, memory, tool schemas, profile
hermes sessions optimize Merge search index, vacuum session DB

"I want to understand how sessions work"

Tonbi emphasized session mechanics as a core workflow and cost-saving pattern:

"I want to use sub-agents for parallel work"

Sub-agents are Hermes spawning copies of itself to work on independent subtasks simultaneously. Each sub-agent gets its own context window and reports findings back. Tonbi: "Profiles are independent agents with different models, skills, and memory. Sub-agents are parallel workers cloned from the current agent."

When to use sub-agents: research that benefits from parallel exploration (search three sources at once), code reviews (one sub-agent reviews while another tests), any task where doing things sequentially is the bottleneck.

Key settings (from AI LABS):

Setting Default Recommended Why
max_concurrent_children 3 3-5 How many sub-agents can run in parallel. Default 3 is fine for most. Bump to 5 if you regularly hit bottlenecks.
max_spawn_depth 1 1 Whether sub-agents can spawn their own sub-agents. Keep at 1 — nesting multiplies token costs exponentially.
subagent_auto_approve false true When true, sub-agents don't pause to ask permission for tool calls. Essential for hands-off parallel work.
Sub-agent model auto (main model) Set cheaper model Every sub-agent spawn burns tokens at your main model's rate. Offload to DeepSeek or Gemini Flash — AI LABS saved significantly here.

Cost warning: sub-agents are powerful but not free. Each spawn creates its own context window with full tool/skill headers. If you run 3 sub-agents on your main model, you're paying ~3× the per-turn cost. Always set a cheaper sub-agent model.

Decision 4: Execution Backend — Safety & Sandboxing

This controls where terminal commands and file operations execute. It is NOT the same thing as the gateway (see Remote Connectivity below). Igor draws the line most people miss: execution backend only affects terminal/file ops — API calls to OpenAI/Anthropic still happen on your local machine regardless.

Backend What It Does When to Use
Local Everything runs on your machine You trust your model and accept responsibility. Igor's default.
Docker Terminal/file ops run in a container — actual sandboxing You want real isolation. Igor: "The BEST way to isolate if you don't fully trust your model. Don't rely on approval mode — that's theater. Docker is the real sandbox."
SSH Terminal/file ops run on a remote machine You have a dedicated server (training, compute-heavy tasks) but want API calls to stay local.
Modal / Daytona / Singularity Cloud container backends Alternative container runtimes if Docker isn't your stack.

Remote Connectivity

Every creator who covered the desktop app called this the killer feature. Igor: "My favorite feature — the best way to run Hermes." Tonbi: "The desktop app is a control room, not a chat box." Wanderloots: "One shared brain across multiple devices."

Remote connectivity is about decoupling the GUI from where the agent runs. The Hermes desktop app is not the agent — it's a window into the agent, wherever that agent lives. This means the agent keeps running when you close the app, cron jobs fire on schedule, and you can connect from multiple devices to the same agent with a single memory bank.

The Critical Distinction

Before configuring anything, understand these are two different things:

Setting Location What It Controls
Execution backend Settings → Advanced Where terminal commands and files live
Gateway Bottom-left panel Where the Hermes agent process runs — this is what makes remote connectivity work

When you connect via remote gateway, the desktop app becomes a thin client — like messaging the agent on Telegram, but with the full desktop UI. Nothing runs on your local machine except the UI. All processing, memory, skills, and cron jobs live on the remote machine.

Pattern A: Same Wi-Fi / LAN

The simplest remote setup. Both machines are on the same network.

On the machine running Hermes (the "server"):

  1. Set a username, password, and 32-character secret in Hermes settings
  2. Start the dashboard: hermes dashboard --no-open --host 0.0.0.0 --port 9119
  3. Note the machine's local IP (e.g., 192.168.1.100)

On your laptop (the "client"):

  1. Settings → Gateway → Remote Gateway
  2. Enter: http://192.168.1.100:9119
  3. Authenticate with username/password

Your laptop is now a window into the server's agent. Sessions, memory, skills — everything lives on the server.

Pattern B: VPS (24/7 Agent)

The agent runs on a cloud VPS. This is the pattern for always-on cron jobs and multi-device access. Igor considers this the best way to run Hermes.

Prerequisites:

On the VPS:

  1. SSH into the VPS
  2. Register the dashboard: hermes dashboard register
  3. Set up OAuth (required for VPS, not needed for LAN):
    • In .env, add: HERMES_DASHBOARD_OAUTH_CLIENT_ID=<your-client-id>
    • In Nous Research Portal, set the redirect URL to http://<VPS-IP>:9119/oauth/callback
  4. Start the dashboard: hermes dashboard --host 0.0.0.0 --port 9119
  5. Critical — make it permanent. The dashboard process dies when your SSH session ends. The cleanest fix: ask Hermes itself to create a long-running service. "Create a systemd service for the Hermes dashboard that starts on boot and survives disconnects."

On your desktop/laptop:

  1. Settings → Gateway → Remote Gateway
  2. Enter: http://<VPS-IP>:9119
  3. Sign in via Nous Research OAuth when prompted
  4. The gateway connects — your local app is now a thin client

What you get:

Pattern C: Tailscale (Secure, No Public IPs)

Tonbi's recommended pattern for production. Tailscale creates a private mesh network so you never expose Hermes to the public internet.

On both machines:

  1. Install Tailscale (sudo tailscale up)
  2. Verify: tailscale status — both machines should show as connected

On the VPS:

  1. Start the dashboard with the Tailscale IP: hermes dashboard --host <tailscale-ip> --port 9119
  2. In Nous Research Portal, set the redirect URL using the Tailscale IP: http://100.x.y.z:9119/oauth/callback

On your desktop/laptop:

  1. Settings → Gateway → Remote Gateway
  2. Enter: http://<VPS-tailscale-ip>:9119
  3. Authenticate via OAuth

Why Tailscale: No open ports on the VPS. No public IP exposure. Traffic is encrypted end-to-end. Works even if both machines are behind NAT/firewalls.

Multi-Device, Single Memory Bank

Wanderloots emphasized this pattern: run the Hermes backend on one machine (desktop or VPS), connect from multiple devices (laptop, phone via Telegram), and maintain one shared brain. Memory updates from any device are visible to all devices.

               ┌─────────────────────┐
               │   VPS / Desktop     │
               │  (Hermes Backend)   │
               │  • Memory           │
               │  • Skills           │
               │  • Cron Jobs        │
               └──────┬──────┬───────┘
                      │      │
            gateway   │      │  Telegram
                      │      │
          ┌───────────┘      └──────────┐
          ▼                             ▼
   ┌─────────────┐              ┌─────────────┐
   │  Laptop     │              │  Phone      │
   │  (Desktop   │              │  (Telegram  │
   │   App)      │              │   Bot)      │
   └─────────────┘              └─────────────┘

Troubleshooting Remote Connectivity

Problem Likely Cause Fix
"Gateway disconnected" after SSH exit Dashboard process died Make dashboard permanent (systemd service or nohup)
OAuth redirect fails Redirect URL mismatch in Nous Portal Match the URL exactly — check protocol (http vs https), IP, and port
Can't reach VPS dashboard Firewall blocking port 9119 Open port 9119 on VPS firewall, or use Tailscale
"Registration error" on dashboard VPS not registered Run hermes dashboard register on the VPS first
Tailscale machines can't see each other Tailscale not running or magicDNS disabled tailscale status on both; ensure both show as active

Decision 5: Automation & Messaging

Connect Hermes to Your Phone

Telegram is the easiest gateway (Wanderloots, Tonbi, all sources agree):

  1. Search BotFather on Telegram → /newbot → name it → copy the API token
  2. Search Raw Data Bot on Telegram → /start → copy your user ID
  3. In Hermes Desktop: Settings → Messaging → Telegram → paste token + user ID
  4. Restart the messaging gateway
  5. Message your bot on Telegram — two-way conversation with your agent from anywhere

Other platforms: Discord, Slack, WhatsApp, SMS, email — all follow the same bot-token + user-ID pattern.

Build a Self-Learning Daily Briefing

Wanderloots' end-to-end workflow for a cron job that gets better every day:

  1. Describe the goal to Hermes in chat. Example: "Every morning, give me the top AI news curated for my interests, delivered to Telegram."
  2. Ask it to make a plan first — ground it in Hermes docs so it doesn't hallucinate capabilities
  3. Run a dry run in chat — don't jump straight to cron. See what the output looks like, tweak it.
  4. Give feedback → agent updates the skill. "More like story #2, less on funding, deeper on agent workflows."
  5. Schedule the cron job — attach the skill, set delivery to Telegram, pick time
  6. The feedback loop: each day, reply to the Telegram briefing with feedback → Hermes updates the skill → tomorrow is better

Critical design rule: Cron jobs start fresh sessions with no messaging history. Design your skill to pull context from memory or Obsidian — not from chat history. Wanderloots solved this with a second cron job ("skill updater") that reads Telegram feedback before the daily report fires.

Cost Optimization: The Full Picture

From AI LABS' team audit — organized by impact:

Rank Action Savings Mechanism
1 Pick the right provider Codex subscription = no per-token cost. OpenRouter Porto = tiered routing. Biggest lever.
2 Auxiliary → cheap model Background tasks don't need GPT-5.5. DeepSeek Chat is effectively free.
3 Sub-agents → cheap model Every spawn burns tokens. Set a cheaper model.
4 Trim tools, skills, MCP Everything in context costs tokens every message. Be ruthless.
5 Compress early, compress often Lower threshold, lower target ratio. Shorter context = cheaper messages.
6 Hard limits everywhere max_turns, hard_stop, cron caps. Prevents runaway costs when things go wrong.
7 Match thinking to task Max effort = more tokens. Off for simple tasks.
8 Session isolation Split work across sessions instead of one mega-conversation. Each thread carries only its own history.

Quick-Reference: Settings Cheat Sheet

Setting Recommendation Quick Reason
Personality Concise / Technical Avoids verbosity
Reasoning blocks ON See what the model is thinking
Timezone Set it "Tomorrow 8am" = your time
Approval mode Smart (or Off) Smart models rarely need babysitting
Persistent memory ON Hermes' defining feature
Compression threshold 50-75% Lower = cheaper, higher = more context
max_turns 60 Default 150 is too generous
hard_stop true Prevents infinite loops
Tool search auto Load tools only when needed
Execution backend Docker (safety) or Local (speed) See Decision 4
API keys Paste in Settings panel Never in chat

Recovery: When Something Breaks

From Tonbi's troubleshooting coverage:

Command What It Does When to Use
hermes uninstall --gui Reinstall the desktop GUI only — keeps agent, config, sessions, and memories intact Desktop app misbehaving but agent is fine
hermes uninstall Remove agent binaries but keep config, sessions, and secrets Agent needs a clean reinstall without losing your setup
hermes uninstall --full Complete wipe — everything removed Starting fresh or switching machines
Delete .venv folder Removes the Python virtual environment Dependency corruption. Desktop recreates .venv on next launch — safe to delete.

Clean reinstall (keeps everything): hermes uninstall then reinstall. Your config, sessions, and memories survive — only the agent binaries are replaced.

Check logs: Hermes writes diagnostic output. If something fails silently, check the logs (location varies by OS — ask Hermes itself: "where are your log files?").

See Also