The reliable way to run Hermes Agent with Docker Compose is to keep its state on the host, retain the image’s default supervised entrypoint, and expose only the interfaces you actually need. Initialize ~/.hermes, mount it at /opt/data, start the official nousresearch/hermes-agent:latest image with gateway run, and treat the API and dashboard ports as protected services rather than anonymous public endpoints.
Antihost offers VPS plans with one-click Hermes Agent, NVMe storage and a 14-day free trial.
This guide gives you a complete Compose deployment, explains what each setting does, and covers persistence, API authentication, dashboard binding, secrets, resource sizing, upgrades, backups, and the failure modes most likely to erase data or make the service unreachable.
As an Amazon Associate I earn from qualifying purchases.
Free tools Windows power users keep installed
One-click scans. No signup required.
What the Compose deployment runs
Hermes Agent is packaged as a Docker image. In the Compose pattern documented by the project, one service runs the gateway process and, when enabled, the dashboard service. Hermes keeps its operational state in /opt/data, including configuration, API keys, sessions, installed skills, memories, and logs. If that directory exists only inside a container, replacing the container replaces the state with it.
A bind mount connects a directory on the Docker host to /opt/data in the container. The example below uses ~/.hermes on the host. The image’s normal entrypoint remains in place; it uses s6-overlay to supervise the gateway and dashboard processes and to reap orphaned child processes.
#1 Best Overall
Requirements and sizing
Install Docker Engine and a Docker Compose implementation that supports the docker compose command. You need permission to create the host data directory, pull the image, publish the selected ports, and keep the host running for as long as the agent should be available.
| Use case | Documented capacity | Qualification |
|---|---|---|
| Hermes minimum | 1 GB RAM, 1 CPU core, 500 MB disk | Minimums listed in the official GitHub Docker guide for the 2026 Dinh2026/hermes-agent documentation. |
| Recommended baseline | 2–4 GB RAM, 2 CPU cores, 2+ GB disk | Baseline from the same 2026 guide; allow additional disk for logs, sessions, skills, and memories as your use grows. |
| Browser automation | At least 2 GB RAM | Specific guidance for browser automation; the minimum general profile may be insufficient. |
These figures describe the Hermes service, not the operating system, Docker daemon, database backups, or other applications on the host. Leave headroom for those components. Browser automation is the clearest reason to choose the recommended profile rather than the absolute minimum.
Initialize persistent storage once
Create the host directory before starting the Compose service, then run the setup wizard with the same mount that Compose will use. This makes the wizard write its configuration and credentials into the persistent location rather than into a temporary container layer.
-
Create the directory:
mkdir -p ~/.hermes -
Run the one-time setup wizard:
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup -
Complete the prompts for your provider credentials and other initial settings. The wizard writes API keys to
~/.hermes/.envon the host because that directory is mounted at/opt/data.
The --rm option removes the temporary setup container when the wizard exits. It does not remove the mounted ~/.hermes directory or the files created there.
Use this Docker Compose file
Save the following as compose.yaml (or docker-compose.yml) in a directory from which you will operate the service:
Recommended Free Tools
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
ports:
- "8642:8642" # gateway API and health endpoint
- "9119:9119" # dashboard when enabled
volumes:
- ~/.hermes:/opt/data
environment:
- HERMES_DASHBOARD=1
# Optional variable forwarding:
# - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
# - OPENAI_API_KEY=${OPENAI_API_KEY}
# - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
deploy:
resources:
limits:
memory: 4G
cpus: "2.0"Image and container lifecycle
nousresearch/hermes-agent:latest is the official image named in the deployment guide. The container_name gives the container a predictable name for inspection commands. restart: unless-stopped asks Docker to bring the service back after a crash or host restart, while still respecting an explicit stop.
command: gateway run starts the Hermes gateway under the image’s existing entrypoint. Do not replace the entrypoint merely to run this command. The default entrypoint supplies s6-overlay supervision for the gateway and dashboard and reaps orphaned child processes. Removing it changes process management and can allow zombie processes to accumulate.
Ports
Port 8642 is the gateway API and health endpoint. It is optional when Hermes is used only through chat platforms, but it is required by the dashboard and by external tools that call the API. Port 9119 is the dashboard’s default listener when the dashboard is enabled.
The short mappings in the example publish both ports according to Docker’s normal host binding behavior. If the dashboard or API is needed only from the same machine, bind the host side to loopback instead, for example 127.0.0.1:8642:8642 or 127.0.0.1:9119:9119. If another machine must connect, use a firewall or a private network and configure authentication before allowing access.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Volume and environment settings
~/.hermes:/opt/data is the persistence boundary. Keep this mapping unchanged across container replacements and upgrades. The HERMES_DASHBOARD=1 variable enables the dashboard. The commented variables show optional forwarding for provider and chat credentials; uncomment only the variables you actually supply.
The Compose resource declaration limits the service to 4 GB of memory and 2.0 CPU units in environments that enforce the deploy.resources.limits stanza. Those values are a ceiling, not a guarantee that Hermes will receive that capacity. Choose a limit compatible with the host and your workload; browser automation in particular needs at least 2 GB of RAM according to the project’s guidance.
Start the service and verify it
-
From the directory containing the Compose file, start Hermes in detached mode:
docker compose up -d -
Follow the service output while it initializes:
docker compose logs -f -
Watch for the gateway and, if enabled, dashboard services to start without repeated restarts. The supervised gateway output is also written below the Hermes data volume.
DriversOutdated Drivers Are Slowing You DownPerformancePC Slower Than It Used to Be?DriversCrashes, No Sound, or Screen Glitches?Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Confirm that the container is running:
docker compose ps -
Check the host ports from the machine or network location that should reach them. A failure can mean the service is still starting, the port is already occupied, the API server is disabled, or a firewall is blocking the connection.
Do not delete ~/.hermes while diagnosing a startup issue. It contains the setup-generated .env, sessions, skills, memories, and logs that you may need to recover or inspect.
Configure the API without exposing an unauthenticated endpoint
Publishing a Docker port is not the same as enabling and securing Hermes’s API server. To expose the API beyond container loopback, set all three documented variables:
API_SERVER_ENABLED=trueAPI_SERVER_HOST=0.0.0.0API_SERVER_KEYset to a value of at least eight characters
You can add them under environment in Compose:
environment:
- HERMES_DASHBOARD=1
- API_SERVER_ENABLED=true
- API_SERVER_HOST=0.0.0.0
- API_SERVER_KEY=${HERMES_API_SERVER_KEY}In this example, Compose substitutes HERMES_API_SERVER_KEY from the shell or Compose’s variable file. Keep the key out of the YAML file if that file will be shared or committed. The documentation warns that opening the API port on an internet-facing machine is a security risk. Prefer a private network, host firewall, or loopback-only binding when external access is unnecessary.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When port 8642 is actually needed
A chat-only deployment can leave the API unpublished if no dashboard or external integration needs it. The dashboard depends on the gateway API, and external tools need the API port to make requests. Decide this before opening a firewall rule; a published port that no client uses only increases the attack surface.
Enable and protect the dashboard
Set HERMES_DASHBOARD=1 to enable the dashboard. It listens on port 9119 by default, so the Compose mapping 9119:9119 makes that listener reachable through the host’s published port subject to your network and firewall rules.
Current hardened releases require an authentication provider when the dashboard is bound to a non-loopback address. Do not treat the dashboard as a public administrative site simply because it loads in a browser. If you need remote access, configure the required authentication provider, restrict the network path, and avoid exposing the port directly to the open internet. For a local-only dashboard, publish it on loopback and access it from the Docker host or through an authenticated private tunnel.
Choose a secrets workflow
The setup wizard stores keys in /opt/data/.env, which appears as ~/.hermes/.env on the host. That is convenient for a single host, but protect the directory with the host’s normal file permissions and backups because it contains credentials as well as operational state.
For CI, a secrets manager, or another workflow that should not write keys to disk, pass variables directly into the container. Directly supplied environment variables override values loaded from /opt/data/.env. This precedence lets an operator keep a stable data volume while replacing a credential at deployment time:
docker compose run --rm
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
hermes gateway runUse the same principle in the Compose service by referencing host variables with ${VARIABLE_NAME}. Avoid putting real keys in a file that will be checked into source control, pasted into issue reports, or printed in diagnostic output.
Best Value
Persistence, permissions, and safe replacement
What must survive replacement
The mounted directory contains the state that matters: configuration, provider keys, sessions, skills, memories, and logs. A replacement created with the same ~/.hermes:/opt/data mount sees that state again. A container started without the mount sees a new, empty data area and may appear to have lost configuration even though the old host files still exist.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →NAS and shared-storage permissions
Permission errors are common when ~/.hermes is on a NAS or another shared mount. Align the container’s user and group IDs with the host owner using the documented PUID/PGID or HERMES_UID/HERMES_GID settings. The exact values depend on the owner of the mounted directory; identify that owner on the host rather than guessing.
Back up the data directory
Back up ~/.hermes as a unit, including hidden files such as .env. Stop or quiesce writes when taking a filesystem-level snapshot if your storage system requires consistency. Store backup copies separately from the Docker host and test that you can restore the directory with the same ownership and mount path.
Upgrade Hermes without discarding state
Pull the newer image and recreate the service:
docker compose pull
docker compose up -dThe bind-mounted data directory is preserved during this process. Hermes can perform non-interactive configuration migrations during startup, so watch the logs after the upgrade and keep a backup made before changing versions. If the container repeatedly restarts, inspect the migration or permission messages before rolling back the image.
Using the mutable :latest tag follows the official example but means a future pull can change the image. For a tightly controlled production rollout, record the image digest you deployed and update deliberately; the project’s documented Compose example itself uses latest.
Compare the practical deployment variants
| Decision axis | Persistent Compose deployment | Disposable container | Compose with dashboard |
|---|---|---|---|
| Persistence model | Bind host ~/.hermes to /opt/data; state survives replacement. |
No durable mount; container-local state disappears with removal. | Same bind mount; dashboard shares the persistent Hermes state. |
| Exposure surface | Gateway port only if you publish and enable it. | Usually limited to the process invocation; no retained service state. | Gateway on 8642 plus dashboard on 9119 when both are published. |
| Process lifecycle | Default s6-overlay entrypoint supervises services. | Replacing the entrypoint removes that supervision. | Default supervision is especially important because gateway and dashboard run together. |
| Secret handling | Setup writes /opt/data/.env; direct environment variables can override it. |
Secrets may vanish with the container unless mounted or injected. | Use an injected API key and dashboard authentication for remote access. |
| Resource allocation | Compose example declares 4 GB memory and 2.0 CPU limits. | Capacity depends on the one-off Docker invocation. | Plan at least 2 GB RAM for browser automation and use the documented baseline for general workloads. |
The persistent Compose deployment is the sensible default for a continuously running Hermes installation. A disposable run is useful for experiments or setup, not for an agent whose sessions, memories, and skills must survive.
Troubleshoot by symptom
Files or settings disappear after a restart
- Run
docker compose configand verify that the service contains the intended volume mapping. - Confirm that the host directory is the same one used by the setup command and the Compose file.
- Check that the mapping ends at
/opt/data, not a similarly named directory. - Inspect the host directory, including hidden files, for
.envand the expected Hermes state.
If the mount is correct but files are unreadable, resolve ownership with the documented UID/GID settings before recreating the container.
The API cannot be reached
- Check
docker compose logs -ffor API startup errors. - Verify
API_SERVER_ENABLED=truewhen an API client needs the endpoint. - Verify
API_SERVER_HOST=0.0.0.0when the client is outside the container. - Confirm that
API_SERVER_KEYis present and at least eight characters long. - Check the host-side published port, firewall rules, and whether another process already occupies port
8642.
A container can be healthy while an API request fails because the server is disabled, bound only to loopback, or blocked before it reaches Docker.
The dashboard does not load
- Confirm
HERMES_DASHBOARD=1is in the running container’s environment, not only in an unused Compose file. - Confirm port
9119is published and not already occupied on the host. - Ensure the gateway API is configured when the dashboard requires it.
- If binding beyond loopback, configure the authentication provider required by current hardened releases.
- Read the supervised service output for startup or permission errors.
The container repeatedly restarts
- Follow logs during a fresh start with
docker compose logs -f hermes. - Check that the mounted directory is writable by the container user.
- Review API and provider variables for malformed values.
- Make sure the host has enough memory and CPU for the selected limits and workload.
- Do not remove the default entrypoint as a workaround; doing so removes the process supervision that the image expects.
Setup succeeds but the running service has different credentials
Compare the environment passed by Compose with ~/.hermes/.env. Direct container variables take precedence over the file in /opt/data. An old shell variable or CI secret can therefore override the value you entered during setup. Clear or correct the higher-precedence variable, then recreate the service.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Quick Recap
Preflight checklist
- Storage:
~/.hermesexists, is backed up, and is mounted at/opt/data. - Initialization: the setup wizard has run once with the same mount.
- Image: the service uses
nousresearch/hermes-agent:latestor another deliberately selected image reference. - Entrypoint: the image’s default entrypoint is intact and
command: gateway runis used. - Ports: publish
8642only when the API, dashboard, or an external tool needs it; publish9119only when the dashboard is enabled. - API security: remote API use has
API_SERVER_ENABLED=true,API_SERVER_HOST=0.0.0.0, and an eight-character-or-longer key, plus network restrictions. - Dashboard security: non-loopback access has the required authentication provider.
- Secrets: decide whether keys belong in the mounted
.envor injected environment variables, and remember that injected values override the file. - Capacity: the host meets at least the documented minimums, with 2 GB or more of RAM for browser automation.
- Operations: logs are monitored after startup and upgrades, and the data directory is backed up before migrations.
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.
