Tutorial 16: Docker Deployment | Easy Understand Hermes Agent

This is part of the Hermes Agent official tutorial series. View all tutorials

Think of Docker like a moving box for your AI assistant. You pack up Hermes (and all its belongings—settings, memories, API keys) into a standardized container, and it runs identically on any computer that has Docker installed. Today, we’ll learn how to ship that box and keep it running 24/7.

What You’re Actually Doing

There are two ways Docker and Hermes work together, but this tutorial focuses on the first: running Hermes inside a container. The magic trick? Your data (config, sessions, skills) lives in a folder on your computer (~/.hermes), while the container itself is just a temporary shell. You can delete the container, pull a newer version, and start again—your data stays safe on the host.

Step 1: Create a Data Folder

First, make a home for Hermes’ memories on your computer:

mkdir -p ~/.hermes

This folder will hold everything important. Think of it as the assistant’s diary—it never gets thrown away.

Step 2: Run the Setup Wizard (One Time Only)

Now, start the container interactively to configure your API keys:

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

-it means “interactive mode”—you’ll see prompts.
--rm cleans up the container after you finish (your data stays in ~/.hermes).
-v ~/.hermes:/opt/data connects your folder to the container’s storage.

You’ll be asked for API keys and to set up a chat system (Telegram, Discord, etc.). Do this once, and you’re done.

⚠️ Browser Console Warning: If you’re on a VPS (like Hetzner), don’t paste commands into the browser-based console. It mangles characters like : and @, silently corrupting your setup. Use SSH (ssh root@<host>) instead. If you must use the browser, type everything manually and double-check every symbol.

Step 3: Run Hermes as a Background Gateway

Once configured, you want Hermes to run forever, listening for messages from your chat apps. Use this command:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Breaking it down:

-d runs it in the background (like closing the lid on a laptop but leaving it on).
--name hermes gives the container a friendly name.
--restart unless-stopped means Docker auto-restarts it if it crashes or if your computer reboots.
-p 8642:8642 opens a port for the optional API server and dashboard. Skip this if you only use chat apps—but keep it if you want to connect external tools.

Step 4: What Happens If It Crashes?

Inside the official image, Hermes uses a tool called s6-overlay that acts like a babysitter. If the gateway process crashes, it restarts within seconds—without killing the container. The container itself stays alive, and docker logs hermes shows you what’s happening.

If you want the old behavior (container exits when the gateway exits), you can opt out by adding --no-supervisor to the command. But for most beginners, the default is perfect.

Extra Tip: Nous Portal

If you use Nous Portal, run this once inside the container:

hermes setup --portal

The refresh token will be saved in your ~/.hermes folder, so you won’t need to repeat it.

Summary

You now have a self-healing, always-on AI assistant that survives updates and crashes. The key insight: your data is the host, the container is just a disposable wrapper. Upgrading is as simple as pulling a new image and re-running Step 3.

Next up: In Tutorial 17, we’ll explore how to use Docker as a sandbox for running individual commands securely—so your agent can execute code without touching your main system. Stay tuned!