saegfred/spedition

Run your own AI agent with a chat interface on Hugging Face Spaces — for free.

This is not original work. It combines three great open-source projects into one easy-to-deploy package: - Hermes Agent by Nous Research — the AI brain - Hermes WebUI by @nesquena — the chat interface - HuggingMes by @somratpro — the Hugging Face wrapper

All credit goes to the original creators. This repo just wires them together.

Quick Setup (5 minutes)

1. Duplicate the Space


Click the badge above, name your space → pick CPU Basic (Free) → and keep it public(else the .hf.space urls won't work).

2. Add Your Secrets

Go to Settings → Variables and secrets in your new Space and add these:

3. Add an AI Provider

Your agent needs an AI model to talk to. Add one of these API keys as a secret (or configure later in the dashboard):

Or configure manually later at /hm/app/config inside your Space.

4. Start It Up

Hit Restart this Space in Hugging Face. Wait 5–8 minutes for the first build.

When you see this in the Logs tab, you're ready:

HuggingMes + Hermes WebUI router listening on 0.0.0.0:7861

Open your Space URL (https://your-name.hf.space) in a new tab, enter your GATEWAY_TOKEN, and start chatting. Open Hermes Dashboard from here (https://f4b404-hermes.hf.space/hm/app)

Pro tip: Bookmark the direct *.hf.space URL — it works better on mobile than the Hugging Face embed.

What You Get

Your Data Is Safe

When HF_TOKEN is set:

• —All your chats, files, settings, and agent memory are backed up to a private Hugging Face Dataset within seconds of each change (change-driven, capped at 60 s)
• —If the Space restarts, everything comes back exactly as you left it

Common Issues

Want It on Your Phone?

Use the same (https://your-name.hf.space) url in android and then you can install it as Progressive Web App(PWA) or just use the same url on any browser for normal chat using the web.

🔧 Advanced Setup & Technical Details

Skip this section if you just want to chat. The steps above are enough to get started. This part is for developers, power users, and anyone who wants to customize or understand the internals.

Optional Secrets (Power Users)

Configure LLM Provider via Config Editor

### ⚠️ Provider keys go in HF Space Secrets, not the dashboard's Env tab The Hermes dashboard exposes an "Env" editor that writes to /opt/data/.env inside the container. *That file is not backed up to your HF Dataset. On every Space sleep / rebuild the container's filesystem is wiped, the `.env` is gone, and your `OLLAMA_API_KEY` / `OPENROUTER_API_KEY` / `ANTHROPIC_API_KEY` / etc. disappear with it. The Space then 500s on the first chat with `Provider 'X' is set in config.yaml but no API key was found`. Always add provider keys as HF Space Secrets* (Settings → Variables and secrets → New secret). HF injects them as env vars at boot, never writes them to disk on the Space, and they survive every restart. Use the dashboard's Env tab only for non-secret tweaks. The status page's Backup tile will show a yellow warning whenever it detects keys sitting in the ephemeral .env so you don't have to remember this on your own. If you accept the security tradeoff and want .env backed up anyway, set SYNC_INCLUDE_ENV=1 as a Space Variable. The dataset is private, but a leak of that dataset URL is then a leak of every key in .env.

If you prefer not to add API keys as HF Secrets, you can configure providers directly in Hermes after the Space starts:

1. 1.Open /hm/app/config in your Space
2. 2.Add your provider under the llm section:

llm:
  openai:
    api_key: "${OPENAI_API_KEY}"
  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
  moonshot:
    api_key: "${MOONSHOT_API_KEY}"
    base_url: "https://api.moonshot.cn/v1"

If you set the API keys as HF Secrets, you can reference them with ${VAR_NAME} as shown above. Hermes supports many providers — see the Hermes Agent docs for the full list.

Using the API from Code

Your Space exposes an OpenAI-compatible API at /v1/*:

curl https://<you>-<name>.hf.space/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes",
    "messages": [{"role": "user", "content": "hello"}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://<you>-<name>.hf.space/v1",
    api_key="<your GATEWAY_TOKEN>",
)
resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "hello"}],
)

Adding MCP Servers

MCP (Model Context Protocol) servers extend your agent's capabilities. Add them via the config editor at /hm/app/config:

mcp:
  servers:
    fetch:
      command: uvx
      args: ["mcp-server-fetch"]
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/opt/data/workspace"]

uvx and npx are pre-installed in the image.

Persistence Details

When HF_TOKEN is set:

• —On boot, the Space downloads the latest snapshot from your private HF Dataset and restores it into /opt/data/.
• —Every `SYNC_INTERVAL` seconds (default 600), it detects state changes and uploads a new snapshot.
• —On graceful shutdown (SIGTERM), it does one final sync before exit.

What gets backed up: chat sessions, agent memory, workspace files, profiles, skills, cron jobs, Hermes config. The dataset is private to your HF account.

Architecture

Single port (7861) Node.js router fronts multiple backends:

HF Space port 7861
        │
        ▼
   health-server.js  (router + auth + status page)
        │
        ├─► /                  → Hermes WebUI         (127.0.0.1:8787)
        ├─► /hm                → HuggingMes status    (in-process)
        ├─► /hm/app/*          → Hermes dashboard     (127.0.0.1:9119)  [SPA-rewritten]
        ├─► /v1/*              → Hermes gateway API   (127.0.0.1:8642)  [bearer auth]
        ├─► /telegram          → Telegram webhook     (127.0.0.1:8765)
        └─► /health, /status   → in-process JSON

start.sh boots Hermes Agent's gateway + dashboard + WebUI as subprocesses, then the router on top. hermes-sync.py runs the periodic HF Dataset upload loop. Cloudflare and Telegram setup runs once at boot if their respective secrets are set.

Local Testing

git clone https://github.com/F4bC0d3/huggingmes-hermes-webui.git
cd huggingmes-hermes-webui
cp .env.example .env
# edit .env with GATEWAY_TOKEN and provider API keys (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY)
docker build -t huggingmes-hermes-webui .
docker run --rm -p 7861:7861 --env-file .env huggingmes-hermes-webui
# open http://localhost:7861

Extended Troubleshooting

Credits

• —[Nous Research](https://nousresearch.com/) for [Hermes Agent](https://github.com/NousResearch/hermes-agent) — the agent runtime, the persistent memory system, the multi-provider LLM routing, the cron and skills systems. None of this exists without their work.
• —[@nesquena](https://github.com/nesquena) for [Hermes WebUI](https://github.com/nesquena/hermes-webui) — the chat interface you actually see and use. Three-panel layout, SSE streaming, slash commands, profile management, theme system, mobile responsive design — all theirs.
• —[@somratpro](https://github.com/somratpro) for [HuggingMes](https://github.com/somratpro/HuggingMes) — the HF Space packaging, the HF Dataset backup engine (hermes-sync.py), the Cloudflare proxy and keepalive setup, the Telegram integration, and the gateway auth wrapper.

This repo's only contribution is the integration layer: a Node.js router that fronts both UIs on a single HF Space port, unified auth where one GATEWAY_TOKEN gates everything, and minor tweaks to start.sh to launch hermes-webui alongside the existing HuggingMes processes. If you find this useful, star the upstream projects.

License

MIT — same as all upstream projects.