To keep Hermes Agent running in Docker across restarts and image upgrades, mount a persistent host directory at /opt/data, run the setup wizard once, then start the gateway with a restart policy. Protect the mounted files and any published ports: that directory holds credentials and session data, while the API can expose powerful tools.
What this Docker setup runs
This guide runs Hermes itself in a Docker container as an always-on gateway. It is different from running Hermes on the host and using Docker only as the backend for terminal-command sandboxes; the two patterns have different setup and security boundaries. The Hermes Docker guide covers the containerized gateway.
As an Amazon Associate I earn from qualifying purchases.
The official image keeps mutable files outside the image under /opt/data. That includes configuration, API keys, sessions, skills, memories, logs, and other user-managed files. Keeping this directory mounted means the state can survive container replacement during upgrades. The installed application tree at /opt/hermes is root-owned and read-only to the runtime user, so use the data mount or a derived image for persistent customization rather than editing files inside a running container.
The instructions below follow the repository’s main branch documentation as accessed October 7, 2026. Image channels and implementation details can change; check the guide for the exact release you deploy.
Install and start the gateway
1. Create a persistent state directory
mkdir -p ~/.hermesKeep this directory private and writable by the container’s runtime user. It contains secrets as well as application state.
2. Run the setup wizard
docker run --rm -it
-v ~/.hermes:/opt/data
nousresearch/hermes-agent setupThe interactive wizard prompts for API keys and saves them in ~/.hermes/.env. Configure a chat platform during setup if you plan to use Hermes through messaging. The environment-variable reference recommends .env for API keys, bot tokens, and OAuth secrets, and config.yaml for non-secret behavior settings. See the environment variables reference.
3. Choose an image channel before deploying
The Hermes Docker guide describes latest and stable as stable-release-gated tags, main as a development image, and X.Y.Z tags as versioned stable images. Stable tags follow release promotion; a version tag makes the intended release explicit, while an image digest pins the exact image identity. Use a digest when reproducible image identity matters, and avoid treating main as a stable release channel.
Rank #2
- 【Build Your Own NAS & Homelab — Not Just Storage】 More than a traditional NAS, ZimaBlade 7700 is a flexible x86 mini server for building your own homelab, personal cloud, or Docker host. Perfect for DIY NAS, self-hosting, container apps, and even retro systems — not limited like typical ARM-based NAS devices.
- 【x86 Platform — Broad Compatibility, Real Freedom】 Powered by an Intel quad-core x86 processor, it runs a wide range of operating systems and software with native compatibility. Ideal for Linux, Docker, CasaOS, and more — designed for flexibility and experimentation rather than locked-down appliance use.
- 【16GB RAM for Smooth Multi-Service Workloads】 Handle file sharing, media streaming, backups, and multiple lightweight services at once. Optimized for low-power, always-on operation — a great fit for home labs and personal servers running 24/7.
- 【Smooth 4K Media Streaming — Plex Direct Play Ready】 Stream your personal media library smoothly with Plex and similar media servers. Supports 4K playback on compatible devices via direct play, delivering a reliable home media experience without the need for heavy transcoding.
- 【Complete 2-Bay NAS Kit — Ready to Build】 Includes power supply, 16GB RAM, metal drive cage for 2 HDD/SSD, and dual SATA cables — everything you need to start building your own NAS right out of the box.
The guide documents builds for amd64 and arm64. For a tagged image, use the corresponding tag in place of nousresearch/hermes-agent in the commands; for an exact pin, use the digest-qualified image reference you have selected.
4. Start the persistent gateway
docker run -d
--name hermes
--restart unless-stopped
-v ~/.hermes:/opt/data
-p 127.0.0.1:8642:8642
nousresearch/hermes-agent gateway runThis keeps the container running in the background and restarts it after a Docker daemon or host restart, unless you have explicitly stopped it. Port 8642 serves the OpenAI-compatible API and health endpoint; it is optional for a messaging-only setup, but needed when the dashboard or external tools must reach the gateway. The example binds the published port to host loopback rather than every host interface. If you intentionally need remote access, put an authenticated reverse proxy or secure tunnel in front of it and restrict network access.
Choose storage, updates, access, and inference deliberately
| Decision | Option | What it means |
|---|---|---|
| Image updates | latest or stable |
Tracks the stable-release promotion channel described in the Hermes Docker guide. |
| Image updates | Version tag such as X.Y.Z |
Selects a named stable version rather than following a moving stable channel. |
| Image updates | Digest | Pins an exact image identity; useful when deployment reproducibility is more important than automatic tracking. |
| State storage | Host bind mount | Convenient access to files such as ~/.hermes/.env; filesystem behavior matters for SQLite, especially when the path crosses a desktop VM boundary. |
| State storage | Native Docker volume | Keeps the data on Docker-managed storage and is an option when a VM-shared bind mount is unsuitable for SQLite WAL. |
| Access | Chat only | Port 8642 is optional if no dashboard or external API client needs the gateway. |
| Access | Local dashboard or API | Publish only to loopback when access is limited to the host; the API still requires an API key. |
| Access | Remote dashboard or API | Use an authenticated proxy or tunnel; do not expose the dashboard without authentication. |
| Inference | Another container | Put both containers on the same Docker network and address the inference service by its container name. |
| Inference | Host process | Use host.docker.internal on macOS or Windows; the Docker guide describes host networking on Linux. |
Use Compose for a gateway and dashboard
The repository’s official Compose file defines a gateway and dashboard service that mount the same state directory. It lets you match the container user and group to the host directory owner:
HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -dIn that Compose example, the dashboard binds to 127.0.0.1; its comments recommend an SSH tunnel for remote access and warn that exposing the dashboard on a LAN without authentication is unsafe because it stores API keys. The Compose layout’s two services do not mean you should run two gateway containers: never run two gateways against the same data directory.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Check SQLite compatibility before choosing a mount
Hermes stores sessions in SQLite at /opt/data/state.db and normally uses WAL journaling. The Docker guide warns that some bind mounts crossing a virtual-machine boundary, including virtiofs and 9p or drive mounts in certain desktop container environments, may not provide the coherent shared memory WAL requires. Concurrent writers on an unsuitable mount can silently corrupt data.
For a fresh database detected on such a mount, Hermes uses rollback (DELETE) journal mode and logs a warning. It does not live-downgrade an existing WAL database. The guide does not classify NFS, SMB, or generic FUSE mounts as safe or unsafe; it says to set database.journal_mode: delete explicitly for those cases. These behaviors are version-sensitive, so verify them against the deployed release.
Rank #4
- Dell PowerEdge R730xd 24B SFF 2U Server
- 2x Intel Xeon E5-2690 v4 2.6Ghz 14-Core (28-cores Total)
- 128GB DDR4 RAM – 4x 1.2TB 10K SAS 2.5” 12Gb/s
- Dell H730P mini 2GB 12Gb/s RAID
- 2x 750W PSU - 2x 10Gb SFP+ 2x 1Gb (RJ45) NIC
If you need to change an existing WAL database, stop every process using it, perform a one-time offline conversion, and then set database.journal_mode: delete in config.yaml. The other documented option is to move the data directory to a native Docker volume. Do not attempt a live journal-mode change while a gateway is using the database.
Size the host for the enabled features
The Hermes Docker guide publishes these figures as recommendations, not independent benchmarks or guarantees. Actual needs depend on the workload and the features enabled.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Resource | Guide’s minimum | Guide’s recommendation |
|---|---|---|
| Memory | 1 GB | 2–4 GB |
| CPU | 1 core | 2 cores |
| Data volume | 500 MB | 2+ GB as sessions and skills grow |
| Memory with browser automation | Not stated | At least 2 GB when browser tools are active |
Browser automation is identified as the most memory-hungry feature. Use the higher memory recommendation when browser tools are active, and watch actual resource consumption as your sessions, skills, and workload grow.
Best Value
- Ateco #1357 Dough Docker for use with pastry or pizza dough for best baked results
- Roll over pizza dough, pie dough, pastries before baking, the small depressions help reduce blistering or air pockets from forming while crust bakes
- Measures 5.25-Inches wide, 2.25-Inch diameter, 8.25-Inches long including handle
- Hand wash suggested for best results; made from high impact plastic
- Family owned and operated since 1905, Ateco has produced specialized professional quality baking and decorating tools for professional pastry chefs and discerning home bakers alike
Connect to local inference without using the wrong hostname
Inference server in another container
Put Hermes and the inference service on a shared Docker network and configure Hermes to connect to the inference container’s name and listening port. Do not use localhost from inside the Hermes container to reach a separate container: there, it refers to Hermes itself. Ensure the inference process listens on 0.0.0.0 inside its container and that the configured port matches.
Inference server running on the host
On macOS and Windows, the Docker guide uses host.docker.internal as the host address. On Linux, it describes host networking as an option. With host networking, published-port flags are ignored and container ports are directly exposed on the host, so account for that exposure when deciding whether to use it.
Protect the gateway, dashboard, and credentials
Require authentication for API access
The API server exposes Hermes tools, including terminal commands. Its documentation requires an API key for every deployment, including loopback access, and gives 127.0.0.1 as the default bind address. Treat the key as a high-value credential; keep browser CORS origins narrow if browser access is explicitly enabled. See the API server documentation.
Limit dashboard and messaging access
Do not expose the dashboard on a LAN without authentication, and do not use an insecure all-interface dashboard bind for remote access. Use an authenticated reverse proxy or tunnel instead. For messaging, Hermes defaults to denying access when no allowlist is configured and GATEWAY_ALLOW_ALL_USERS is unset; prefer explicit allowlists or pairing over opening access broadly.
Be selective about environment variables
The security guide describes Docker as an isolation boundary for terminal command execution and lists hardened container settings, including dropped Linux capabilities, no-new-privileges, a process limit, and size-limited tmpfs mounts. However, environment variables explicitly forwarded into a terminal container are readable by code running there. Forward only the credentials a task actually needs. See Secure Hermes on a Work Machine.
Troubleshoot common startup and connection failures
- Container exits soon after launch: Run
docker logs hermes. The Docker guide identifies a missing or invalid.envfile and a port conflict as common causes. - Permission errors in the mounted directory: Match the container UID and GID to the owner of the host state directory with
HERMES_UIDandHERMES_GID, or ensure the mount is writable. Do not make the whole directory world-readable; it contains credentials. - Local inference is unreachable: Confirm the containers share a Docker network, the inference process listens on
0.0.0.0, and the hostname and port in Hermes configuration match the service. - SQLite warnings or corruption concerns: Check whether the data path crosses a VM boundary and whether the database is in WAL mode. Stop all database users before an offline conversion or move the state to a native Docker volume.
The Docker, Compose, security, API, and environment behavior described here is documented by NousResearch in the Hermes Docker guide, Compose file, security guide, API server guide, and environment reference.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems
