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.

If you want to chat with Hermes directly from the terminal, run this first:

source /root/.bashrc

The shell environment inside the container doesn't load automatically when you open it through the UGREEN UI, so the Hermes CLI won't be on the path until you source it.

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.