simata/huggingmes
1
1---2title: HuggingMes3emoji: 🪽4colorFrom: blue5colorTo: indigo6sdk: docker7app_port: 78618pinned: true9license: mit10secrets:11 - name: LLM_API_KEY12 description: "Your LLM provider API key for direct providers such as OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, and others."13 - name: LLM_MODEL14 description: "Model or provider model ID, such as openrouter/anthropic/claude-sonnet-4 or openai/gpt-4o."15 - name: GATEWAY_TOKEN16 description: "Strong token to secure your dashboard and API (generate: openssl rand -hex 32)."17 - name: TELEGRAM_BOT_TOKEN18 description: "Telegram bot token from @BotFather."19 - name: TELEGRAM_ALLOWED_USERS20 description: "Comma-separated list of numeric user IDs allowed to use the bot."21 - name: HF_TOKEN22 description: "Hugging Face token with write access. Used for automatic workspace backup and HF providers."23 - name: CLOUDFLARE_WORKERS_TOKEN24 description: "Cloudflare API token for automatic Worker proxy and KeepAlive setup."25---26 27<!-- Badges -->28[](https://github.com/NousResearch/hermes-agent)29[](https://opensource.org/licenses/MIT)30[](https://huggingface.co/spaces)31[](https://github.com/NousResearch/hermes-agent)32 33**Self-hosted Hermes AI agent gateway for Hugging Face Spaces.** HuggingMes runs [Nous Research Hermes Agent](https://github.com/NousResearch/hermes-agent) on HuggingFace Spaces, giving you a 24/7 personal AI assistant with a management dashboard, persistent HF Dataset backup, and automatic connectivity fixes for blocked outbound traffic. HuggingMes directly wires the startup providers listed below, and it can also use Hermes providers configured through `hermes model` or `config.yaml`.34 35## Table of Contents36 37- [✨ Features](#-features)38- [🎥 Video Tutorial](#-video-tutorial)39- [🚀 Quick Start](#-quick-start)40- [🔐 Access Control](#-access-control)41- [🤖 LLM Providers](#-llm-providers)42- [📱 Telegram Setup](#-telegram-setup)43- [🌐 Cloudflare Proxy](#-cloudflare-proxy)44- [💾 Backup & Persistence](#-backup--persistence)45- [📦 Ephemeral Package Re-install](#-ephemeral-package-re-install-optional)46- [🔑 API Key Rotation](#-api-key-rotation-optional)47- [💓 Staying Alive](#-staying-alive-recommended-on-free-hf-spaces)48- [🔐 Security & Advanced](#-security--advanced)49- [💻 Terminal Access (JupyterLab)](#-terminal-access-jupyterlab)50- [🏗️ Architecture](#-architecture)51- [🐛 Troubleshooting](#-troubleshooting)52- [🌟 More Projects](#-more-projects)53 54## ✨ Features55 56- 🧠 **Hermes Core:** Runs Hermes Agent for multi-turn chat, tools, memory, and agent workflows.57- 🔐 **Secure by Default:** Protects the dashboard and API with a single gateway token.58- 🌐 **Built-in Connectivity:** Adds Cloudflare Worker proxy support for Telegram and other blocked outbound traffic.59- 📊 **Dashboard:** Real-time view of uptime, sync health, model, provider, and agent status at `/`.60- 💾 **Persistent Backup:** Syncs chats, config, and session data to a private HF Dataset.61- ⏰ **Keep-Alive:** Can provision a cron-triggered Cloudflare Worker to keep the Space awake.62- 💻 **Terminal Out of the Box:** JupyterLab terminal at `/terminal/` auto-enabled when `GATEWAY_TOKEN` is set — no extra config needed.63- 🔄 **Self-Healing Gateway:** Gateway, dashboard, health server, and JupyterLab are all monitored and automatically restarted if they exit unexpectedly.64- 📦 **Ephemeral Package Replay:** Install packages from the terminal and they survive restarts — shell wrappers record `apt`/`pip`/`uv`/`npm`/`hermes` installs and replay them on every boot.65- 🚀 **Startup Scripts:** Run arbitrary bash at boot via `HUGGINGMES_RUN` or `HUGGINGMES_APT/PIP/NPM_PACKAGES` variables.66- 🔑 **API Key Pool Rotation:** Supply comma-separated key pools (e.g. `ANTHROPIC_API_KEYS=key1,key2`) and the first key is promoted automatically.67- 🤖 **Broad Provider Support:** Supports Hermes' native providers, direct API-key providers, OAuth providers, and custom OpenAI-compatible endpoints.68 69## 🎥 Video Tutorial70 71Watch a quick walkthrough on YouTube: [Deploying HuggingMes on HF Spaces](https://www.youtube.com/watch?v=kagB1ID-NtE).72 73## 🚀 Quick Start74 75### Step 1: Duplicate this Space76 77[](https://huggingface.co/spaces/somratpro/HuggingMes?duplicate=true)78 79### Step 2: Add Your Secrets80 81In your Space's **Settings → Variables and secrets**, add these under **Secrets**:82 83- `LLM_API_KEY` - Your provider API key for direct providers.84- `LLM_MODEL` - The model ID to use, such as `openrouter/anthropic/claude-sonnet-4`, `openai/gpt-4o`, or `google/gemini-2.5-flash`.85- `GATEWAY_TOKEN` - A strong token to secure the dashboard.86- `TELEGRAM_BOT_TOKEN` - Telegram bot token from BotFather.87- `TELEGRAM_ALLOWED_USERS` - Comma-separated numeric Telegram user IDs.88- `HF_TOKEN` - Hugging Face token with write access for backups and HF providers.89- `CLOUDFLARE_WORKERS_TOKEN` - Cloudflare token for outbound proxying and keep-alive automation.90 91### Step 3: Deploy & Run92 93After the Space builds, open it and click **Open Hermes UI** to access the agent interface.94 95## 🔐 Access Control96 97Hermes' built-in dashboard is wrapped by HuggingMes:98 99- **Dashboard:** Opening `/app/` requires `GATEWAY_TOKEN`.100- **API:** Routes under `/v1/*` require `Authorization: Bearer <GATEWAY_TOKEN>`.101 102## 🤖 LLM Providers103 104HuggingMes supports Hermes providers in two different ways:105 106- **Direct startup providers:** Set `LLM_API_KEY` and `LLM_MODEL`, and HuggingMes maps them during boot.107- **Hermes-native providers:** Use `hermes model` after the Space starts, or edit `config.yaml` through the Hermes UI.108- **Custom OpenAI-compatible endpoints:** Point Hermes at your own `/v1` endpoint.109 110### Direct startup providers111 112These are the providers that HuggingMes maps directly from `LLM_MODEL` and `LLM_API_KEY` at startup.113 114| Provider | Prefix | Example `LLM_MODEL` | Key env |115| :--- | :--- | :--- | :--- |116| OpenRouter | `openrouter/` | `openrouter/anthropic/claude-sonnet-4` | `LLM_API_KEY` -> `OPENROUTER_API_KEY` |117| Hugging Face Inference Providers | `huggingface/` or `hf/` | `huggingface/Qwen/Qwen3-235B-A22B-Thinking-2507` | `LLM_API_KEY` -> `HF_TOKEN` |118| AI Gateway / Vercel AI Gateway | `ai-gateway/` or `vercel-ai-gateway/` | `ai-gateway/openai/gpt-4o` | `LLM_API_KEY` -> `AI_GATEWAY_API_KEY` |119| Anthropic | `anthropic/` | `anthropic/claude-sonnet-4-6` | `LLM_API_KEY` -> `ANTHROPIC_API_KEY` |120| OpenAI / OpenAI Codex | `openai/` or `openai-codex/` | `openai/gpt-4o` | `LLM_API_KEY` -> `OPENAI_API_KEY` |121| Google Gemini | `google/` or `gemini/` | `google/gemini-2.5-flash` | `LLM_API_KEY` -> `GOOGLE_API_KEY` and `GEMINI_API_KEY` |122| DeepSeek | `deepseek/` | `deepseek/deepseek-chat` | `LLM_API_KEY` -> `DEEPSEEK_API_KEY` |123| Kimi / Moonshot | `kimi-coding/` or `moonshot/` | `kimi-coding/kimi-for-coding` | `LLM_API_KEY` -> `KIMI_API_KEY` |124| Kimi / Moonshot (China) | `kimi-coding-cn/` | `kimi-coding-cn/kimi-k2.5` | `LLM_API_KEY` -> `KIMI_CN_API_KEY` |125| Arcee AI | `arcee/` | `arcee/trinity-large-thinking` | `LLM_API_KEY` -> `ARCEEAI_API_KEY` |126| GMI Cloud | `gmi/` | `gmi/zai-org/GLM-5.1-FP8` | `LLM_API_KEY` -> `GMI_API_KEY` |127| MiniMax | `minimax/` | `minimax/MiniMax-M2.7` | `LLM_API_KEY` -> `MINIMAX_API_KEY` |128| MiniMax (China) | `minimax-cn/` | `minimax-cn/MiniMax-M2.7` | `LLM_API_KEY` -> `MINIMAX_CN_API_KEY` |129| Alibaba Cloud | `alibaba/` | `alibaba/qwen3.5-plus` | `LLM_API_KEY` -> `DASHSCOPE_API_KEY` |130| Alibaba Coding Plan | `alibaba-coding-plan/` | `alibaba-coding-plan/qwen3-coder-plus` | `LLM_API_KEY` -> `DASHSCOPE_API_KEY` |131| Xiaomi MiMo | `xiaomi/` | `xiaomi/mimo-v2-pro` | `LLM_API_KEY` -> `XIAOMI_API_KEY` |132| Tencent TokenHub | `tencent-tokenhub/` | `tencent-tokenhub/hy3-preview` | `LLM_API_KEY` -> `TOKENHUB_API_KEY` |133| Z.ai / GLM | `zai/`, `z-ai/`, `z.ai/`, or `glm/` | `zai/glm-5` | `LLM_API_KEY` -> `GLM_API_KEY` |134| NVIDIA NIM | `nvidia/` | `nvidia/nemotron-3-super-120b-a12b` | `LLM_API_KEY` -> `NVIDIA_API_KEY` |135| xAI / Grok | `xai/` or `grok/` | `xai/grok-4-1-fast-reasoning` | `LLM_API_KEY` -> `XAI_API_KEY` |136| Kilo Code | `kilocode/` | `kilocode/<model-id>` | `LLM_API_KEY` -> `KILOCODE_API_KEY` |137| OpenCode Zen | `opencode-zen/` | `opencode-zen/<model-id>` | `LLM_API_KEY` -> `OPENCODE_ZEN_API_KEY` |138| OpenCode Go | `opencode-go/` | `opencode-go/<model-id>` | `LLM_API_KEY` -> `OPENCODE_GO_API_KEY` |139 140### Hermes-native providers and OAuth flows141 142These providers are supported by Hermes and can be used in HuggingMes once the agent config is set through `hermes model` or `config.yaml`. HuggingMes does not auto-map them from `LLM_MODEL` at boot unless Hermes itself handles that provider.143 144| Provider | How to use | Notes |145| :--- | :--- | :--- |146| Nous Portal | `hermes model` | Subscription-based OAuth provider in Hermes |147| OpenAI Codex | `hermes model` | ChatGPT OAuth / Codex models |148| GitHub Copilot | `hermes model` | Uses `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` |149| GitHub Copilot ACP | `hermes model` | Spawns the Copilot CLI backend |150| Anthropic (OAuth / Claude Code) | `hermes model` | Also supports `ANTHROPIC_API_KEY` |151| Google Gemini (OAuth) | `hermes model` | Browser OAuth flow, including free-tier Gemini OAuth |152| Qwen Portal (OAuth) | `hermes model` | Alibaba Qwen portal OAuth login |153| MiniMax (OAuth) | `hermes model` | Portal login for MiniMax models |154| Hugging Face Inference Providers | `hermes model` | Unified HF provider routing with model suffixes like `:fastest` and `:cheapest` |155| AWS Bedrock | `hermes model` or `config.yaml` | Uses AWS credentials chain, not an API key |156| Ollama Cloud | `hermes model` | Managed Ollama catalog with `OLLAMA_API_KEY` |157| Arcee AI | `hermes model` | First-class Hermes provider |158| GMI Cloud | `hermes model` | First-class Hermes provider |159| Alibaba Cloud / DashScope | `hermes model` | First-class Hermes provider for Qwen models |160| Tencent TokenHub | `hermes model` | First-class Hermes provider |161| Custom endpoint | `hermes model` or `config.yaml` | Any OpenAI-compatible endpoint |162 163### Custom and self-hosted endpoints164 165HuggingMes also works with any OpenAI-compatible server. Common examples include local Ollama, LM Studio, llama.cpp / llama-server, vLLM, SGLang, LocalAI, Jan, LiteLLM, ClawRouter, Together AI, Groq, Fireworks AI, Azure OpenAI, and similar services.166 167Use either the Hermes model wizard or a direct `config.yaml` entry with a `base_url`, `model`, and optional API key. For local servers that do not require auth, leave the key empty.168 169### Recommended provider choices170 171- **Just want it to work:** OpenRouter or Hermes' Nous Portal.172- **Want local models:** Ollama, LM Studio, llama.cpp, vLLM, or SGLang through a custom endpoint.173- **Need cloud APIs:** OpenAI, Anthropic, Google Gemini, DeepSeek, xAI, Hugging Face, or any other direct provider above.174- **Need routing or fallback:** Use a custom endpoint such as LiteLLM or ClawRouter.175 176## 📱 Telegram Setup177 178To use Hermes via Telegram:179 1801. Create a bot via [@BotFather](https://t.me/BotFather): send `/newbot`, follow the prompts, and copy the bot token.1812. Find your Telegram user ID with [@userinfobot](https://t.me/userinfobot) — send it any message and it replies with your numeric user ID.1823. Add `TELEGRAM_ALLOWED_USERS` as a comma-separated list of those numeric user IDs to restrict access.1834. Add `CLOUDFLARE_WORKERS_TOKEN` if you need automatic outbound proxying for Telegram API traffic.184 185## 🌐 Cloudflare Proxy186 187Hugging Face Spaces often block outbound calls to APIs used by Telegram and some provider backends. HuggingMes can provision a Cloudflare Worker proxy automatically when you add `CLOUDFLARE_WORKERS_TOKEN`.188 189## 💾 Backup & Persistence *(Optional)*190 191Set `HF_TOKEN` with write access to enable backup. HuggingMes syncs workspace data to a private HF Dataset named `huggingmes-backup` every 600 seconds by default.192 193| Variable | Default | Description |194| :--- | :--- | :--- |195| `HF_TOKEN` | — | HF token with **Write** access |196| `BACKUP_DATASET_NAME` | `huggingmes-backup` | Dataset name for backup |197| `SYNC_INTERVAL` | `600` | Backup frequency in seconds |198 199## 📦 Ephemeral Package Re-install *(Optional)*200 201Install packages in the terminal and they survive Space restarts — no extra config needed. Shell wrappers record every successful `apt install`, `pip install`, `uv pip install`, `npm install -g`, and `hermes plugins install` into `workspace/startup.sh`, which is backed up and replayed automatically on next boot.202 203For packages you want installed from day one (before the terminal is even opened), use the startup variables:204 205| Variable | What to put in it |206| :--- | :--- |207| `HUGGINGMES_RUN` | Full bash script to run on every startup (multi-line, heredocs, `if` blocks all work) |208| `HUGGINGMES_APT_PACKAGES` | Space-separated apt packages to install |209| `HUGGINGMES_PIP_PACKAGES` | Space-separated Python packages to install |210| `HUGGINGMES_NPM_PACKAGES` | Space-separated npm packages to install globally |211 212**Example:**213 214```bash215HUGGINGMES_RUN="""216pip install pandas matplotlib217npm install -g tsx218sudo apt-get install -y ffmpeg219"""220```221 222For scripts with complex quoting, base64-encode them:223 224```bash225# locally226base64 -w0 setup.sh227# HF Variable228HUGGINGMES_RUN=base64:<paste-output-here>229```230 231## 🔑 API Key Rotation *(Optional)*232 233Spread requests across multiple API keys to avoid rate limits. Supply a comma-separated pool — the first key is promoted to the provider's singular env var, and Hermes picks it up automatically.234 235```bash236ANTHROPIC_API_KEYS=sk-ant-key1,sk-ant-key2237OPENAI_API_KEYS=sk-oai-key1,sk-oai-key2238OPENROUTER_API_KEYS=sk-or-key1,sk-or-key2239```240 241Supported pool vars: `OPENROUTER_API_KEYS`, `ANTHROPIC_API_KEYS`, `OPENAI_API_KEYS`, `GOOGLE_API_KEYS`, `GEMINI_API_KEYS`, `DEEPSEEK_API_KEYS`, `KIMI_API_KEYS`, `MINIMAX_API_KEYS`, `NVIDIA_API_KEYS`, `XAI_API_KEYS`, `KILOCODE_API_KEYS`, `GLM_API_KEYS`, `ARCEEAI_API_KEYS`, `DASHSCOPE_API_KEYS`, `GMI_API_KEYS`, `TOKENHUB_API_KEYS`.242 243## 💓 Staying Alive244 245With `CLOUDFLARE_WORKERS_TOKEN` set, HuggingMes can create a keep-alive worker that pings the Space's `/health` endpoint on a schedule so the free tier stays awake longer.246 247## 🔐 Security & Advanced *(Optional)*248 249| Variable | Default | Description |250| :--- | :--- | :--- |251| `GATEWAY_TOKEN` | — | Token for dashboard and API auth |252| `HF_TOKEN` | — | HF token with write access for backups and HF providers |253| `CLOUDFLARE_WORKERS_TOKEN` | — | Cloudflare API token for proxying and keep-awake |254| `SYNC_INTERVAL` | `600` | Backup frequency in seconds |255| `CLOUDFLARE_KEEPALIVE_ENABLED` | `true` | Set `false` to disable keep-awake worker |256| `TELEGRAM_MODE` | `webhook` | `webhook` or `polling` (webhook auto-configured from `SPACE_HOST`) |257| `DEV_MODE` | `true` | Set `false` to disable JupyterLab terminal at `/terminal/` |258| `JUPYTER_TOKEN` | *(uses `GATEWAY_TOKEN`)* | Override terminal password (optional) |259| `WEBHOOK_URL` | — | Endpoint for POST JSON restart notifications |260| `GATEWAY_RESTART_DELAY` | `5` | Seconds between gateway restart attempts |261| `GATEWAY_MAX_RESTARTS` | `0` (unlimited) | Maximum gateway restart count before container exits |262 263## 💻 Terminal Access (JupyterLab)264 265HuggingMes includes a JupyterLab terminal at `/terminal/` for direct shell access to the container — useful for running `hermes` commands, inspecting files, installing packages, and debugging. Enabled by default when `GATEWAY_TOKEN` is set.266 267### Setup268 269The terminal is **on by default** — no extra configuration needed. Click **Open Terminal →** on the dashboard, then log in with your `GATEWAY_TOKEN`.270 271To disable it, set `DEV_MODE=false`. To use a separate terminal password, set `JUPYTER_TOKEN` to a different value.272 273> **Security:** JupyterLab grants full shell access to the container. The terminal will not start if no `GATEWAY_TOKEN` is set.274 275### What you can do276 277- Run `hermes` CLI commands directly278- Browse and edit files in the workspace279- Install Python packages with `pip` or `uv pip`280- Check logs, inspect config, debug issues281 282## 💻 Local Development283 284```bash285docker compose up --build286# Dashboard: http://localhost:7861287# Hermes App: http://localhost:7861/app/288```289 290## 🏗️ Architecture291 292- **Dashboard (`/`)**: Real-time management and monitoring.293- **Hermes App (`/app/`)**: Secure proxied access to the Hermes UI.294- **API (`/v1/*`)**: Proxied OpenAI-compatible agent API.295- **Terminal (`/terminal/`)**: JupyterLab terminal (auto-enabled when `GATEWAY_TOKEN` is set; set `DEV_MODE=false` to disable).296- **Health Check (`/health`)**: Readiness probe for HF and keep-alive.297- **Sync Engine**: Python background task for HF Dataset persistence.298 299## 🐛 Troubleshooting300 301- **Telegram bot not responding:** Ensure `CLOUDFLARE_WORKERS_TOKEN` is set and check logs for the proxy setup step.302- **Authentication failed:** Clear browser cookies or use an incognito window if `GATEWAY_TOKEN` changed.303- **Data not persisting:** Ensure `HF_TOKEN` has write access.304- **Provider not showing up:** If it is a Hermes-native provider, run `hermes model` and complete the provider-specific setup there. If it is a custom endpoint, verify the `base_url` exposes `/v1/models` or `/v1/chat/completions`.305- **Space keeps sleeping:** Add `CLOUDFLARE_WORKERS_TOKEN` to enable automatic keep-awake monitoring.306 307## 🌟 More Projects308 309Similar projects by [@somratpro](https://github.com/somratpro) — all free, one-click deploy on HF Spaces:310 311| Project | What it runs | HF Space | GitHub |312| :--- | :--- | :--- | :--- |313| **HuggingFlow** | DeerFlow — deep research agent | [Space](https://huggingface.co/spaces/somratpro/HuggingFlow) | [Repo](https://github.com/somratpro/HuggingFlow) |314| **Hugging8n** | n8n — workflow & automation platform | [Space](https://huggingface.co/spaces/somratpro/Hugging8n) | [Repo](https://github.com/somratpro/hugging8n) |315| **HuggingClaw** | OpenClaw — Claude Code in the browser | [Space](https://huggingface.co/spaces/somratpro/HuggingClaw) | [Repo](https://github.com/somratpro/huggingclaw) |316| **HuggingClip** | Paperclip — AI agent orchestration platform | [Space](https://huggingface.co/spaces/somratpro/HuggingClip) | [Repo](https://github.com/somratpro/huggingclip) |317| **HuggingPost** | Postiz — social-media scheduler | [Space](https://huggingface.co/spaces/somratpro/HuggingPost) | [Repo](https://github.com/somratpro/huggingpost) |318 319---320*Made with ❤️ by [@somratpro](https://github.com/somratpro)*321