How to Run Hermes Agent on a UGREEN NAS with Docker

This guide covers running Hermes Agent as a persistent gateway on a UGREEN NAS. The install itself is straightforward; the permissions step is where most setups break without any useful error.

Prerequisites: UGREEN NAS with Docker installed, SSH access to the NAS, and a Telegram bot token if you want Telegram integration.

Create the Container

Use nousresearch/hermes-agent:latest. Map port 8642 → 8642, mount /volume1/docker/hermes to /opt/data, and set the command to gateway.

UGREEN Docker app showing hermes-agent container running — nousresearch/hermes-agent:latest image, 1% CPU, 227MB RAM used out of 7.5GB, created 2026-04-29

At idle: about 1% CPU and 227MB RAM on a 7.5GB NAS.

Run First-Time Setup

UGREEN's Docker app doesn't expose a terminal by default. Get a shell through the UI:

Docker → Container → click hermes-agent
Terminal tab → Add
Choose /bin/bash

Inside the container, run:

./setup-hermes.sh

Terminal tab inside the hermes-agent container — /opt/hermes directory listing with setup-hermes.sh visible, root shell prompt

This creates /opt/data/config.yaml and /opt/data/.env. Without it, those files don't exist and the gateway exits immediately on start.

Fix Volume Permissions

Caution

Hermes fails silently when it can't read its config — no error in the logs, just a gateway that doesn't respond. On UGREEN, this is almost always a permissions issue.

SSH into the NAS and check:

ls -ld /volume1/docker/hermes

If you see this, the problem is confirmed:

drwx------ 1 10000 10000 ... hermes

UID 10000 owns the directory with 700 permissions. The Hermes process runs as UID 1000 and has zero access — not read, not directory traversal. Fix it:

sudo chown -R 1000:10 /volume1/docker/hermes
sudo chmod -R 755 /volume1/docker/hermes

Verify the result looks like this before restarting:

ls -ld /volume1/docker/hermes
# drwxr-xr-x ... 1000 10 hermes

After restarting, Permission denied: '/opt/data/config.yaml' should disappear from the logs. If Telegram was returning unauthorized errors, those clear too.

If it still breaks, open permissions fully to isolate the cause:

sudo chmod -R 777 /volume1/docker/hermes

If that fixes it, tighten back to 755. Reapply chown after every container recreation — UGREEN can reset volume ownership on remount.

Configure .env

Edit /opt/data/.env on the NAS:

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
API_SERVER_KEY=pick-something-here
GATEWAY_ALLOW_ALL_USERS=true
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_ALLOWED_USERS=your-telegram-user-id

Important

Set API_SERVER_KEY to something you generate. Any request to the gateway uses this to authenticate. Don't leave it as a weak placeholder if your NAS is reachable outside your local network.

Restart the container after saving.

Health Check

http://<nas-ip>:8642/health

Expected: {"status":"ok"}. Connection refused means the container didn't start or port binding is wrong. An empty response or config error points back to the permissions problem.

Connecting a Frontend

Hermes exposes an OpenAI-compatible API on port 8642. I ended up using Telegram — configure the bot token and allowed user IDs in .env and it works out of the box. The gateway also supports any OpenAI-compatible frontend; Open WebUI and LibreChat both connect by pointing at http://<nas-ip>:8642 as the API base URL.

There's also a dashboard container (nousresearch/hermes-agent dashboard) on port 9119 that shows agent state. It's a separate container and not required for the gateway to work, but worth adding once the core setup is stable.