---
title: Hermes Docker on Kraken
created: '2026-05-23'
updated: '2026-06-04'
type: tech
namespace: personal
tags: [hermes, docker, kraken, infra, how-to]
related:
  - "[[tech/kraken-network]]"
  - "[[concepts/hermes-deployment-patterns]]"
  - "[[tech/hermes-kraken-api]]"
---

# Hermes Docker on Kraken

## Key Rule

Hermes runs via **`docker compose`** from the `hermes-build/` directory.

## Directory Layout (on Kraken)

```
/srv/.../docker/
├── hermes-build/          ← build + run from here
│   ├── Dockerfile         ← clones upstream NousResearch/hermes-agent
│   ├── docker-compose.yml ← canonical compose file
│   ├── config.yaml        ← unused at build time (runtime config is in hermes/config/)
│   └── .env               ← all secrets/API keys (sourced by compose)
└── hermes/
    └── config/            ← mounted as /opt/data (HERMES_HOME) inside container
```

## Compose File (`hermes-build/docker-compose.yml`)

```yaml
services:
  kraken:
    build:
      context: .
      dockerfile: Dockerfile
    image: hermes-kraken:latest
    container_name: hermes-kraken
    stdin_open: true
    tty: true
    restart: unless-stopped
    volumes:
      - /srv/.../docker/hermes/config:/opt/data
      - /home/kraken/obsidian:/vault:rw
    environment:
      - HERMES_ALLOW_ROOT_GATEWAY=1
    env_file:
      - .env
    command: gateway
    network_mode: host
```

## Managing the Container

```bash
cd /srv/dev-disk-by-uuid-49e8f586-3839-4c5d-a1e1-58bfc3579ade/docker/hermes-build

docker compose up -d          # start
docker compose down           # stop
docker compose pull           # pull new image (if from registry)
docker compose build          # rebuild image from Dockerfile
docker compose restart        # restart
docker compose logs -f        # follow logs
```

## Image

Built locally from `Dockerfile` — clones **upstream** `NousResearch/hermes-agent`
(`--depth=1` from `main`). Not a custom fork. To update Hermes:

```bash
cd /srv/.../docker/hermes-build
docker compose build --no-cache
docker compose up -d
```

## Volumes

| Host path | Container path | Purpose |
|-----------|----------------|---------|
| `hermes/config/` | `/opt/data` | `HERMES_HOME` — config, sessions, skills, memory |
| `/home/kraken/obsidian` | `/vault` | Obsidian vault read/write access |

## Notes

- `network_mode: host` — port 8642 is directly on the Kraken host, no port mapping needed
- `HERMES_ALLOW_ROOT_GATEWAY=1` — required since container runs as root
- All secrets in `hermes-build/.env` (not committed)