Hermes Agent on Unraid — Complete Install Guide (v0.14.0, Built from Hard-Won Experience)

---

Prerequisites

• Unraid 6.12+

• Docker enabled

• An SSD or NVMe pool mounted (e.g., /mnt/cache/ or /mnt/ssd/) — not an array disk via /mnt/user/

• An Ollama container already running and accessible on your LAN

• At least one Ollama model with native context ≥ 64K (gemma4, qwen 3.6, llama 3.x, etc.)

• Optional: a Telegram bot token from @BotFather and your numeric user ID from @userinfobot

---

Phase 1 — Prep Ollama Properly

Before Hermes touches anything, make sure Ollama is configured for agent work.

Edit your Ollama container template

Add these environment variables (or update them if they exist):

Key	Value	Purpose
OLLAMA_HOST	0.0.0.0:11434	Reachable from other containers
OLLAMA_CONTEXT_LENGTH	65536	Agent workloads need 64K+
OLLAMA_KEEP_ALIVE	24h	Keep model warm in VRAM
OLLAMA_FLASH_ATTENTION	1	Faster, less VRAM
OLLAMA_NUM_PARALLEL	2	Allow concurrent requests
OLLAMA_MAX_LOADED_MODELS	2	Main model + optional aux
OLLAMA_SCHED_SPREAD	1 (optional)	Force multi-GPU split (only if needed)

Apply. Verify with:

docker exec ollama printenv | grep OLLAMA

docker exec ollama nvidia-smi

Both GPUs should be visible.

Pick and prepare a model

Run:

docker exec ollama ollama list

Pick one with native context ≥ 64K. Verify:

docker exec ollama ollama show <model-name> | grep -i "context length"

If the number is ≥ 65536, you're set. If lower, pick a different model or create a derived Modelfile.

---

Phase 2 — Prepare the Appdata Directory

This is the single biggest source of failure later. Get it right now.

Critical: use a direct pool path, NOT /mnt/user/

The FUSE-based /mnt/user/ filesystem breaks SQLite locking. Always use the direct pool mount.

in console:

mkdir -p /mnt/cache/appdata/hermes-agent

(Replace /mnt/cache/ with /mnt/ssd/ or whichever pool you use for appdata.)

Do NOT chown to 99:100

The Hermes image expects UID 10000 internally.

Match that:

in console:

chown -R 10000:10000 /mnt/cache/appdata/hermes-agent

---

Phase 3 — Run the Setup Wizard (Carefully)

Pull the image and run the wizard

docker run -it --rm \

  -v /mnt/cache/appdata/hermes-agent:/opt/data \

  nousresearch/hermes-agent setup

Wizard answers — exact values

Model provider: Choose Custom Endpoint (enter URL manually) — NOT "Custom Direct API."

API base URL: http://<your-unraid-ip>:11434/v1 (e.g., http://10.10.10.150:11434/v1 — the /v1 is required, OpenAI-compat path)

API key: ollama (any non-empty string — Ollama doesn't validate it)

Model name: Exact tag from ollama list, e.g., gemma4:26b

Context length: 65536

⚠️ Critical typing rule: Do NOT press the up arrow during text input. The wizard captures the literal \e[A escape sequence and corrupts the value. If you mistype, use Backspace, never arrow keys.

Configure aux models: Skip / use main provider for everything. Adding aux models with mismatched context windows causes silent failures.

Telegram setup (optional):

• Bot token: paste the full <numeric>:<alphanumeric> from BotFather (40+ chars). If you only have a placeholder, skip this step rather than entering junk.

• Allowed users: paste your numeric Telegram user ID from @userinfobot. Never leave empty — "open access" means anyone with your bot username can burn your tokens.

Agent name / SOUL: accept defaults.

⚠️ Critical: NEVER Ctrl+C the wizard

The wizard atomic-commits at the end. Ctrl+C = lost configuration. If a step asks something you don't have an answer for, enter a placeholder (e.g., none, skip) and edit the file afterward. Always let the wizard run to completion.

Verify what the wizard wrote

cat /mnt/cache/appdata/hermes-agent/config.yaml | head -10

grep -E "TELEGRAM|HERMES" /mnt/cache/appdata/hermes-agent/.env

The config.yaml should have a clean model: block. The .env should have your Telegram credentials if you set them up.

---

Phase 4 — Build the Unraid Docker Template

Switch to Advanced View in the top-right toggle of the Add Container page. Without this, you can't add Post Arguments or Extra Parameters.

Top section

Field	Value
Name	hermes-agent
Repository	nousresearch/hermes-agent:latest
Network Type	Bridge
Console shell command	Bash
Privileged	Off
Post Arguments	gateway run
Extra Parameters	--restart=unless-stopped --shm-size=1g --memory=8g
Icon URL (optional)	https://avatars.githubusercontent.com/u/134168893?s=200
WebUI	http://[IP]:[PORT:9119]/

Ports — add BOTH at once

Gateway API:

Field	Value
Config Type	Port
Name	Gateway API
Container Port	8642
Host Port	8642
Default Value	8642
Connection Type	TCP

Web Dashboard:

Field	Value
Config Type	Port
Name	Web Dashboard
Container Port	9119
Host Port	9119
Default Value	9119
Connection Type	TCP

Path (just one)

Field	Value
Config Type	Path
Name	Config and Data
Container Path	/opt/data
Host Path	/mnt/cache/appdata/hermes-agent
Default Value	/mnt/cache/appdata/hermes-agent
Access Mode	Read/Write

⚠️ Use the direct pool path (/mnt/cache/ or /mnt/ssd/), never /mnt/user/.

Environment Variables — exactly these, nothing extra

Dashboard:

Key	Value	Notes
HERMES_DASHBOARD	1	Enable web dashboard
HERMES_DASHBOARD_HOST	0.0.0.0	LAN-accessible
HERMES_DASHBOARD_PORT	9119	Match the port mapping
HERMES_DASHBOARD_TUI	1	In-browser Chat tab

API server:

Key	Value	Notes
API_SERVER_ENABLED	true	OpenAI-compat API on 8642
API_SERVER_HOST	0.0.0.0	LAN-accessible
API_SERVER_KEY	(generate)	See below
API_SERVER_CORS_ORIGINS	*	Allow browser apps

Generate API key once:

openssl rand -hex 32

Paste that into the API_SERVER_KEY field.

Local model tuning:

Key	Value	Notes
HERMES_STREAM_READ_TIMEOUT	1800	30 min timeout for slow local inference
TZ	America/New_York	Your timezone

Click Apply

The container will pull the image (~2 GB) if not already cached, then start.

---

Phase 5 — First Boot Verification

Watch the startup logs

docker logs -f hermes-agent

What you should see (in order):

1. Fixing ownership of /opt/data to hermes (10000)

2. Syncing bundled skills into ~/.hermes/skills/ ...

3. Done: 87 new, 0 updated, 0 unchanged. 87 total bundled. (first run) or 0 new, 0 updated, 87 unchanged (subsequent)

4. Starting hermes dashboard on 0.0.0.0:9119 (background)

5. [dashboard] Hermes Web UI → http://0.0.0.0:9119

6. The gateway banner

7. No errors — specifically:

   • ❌ No esbuild permission denied

   • ❌ No database is locked

   • ❌ No YAML parse errors

   • ❌ No SIGTERM restart loops

   • ❌ No "No user allowlists configured" (if you set up Telegram)

Ctrl+C to stop tailing once it settles.

Verify ports are mapped

docker port hermes-agent

Expected:

8642/tcp -> 0.0.0.0:8642

9119/tcp -> 0.0.0.0:9119

Open the dashboard

Browser → http://<your-unraid-ip>:9119

You should see:

• Status page showing gateway running and version

• Chat tab in the sidebar (the in-browser TUI is working)

• Config tab with your model and context settings populated

• Logs tab populating

---

Phase 6 — Smoke Test the Full Stack

Test via the GUI Chat tab

Send: "hello, what model are you running?"

Should reply with model name and respond cleanly. If it errors with "context window below minimum 64,000," your config.yaml has the wrong context_length — go to Config tab and verify it's 65536.

Test tool use via Telegram (if configured)

Send to your bot: "Run ls -la in the workspace and tell me what's there"

Should:

1. Acknowledge the request

2. Run the tool

3. Reply with file listing

While it runs, in terminal:

docker exec ollama ollama ps

docker exec ollama nvidia-smi

Expected:

• ollama ps shows your model loaded with CONTEXT 65536, 100% GPU

• nvidia-smi shows ~22-24 GB VRAM in use, your model's process listed

Set Telegram home channel

In your Telegram chat with the bot, send: /sethome

This lets Hermes deliver scheduled task results and cross-platform messages to that chat.

---

Troubleshooting Quick Reference

Symptom	Likely Cause	Fix
ERR_CONNECTION_REFUSED on :9119	Port not mapped or dashboard crashed	Verify docker port hermes-agent shows 9119; check logs for [dashboard] errors
Container restart-loops with esbuild error	Wrong UID — directory permissions	Re-chown appdata to 10000:10000, remove HERMES_UID/HERMES_GID env vars
"database is locked" warning	Appdata on /mnt/user/ FUSE	Move appdata to /mnt/cache/ or /mnt/ssd/ direct pool path
YAML parse error line 3 column 6	Hidden characters or \e[A from arrow keys in wizard	Delete config.yaml, re-run wizard, type carefully
"context window 32,768 below minimum 64,000"	context_length in config.yaml too low	Dashboard → Config → General → set to 65536
Telegram bot doesn't respond	Missing TELEGRAM_ALLOWED_USERS in .env	Add TELEGRAM_ALLOWED_USERS=<your_id> to .env, restart container
Model loaded but only on one GPU	Working as designed (fits on one card)	Add OLLAMA_SCHED_SPREAD=1 to Ollama if you want forced split
Wizard "leave empty for open access" prompt	Don't!	Always set explicit allowlist on Telegram/Discord/Slack

---

Optional Improvements

Once everything works, these polish steps are worth doing:

• Add a fallback provider in config.yaml for when local inference is unavailable

• Install Chrome/Playwright inside the container for browser_navigate tool

• Configure cron jobs in the dashboard for scheduled agent tasks

• Bump container memory to 16 GB if you'll do heavy multi-turn agent work

• Save the Unraid template as a Community Apps XML so you can rebuild quickly

---

Summary of Lessons Learned

The four mistakes we made and what to remember:

1. UID matters more than Unraid conventions. I had you set HERMES_UID=99 to match Unraid's "nobody" — but the image's pre-built /opt/hermes/ is owned by UID 10000. The mismatch killed the dashboard TUI build. Don't fight the image — use UID 10000 and chown appdata to match.

2. /mnt/user/ is not safe for SQLite-using containers. Always use the direct pool path. This applies to every Docker container on Unraid with a database (Plex, *arr stack, Nextcloud, Hermes, etc.).

3. The wizard atomic-commits. Ctrl+C loses everything. If you don't have a value for a prompt, enter a placeholder rather than aborting.

4. Hermes' context check reads YOUR config, not the model's max. The 32K error wasn't a model limitation — it was the value we wrote in config.yaml. Always set context_length ≥ 65536 for any model that natively supports it.

Follow this guide top to bottom and you'll have a working Hermes Agent on Unraid in 20 minutes instead of 4 hours. Save it somewhere — you may want to rebuild someday.

I am not an expert, I know a decent amount but I used Opus 4.7 to add a custom docker and install the latest hermes because I could not find a docker in the app store that had the latest.. of course they will probably be one there in the next hour :) Hope this helps someone.

Edited May 21May 21 by Renew

Hello thanks for the post I have 1 question why not use the official hermes app instead? what is the benefit of doing this way ?