diff --git a/family/how-to/hermes-docker-kraken.md b/family/how-to/hermes-docker-kraken.md
index a8069da1..af9290cf 100644
--- a/family/how-to/hermes-docker-kraken.md
+++ b/family/how-to/hermes-docker-kraken.md
@@ -1,7 +1,7 @@
 ---
 title: Hermes Docker on Kraken
 created: '2026-05-23'
-updated: '2026-05-29'
+updated: '2026-06-04'
 type: tech
 namespace: personal
 tags: [hermes, docker, kraken, infra, how-to]
@@ -15,23 +15,78 @@ related:
 
 ## Key Rule
 
-Hermes runs via **`docker run`**, NOT `docker compose`. No compose file.
+Hermes runs via **`docker compose`** from the `hermes-build/` directory.
 
-## Launch Pattern
+## Directory Layout (on Kraken)
 
-```bash
-docker run -d \
-  --name hermes \
-  --restart unless-stopped \
-  -v ~/.hermes:/root/.hermes \
-  ... \
-  hermes-image:tag
+```
+/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
 ```
 
-(Add actual flags from the running container: `docker inspect hermes`)
+## 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
 
-- Using `docker run` keeps restart behavior explicit
-- No compose means no accidental `docker compose down` wipes it
-- Config/memory volume: `~/.hermes` on Kraken host
+- `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)