HuggingMes

title: HuggingMes emoji: 🪽 colorFrom: blue colorTo: indigo sdk: docker app_port: 7861 pinned: true license: mit secrets:

• name: LLM_API_KEY description: "Your LLM provider API key for direct providers such as OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, and others."
• name: LLM_MODEL description: "Model or provider model ID, such as openrouter/anthropic/claude-sonnet-4 or openai/gpt-4o."
• name: GATEWAY_TOKEN description: "Strong token to secure your dashboard and API (generate: openssl rand -hex 32)."
• name: TELEGRAM_BOT_TOKEN description: "Telegram bot token from @BotFather."
• name: TELEGRAM_ALLOWED_USERS description: "Comma-separated list of numeric user IDs allowed to use the bot."
• name: HF_TOKEN description: "Hugging Face token with write access. Used for automatic workspace backup and HF providers."
• name: CLOUDFLARE_WORKERS_TOKEN description: "Cloudflare API token for automatic Worker proxy and KeepAlive setup."

Self-hosted Hermes AI agent gateway for Hugging Face Spaces. HuggingMes runs Nous Research 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.

Table of Contents

• ✨ Features
• 🎥 Video Tutorial
• 🚀 Quick Start
• 🔐 Access Control
• 🤖 LLM Providers
• 📱 Telegram Setup
• 🌐 Cloudflare Proxy
• 💾 Backup & Persistence
• 📦 Ephemeral Package Re-install
• 🔑 API Key Rotation
• 💓 Staying Alive
• 🔐 Security & Advanced
• 💻 Terminal Access (JupyterLab)
• 🏗️ Architecture
• 🐛 Troubleshooting
• 🌟 More Projects

✨ Features

• 🧠 Hermes Core: Runs Hermes Agent for multi-turn chat, tools, memory, and agent workflows.
• 🔐 Secure by Default: Protects the dashboard and API with a single gateway token.
• 🌐 Built-in Connectivity: Adds Cloudflare Worker proxy support for Telegram and other blocked outbound traffic.
• 📊 Dashboard: Real-time view of uptime, sync health, model, provider, and agent status at /.
• 💾 Persistent Backup: Syncs chats, config, and session data to a private HF Dataset.
• ⏰ Keep-Alive: Can provision a cron-triggered Cloudflare Worker to keep the Space awake.
• 💻 Terminal Out of the Box: JupyterLab terminal at /terminal/ auto-enabled when GATEWAY_TOKEN is set — no extra config needed.
• 🔄 Self-Healing Gateway: Gateway, dashboard, health server, and JupyterLab are all monitored and automatically restarted if they exit unexpectedly.
• 📦 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.
• 🚀 Startup Scripts: Run arbitrary bash at boot via HUGGINGMES_RUN or HUGGINGMES_APT/PIP/NPM_PACKAGES variables.
• 🔑 API Key Pool Rotation: Supply comma-separated key pools (e.g. ANTHROPIC_API_KEYS=key1,key2) and the first key is promoted automatically.
• 🤖 Broad Provider Support: Supports Hermes' native providers, direct API-key providers, OAuth providers, and custom OpenAI-compatible endpoints.

🎥 Video Tutorial

Watch a quick walkthrough on YouTube: Deploying HuggingMes on HF Spaces.

🚀 Quick Start

Step 1: Duplicate this Space

Step 2: Add Your Secrets

In your Space's Settings → Variables and secrets, add these under Secrets:

• LLM_API_KEY - Your provider API key for direct providers.
• LLM_MODEL - The model ID to use, such as openrouter/anthropic/claude-sonnet-4, openai/gpt-4o, or google/gemini-2.5-flash.
• GATEWAY_TOKEN - A strong token to secure the dashboard.
• TELEGRAM_BOT_TOKEN - Telegram bot token from BotFather.
• TELEGRAM_ALLOWED_USERS - Comma-separated numeric Telegram user IDs.
• HF_TOKEN - Hugging Face token with write access for backups and HF providers.
• CLOUDFLARE_WORKERS_TOKEN - Cloudflare token for outbound proxying and keep-alive automation.

Step 3: Deploy & Run

After the Space builds, open it and click Open Hermes UI to access the agent interface.

🔐 Access Control

Hermes' built-in dashboard is wrapped by HuggingMes:

• Dashboard: Opening /app/ requires GATEWAY_TOKEN.
• API: Routes under /v1/* require Authorization: Bearer <GATEWAY_TOKEN>.

🤖 LLM Providers

HuggingMes supports Hermes providers in two different ways:

• Direct startup providers: Set LLM_API_KEY and LLM_MODEL, and HuggingMes maps them during boot.
• Hermes-native providers: Use hermes model after the Space starts, or edit config.yaml through the Hermes UI.
• Custom OpenAI-compatible endpoints: Point Hermes at your own /v1 endpoint.

Direct startup providers

These are the providers that HuggingMes maps directly from LLM_MODEL and LLM_API_KEY at startup.

Hermes-native providers and OAuth flows

These 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.