Hermes Agent Docker guide

First-run shape

The official Docker guide uses a mounted data directory so config, API keys, sessions, skills, and memories survive image updates.

mkdir -p ~/.hermes

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

Safer deployment checklist

• Use a dedicated host directory per profile or deployment.
• Avoid mounting broad home directories unless the workflow requires it.
• Keep .env ownership and backup rules explicit.
• Record the image tag or digest used for production.
• Test updates by pulling the new image and recreating the container against a backed-up data directory.

Running on a VPS

Docker mode distinction

There are two Docker decisions. You can run Hermes Agent itself inside Docker, or you can configure Docker as the terminal backend while Hermes runs on the host. The official Docker page focuses on running Hermes inside a container and stores user data through a host mount at /opt/data.

Agent Guide treats both paths as security decisions. A container boundary helps, but mounted files, exposed ports, forwarded environment variables, and API keys still define the real blast radius.

Production-like Docker checklist

• Use a dedicated host data directory for each profile or deployment.
• Bind API ports to localhost unless external access is required and protected.
• Generate a strong API server key before enabling external API access.
• Back up the host-mounted data directory before pulling a new image.
• Keep dashboard exposure separate from chat-platform gateway exposure.

When to use Docker Compose

Use Docker Compose when you want a repeatable service definition, checked-in infrastructure notes, and a cleaner upgrade path than remembering a long docker run command.

Agent Guide judgment

Use Docker when you want repeatability and a clearer boundary, not because containers magically make agent work safe. The real risk is the combination of mounted files, forwarded environment variables, exposed ports, and unattended workflows.

For most production-like experiments, prefer a narrow data mount and localhost-only ports before any public gateway, reverse proxy, or team messaging integration.

Docker smoke test

1. Start the container with a dedicated data directory, not a broad home mount.
2. Confirm logs show startup without provider-key or path errors.
3. Run one harmless task and inspect which host files were mounted.
4. Back up the data directory before testing updates or persistent workflows.

Two Docker decisions

Docker resource reality

The official Docker docs call browser automation the most memory-hungry feature and give higher memory guidance when browser tools are active. That matters for VPS advice: a small server may be fine for a gateway or text workflow, then become unreliable once browser automation enters the workflow.