somratpro/huggingmes

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.