---
title: Hermes / Atlas Architecture Diagram
type: architecture-note
created: 2026-05-29
tags:
  - hermes
  - atlas
  - architecture
  - homelab
  - docker
  - kubernetes
---

# Hermes / Atlas Architecture Diagram

A vector architecture diagram was created for the current Hermes/Atlas agent setup, host Docker/systemd AI services, AgentMon stack, and k0s Kubernetes homelab services.

## Primary artifacts

- SVG vector source: `/home/will/diagrams/hermes-atlas-architecture.svg`
- High-resolution PNG export: `/home/will/diagrams/hermes-atlas-architecture-6400.png`
- HTML presentation page: `/home/will/hermes-atlas-architecture.html`
- Maintenance README: `/home/will/diagrams/README-hermes-atlas-architecture.md`
- SVG extraction script: `/home/will/diagrams/extract-svg.py`

## Why SVG

The diagram is kept as standalone SVG so it can be:

- scaled without resolution loss,
- edited later in Inkscape, Figma, Illustrator, VS Code, or a browser-aware SVG editor,
- exported to PNG at any resolution,
- updated from the HTML presentation page when the layout changes.

## Current coverage

### Hermes / Atlas agent plane

- Telegram, Discord, email, and local UI entrypoints.
- Default Hermes gateway process.
- Hermes state/context layer: `state.db`, sessions, memory, skills, config, auth pools.
- Kanban dispatcher configured inside the gateway.
- Specialist profiles including engineer, reviewer, orchestrator, researcher/writer, ops, and glm-simple.
- Cron jobs and webhook subscriptions.
- n8n/webhook producers for reminders, diary nudges, medication reminders, and Pi run results.

### Host AI / automation plane

- Docker Compose services under `/home/will/lab/swarm`:
  - Brave Search MCP `:18802`
  - SearXNG `:18803`
  - Whisper GPU `:18801`
  - Whisper CPU `:18811`
  - Kokoro TTS `:18805`
  - n8n `:18808`
  - LiteLLM defined on `:18804`, but not running in the captured snapshot
- User systemd services:
  - `llama-server.service` on `:18806`
  - `ollama.service` on `:18807`
- AgentMon:
  - ingest `:8080`
  - query API `:8081`
  - UI `:8082`
  - Postgres and NATS backing services

### k0s Kubernetes plane

- Cluster: `k0s-cluster`
- Nodes:
  - `pi50` control-plane, `192.168.153.210`
  - `pi51` worker, `192.168.153.206`
  - `pi3` worker, `192.168.153.184`
- Main layers:
  - ArgoCD GitOps
  - MetalLB
  - HAProxy, nginx, and Traefik ingress
  - Tailscale exposure
  - atlas-control
  - gitea
  - minio
  - home-assistant
  - monitoring
  - pihole2
  - plex
  - tools
  - backup stores

## Refresh workflow

For simple edits, edit the SVG directly:

```bash
inkscape /home/will/diagrams/hermes-atlas-architecture.svg
```

For larger layout/content edits, edit the HTML page and regenerate the SVG:

```bash
$EDITOR /home/will/hermes-atlas-architecture.html
/home/will/diagrams/extract-svg.py
```

To export a fresh high-resolution PNG from the SVG:

```bash
chromium --headless --disable-gpu --no-sandbox --hide-scrollbars \
  --window-size=3200,2240 \
  --force-device-scale-factor=2 \
  --screenshot=/home/will/diagrams/hermes-atlas-architecture-6400.png \
  file:///home/will/diagrams/hermes-atlas-architecture.svg
```

## Refresh checklist

When updating the diagram from live infrastructure, re-check:

- Hermes profile roster and gateway status.
- Active Kanban worker processes.
- Cron jobs and webhook subscriptions.
- `/home/will/lab/swarm/docker-compose.yaml` services and currently running containers.
- User systemd service units for local model endpoints.
- AgentMon containers and exposed ports.
- k0s nodes, load balancer services, ArgoCD app sync/health status, and selected namespaces.
- Deliberate dormant or degraded states, such as OpenClaw remaining dormant or LiteLLM being defined but not running.

## Source commands used

The initial diagram was based on live read-only checks:

```bash
docker ps
cd /home/will/lab/swarm && docker compose config --services
cd /home/will/lab/swarm && make ps
systemctl --user is-active llama-server.service ollama.service llama-swap.service
systemctl --user cat llama-server.service
systemctl --user cat ollama.service
ss -ltnp
hermes profile list
hermes cron list
hermes webhook list
kubectl config get-contexts
kubectl get nodes -o wide
kubectl get ns
kubectl get svc -A --field-selector spec.type=LoadBalancer -o wide
kubectl get applications -n argocd
kubectl get deploy,sts,ds,pods,svc,ingress -n <namespace>
```

Secrets were intentionally omitted.

## Related

- [[Atlas]]
- [[Hermes]]
- [[Inbox/Inbox]]
