# somratpro/huggingmes architecture

> Architecture diagram of the GitHub repository somratpro/huggingmes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/somratpro/huggingmes
- Repository: https://github.com/somratpro/huggingmes

## Overview

1. **What this repo is**
   HuggingMes is not the Hermes agent itself; it is a Dockerized wrapper and bootstrap layer around the external `hermes-agent` runtime. Its job is to turn a Hugging Face Space into a self-hosted AI gateway with auth, telemetry, persistence, Telegram connectivity, and optional network workarounds.

2. **Top-level runtime boundary**
   The entire system runs as a single containerized service on port `7861` in Hugging Face Spaces. Inside that container, HuggingMes fronts multiple internal surfaces: the dashboard at `/`, the Hermes UI at `/app/`, the OpenAI-compatible API at `/v1/*`, a JupyterLab terminal at `/terminal/`, and a `/health` endpoint.

3. **Bootstrap and process orchestration**
   `start.sh` is the main entrypoint and likely coordinates startup order, env normalization, process launch, and restart supervision. The README indicates the gateway, dashboard, health server, and JupyterLab are monitored and restarted automatically if they exit, so this layer is the operational control plane for the container.

4. **Gateway / reverse-proxy layer**
   The central architectural pattern is a secure gateway in front of Hermes. It enforces `GATEWAY_TOKEN` on `/app/` and `Authorization: Bearer <token>` on `/v1/*`, acting as the auth and routing boundary between users and the underlying agent runtime. This is the main “front door” of the system.

5. **Hermes agent runtime**
   Hermes provides the actual agent behavior: chat, tools, memory, workflows, model selection, and provider integration. HuggingMes does not reimplement that core logic; instead it maps environment variables into Hermes at boot and then proxies access to Hermes’ UI/API. Provider setup can also happen later through Hermes-native configuration (`hermes model`, `config.yaml`).

6. **Model/provider configuration flow**
   The repo supports two provider paths: direct startup mapping from `LLM_MODEL` + `LLM_API_KEY`, and Hermes-native providers configured after launch. The direct path translates one generic secret into provider-specific env vars such as `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, and others. This means provider selection is part of startup config, not an application UI state.

7. **Persistence and backup subsystem**
   `hermes-sync.py` is the persistence engine. It syncs workspace and agent state to a private Hugging Face Dataset, typically every 600 seconds, using `HF_TOKEN`. This creates a clear separation between ephemeral container storage and durable backup storage, and is how chat/config/session state survives rebuilds or Space restarts.

8. **Connectivity repair and outbound proxying**
   The Cloudflare scripts are a separate infrastructure automation layer. `cloudflare-proxy-setup.py` provisions a Worker proxy for blocked outbound traffic, especially Telegram and some provider backends. `cloudflare-keepalive-setup.py` provisions a cron-triggered Worker that pings `/health` to reduce sleep time on free tiers. These are optional but materially affect network topology.

9. **Telegram integration path**
   Telegram is treated as an external ingress channel into Hermes. The bot token and allowed-user list gate access, and the README suggests webhook mode by default, with Cloudflare proxy support when Hugging Face outbound restrictions interfere. This makes Telegram a secondary interface that depends on the same gateway/runtime but uses separate transport and access control.

10. **Health and lifecycle management**
   `health-server.js` exposes a lightweight readiness/uptime endpoint used by Hugging Face and the keep-alive worker. This is distinct from the main agent API: it is for liveness, not conversation traffic. That separation is important for diagrams because the container has a health plane and an application plane.

11. **Terminal and debugging surface**
   The JupyterLab terminal at `/terminal/` is a privileged operational subsystem, enabled when `GATEWAY_TOKEN` is set and optionally disabled with `DEV_MODE=false`. It gives full shell access for `hermes` commands, package installation, and debugging, so it should be drawn as an admin-only side channel rather than part of the user-facing app flow.

12. **Ephemeral customization helpers**
   `env-builder.html` and `env-builder.js` appear to support environment-variable setup or generation, which fits the repo’s emphasis on boot-time configuration over custom code changes. They are helper assets, not core runtime services, but they reinforce that most behavior is driven by secrets and env vars.

13. **Deployment model**
   `Dockerfile` and `docker-compose.yml` define the local and Hugging Face deployment story. The repo is designed to be reproducible as a container image, with Space-specific secrets injected at runtime. In other words, the architecture is “container-first, config-driven, externally wired.”

14. **Primary data flows**
   The main flows are: user/browser or Telegram request → gateway/auth → Hermes UI/API → provider backend; and container state → sync engine → Hugging Face Dataset backup. A separate operational flow is `/health` → keep-alive worker / platform probes, while Cloudflare automation modifies network reachability for outbound traffic and Telegram ingress.

Main entry points: [`start.sh`](https://github.com/somratpro/huggingmes/blob/main/start.sh) (Startup), [`hermes-sync.py`](https://github.com/somratpro/huggingmes/blob/main/hermes-sync.py) (State Sync), [`cloudflare-proxy-setup.py`](https://github.com/somratpro/huggingmes/blob/main/cloudflare-proxy-setup.py) (Proxy Setup), [`cloudflare-keepalive-setup.py`](https://github.com/somratpro/huggingmes/blob/main/cloudflare-keepalive-setup.py) (Keepalive Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Container Runtime"]
  node_node_container["HuggingMes<br/>single-container app"]
  node_node_gateway["Gateway<br/>auth reverse-proxy"]
  node_node_dashboard["Dashboard<br/>web UI"]
  node_node_hermes_ui["Hermes UI<br/>agent frontend"]
  node_node_api["OpenAI API<br/>chat API"]
  node_node_hermes["Hermes Agent<br/>agent runtime"]
  node_node_model_map["Model Map<br/>env translation"]
end

subgraph group_group_ops["Operations"]
  node_node_start["Startup<br/>bootstrap shell<br/>[start.sh]"]
  node_node_terminal["Terminal<br/>admin shell"]
  node_node_health["Health Server<br/>liveness endpoint<br/>[health-server.js]"]
  node_node_container_build["Container Build<br/>docker packaging"]
  node_node_env_builder["Env Builder<br/>setup helper<br/>[env-builder.html]"]
end

subgraph group_group_persistence["Persistence"]
  node_node_sync["State Sync<br/>backup worker<br/>[hermes-sync.py]"]
  node_node_hf_dataset[("HF Dataset<br/>durable storage")]
end

subgraph group_group_network["Network Extensions"]
  node_node_cf_proxy["Proxy Setup<br/>worker provisioner"]
  node_node_cf_keepalive["Keepalive Setup<br/>worker cron setup"]
  node_node_telegram(("Telegram<br/>external ingress"))
end

node_node_container_build -->|"builds"| node_node_container
node_node_start -->|"launches"| node_node_gateway
node_node_start -->|"enables"| node_node_terminal
node_node_start -->|"starts"| node_node_health
node_node_start -->|"starts"| node_node_sync
node_node_start -.->|"optional"| node_node_cf_proxy
node_node_start -.->|"optional"| node_node_cf_keepalive
node_node_gateway -->|"routes /"| node_node_dashboard
node_node_gateway -->|"routes /app/"| node_node_hermes_ui
node_node_gateway -->|"routes /v1/*"| node_node_api
node_node_gateway -->|"fronts"| node_node_hermes
node_node_model_map -->|"configures"| node_node_hermes
node_node_hermes_ui -->|"uses"| node_node_hermes
node_node_api -->|"invokes"| node_node_hermes
node_node_sync -->|"backs up to"| node_node_hf_dataset
node_node_cf_proxy -.->|"unblocks"| node_node_telegram
node_node_cf_keepalive -->|"pings"| node_node_health
node_node_telegram -.->|"enters via"| node_node_gateway
node_node_env_builder -.->|"prepares env"| node_node_start
node_node_terminal -.->|"administers"| node_node_hermes

click node_node_start "https://github.com/somratpro/huggingmes/blob/main/start.sh"
click node_node_health "https://github.com/somratpro/huggingmes/blob/main/health-server.js"
click node_node_sync "https://github.com/somratpro/huggingmes/blob/main/hermes-sync.py"
click node_node_cf_proxy "https://github.com/somratpro/huggingmes/blob/main/cloudflare-proxy-setup.py"
click node_node_cf_keepalive "https://github.com/somratpro/huggingmes/blob/main/cloudflare-keepalive-setup.py"
click node_node_container_build "https://github.com/somratpro/huggingmes/tree/main/Dockerfile"
click node_node_env_builder "https://github.com/somratpro/huggingmes/blob/main/env-builder.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_container,node_node_gateway,node_node_dashboard,node_node_hermes_ui,node_node_api,node_node_hermes,node_node_model_map toneBlue
class node_node_start,node_node_terminal,node_node_health,node_node_container_build,node_node_env_builder toneAmber
class node_node_sync,node_node_hf_dataset toneMint
class node_node_cf_proxy,node_node_cf_keepalive,node_node_telegram toneRose
```

## Components

### Container Runtime

Main service launched inside the Hugging Face Space container.

- **HuggingMes**: single-container app · Dockerized wrapper around the Hermes runtime running as one service on port 7861.
- **Gateway**: auth reverse-proxy · Secures the app and API, routing requests to the right internal surface.
- **Dashboard**: web UI · Root surface for the HuggingMes control experience.
- **Hermes UI**: agent frontend · Underlying Hermes web interface exposed under /app/.
- **OpenAI API**: chat API · OpenAI-compatible /v1/* interface for agent and tool access.
- **Hermes Agent**: agent runtime · External agent runtime providing chat, tools, memory, and workflows.
- **Model Map**: env translation · Maps startup model settings into provider-specific credentials and Hermes config.

### Operations

Bootstrap, lifecycle, and admin surfaces for the container.

- [Startup](https://github.com/somratpro/huggingmes/blob/main/start.sh): bootstrap shell · Entry script that normalizes env, starts services, and supervises restarts. · `start.sh`
- **Terminal**: admin shell · JupyterLab terminal for privileged debugging and Hermes CLI access.
- [Health Server](https://github.com/somratpro/huggingmes/blob/main/health-server.js): liveness endpoint · Lightweight readiness and uptime endpoint used by probes and keep-alive checks. · `health-server.js`
- [Container Build](https://github.com/somratpro/huggingmes/tree/main/Dockerfile): docker packaging · Dockerfile and compose-based packaging for local and Space deployment. · `Dockerfile`
- [Env Builder](https://github.com/somratpro/huggingmes/blob/main/env-builder.html): setup helper · Helper assets for generating or preparing environment variables. · `env-builder.html`

### Persistence

Durable sync and backup path for workspace and agent state.

- [State Sync](https://github.com/somratpro/huggingmes/blob/main/hermes-sync.py): backup worker · Synchronizes workspace and agent state to a private Hugging Face Dataset. · `hermes-sync.py`
- **HF Dataset**: durable storage · Remote backup store for persisted workspace and configuration state.

### Network Extensions

Optional connectivity and ingress workarounds.

- [Proxy Setup](https://github.com/somratpro/huggingmes/blob/main/cloudflare-proxy-setup.py): worker provisioner · Creates Cloudflare Worker proxy support for blocked outbound traffic and Telegram paths. · `cloudflare-proxy-setup.py`
- [Keepalive Setup](https://github.com/somratpro/huggingmes/blob/main/cloudflare-keepalive-setup.py): worker cron setup · Creates a cron-triggered Worker that pings health to reduce sleep on free tiers. · `cloudflare-keepalive-setup.py`
- **Telegram**: external ingress · Secondary user ingress channel that can route into the Hermes runtime.

## Connections

- Container Build → HuggingMes: builds · Packages the service as a reproducible container image.
- Startup → Gateway: launches · Bootstraps the gateway and monitored services.
- Startup → Terminal: enables · Starts the admin terminal when configured.
- Startup → Health Server: starts · Brings up the liveness endpoint for probes and keep-alive traffic.
- Startup → State Sync: starts · Runs the background state synchronization worker.
- Startup → Proxy Setup: optional · Can provision Cloudflare proxy support during setup.
- Startup → Keepalive Setup: optional · Can provision keep-alive infrastructure during setup.
- Gateway → Dashboard: routes / · Serves the main dashboard at the root path.
- Gateway → Hermes UI: routes /app/ · Forwards authenticated users to the Hermes web UI.
- Gateway → OpenAI API: routes /v1/* · Exposes the OpenAI-compatible API behind bearer token auth.
- Gateway → Hermes Agent: fronts · Acts as the security boundary in front of the Hermes runtime.
- Model Map → Hermes Agent: configures · Translates generic startup model settings into Hermes/provider config.
- Hermes UI → Hermes Agent: uses · The UI is backed by the Hermes runtime.
- OpenAI API → Hermes Agent: invokes · API requests are handled by the Hermes agent runtime.
- State Sync → HF Dataset: backs up to · Persists workspace and agent state to remote durable storage.
- Proxy Setup → Telegram: unblocks · Improves outbound reachability and Telegram connectivity when needed.
- Keepalive Setup → Health Server: pings · Uses the health endpoint to keep the container warm.
- Telegram → Gateway: enters via · Telegram traffic ultimately lands in the same secured runtime boundary.
- Env Builder → Startup: prepares env · Supports boot-time secret and variable setup.
- Terminal → Hermes Agent: administers · Provides shell-level access for Hermes commands and debugging.