README.md

metadata

title: HuggingMess
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. HuggingMess maps it to the right Hermes
      provider env var.
  - name: LLM_MODEL
    description: >-
      Optional model ID override, e.g. openrouter/anthropic/claude-sonnet-4 or
      anthropic/claude-opus-4.6.
  - name: TELEGRAM_BOT_TOKEN
    description: Telegram bot token from @BotFather.
  - name: TELEGRAM_ALLOWED_USERS
    description: Comma-separated numeric Telegram user IDs allowed to use the bot.
  - name: GATEWAY_TOKEN
    description: Bearer token for the proxied Hermes API routes.
  - name: HF_TOKEN
    description: Hugging Face token with write access for private Dataset backup.
  - name: CLOUDFLARE_WORKERS_TOKEN
    description: >-
      Cloudflare API token for automatic Telegram proxy and keep-awake Worker
      setup.

HuggingMess

HuggingMess runs Nous Research Hermes Agent as a Hugging Face Docker Space. It follows the same practical shape as HuggingClaw: one public Space port, Telegram gateway support, Cloudflare Worker proxy setup, Cloudflare cron keep-awake, and private HF Dataset backup for Hermes state.

Quick Start

1. Duplicate this Space or push this folder to a new Docker Space.
2. Add these secrets in Space Settings:

Secret	Required	Notes
LLM_MODEL	Optional	Model override. If unset, HuggingMess leaves Hermes default/restored config alone.
LLM_API_KEY	Usually	Used to populate the provider-specific env var automatically
TELEGRAM_BOT_TOKEN	For Telegram	Bot token from BotFather
TELEGRAM_ALLOWED_USERS	Recommended	Comma-separated numeric Telegram user IDs
GATEWAY_TOKEN	Recommended	Bearer token for /v1/* API routes
HF_TOKEN	Optional	Enables private Dataset backup named huggingmess-backup
CLOUDFLARE_WORKERS_TOKEN	Optional	Auto-creates Workers for Telegram proxy and /health keep-awake

Access Control

Hermes' built-in dashboard is local-first and does not provide its own public auth layer. HuggingMess adds wrapper-level auth for the exposed Space routes.

Set this Space secret:

GATEWAY_TOKEN=your-strong-password-or-token

Then:

• Opening /app/ shows a HuggingMess login page with one field.
• Paste GATEWAY_TOKEN into that field.
• HuggingMess stores an HTTP-only session cookie for the dashboard routes.
• API routes under /v1/* accept Authorization: Bearer <GATEWAY_TOKEN>.

LLM Providers

HuggingMess supports two configuration styles:

1. Simple wrapper style: set LLM_MODEL and LLM_API_KEY; HuggingMess maps them into Hermes config and provider-specific API key variables.
2. Native Hermes style: set Hermes variables directly, such as HERMES_MODEL, HERMES_INFERENCE_PROVIDER, and the provider API key.

Gemini

For Google Gemini, add these Space secrets:

Secret	Value
LLM_MODEL	google/gemini-2.5-flash
LLM_API_KEY	Your Google AI Studio API key

HuggingMess will convert that into Hermes config:

model:
  default: gemini-2.5-flash
  provider: gemini

And it exports both GOOGLE_API_KEY and GEMINI_API_KEY for Hermes. You can also use gemini/gemini-2.5-flash; the prefix is stripped the same way.

Native Hermes equivalent:

Secret	Value
HERMES_MODEL	gemini-2.5-flash
HERMES_INFERENCE_PROVIDER	gemini
GOOGLE_API_KEY or GEMINI_API_KEY	Your Google AI Studio API key

Common Examples

Provider	Simple LLM_MODEL	API key secret
Gemini	google/gemini-2.5-flash	LLM_API_KEY
OpenRouter	openrouter/anthropic/claude-sonnet-4	LLM_API_KEY
Anthropic	anthropic/claude-opus-4.6	LLM_API_KEY
OpenAI	openai/gpt-4o	LLM_API_KEY
Hugging Face Router	huggingface/meta-llama/Llama-3.3-70B-Instruct	LLM_API_KEY

Telegram on HF Spaces

When TELEGRAM_BOT_TOKEN and SPACE_HOST are present, HuggingMess defaults Telegram to webhook mode:

TELEGRAM_WEBHOOK_URL=https://your-space.hf.space/telegram
TELEGRAM_WEBHOOK_PORT=8765

If you need polling instead, set:

TELEGRAM_MODE=polling

Hermes requires numeric Telegram IDs for allowlists. You can use either Hermes-native TELEGRAM_ALLOWED_USERS or the HuggingClaw-style aliases TELEGRAM_USER_ID / TELEGRAM_USER_IDS.

Cloudflare Workers

Hugging Face Spaces can be restrictive for outbound bot API traffic. Add CLOUDFLARE_WORKERS_TOKEN, and HuggingMess will:

1. create a Telegram proxy Worker,
2. generate a shared proxy secret,
3. set Hermes Telegram base_url to https://worker.example.workers.dev/bot,
4. set base_file_url to https://worker.example.workers.dev/file/bot,
5. create a second scheduled keep-awake Worker that pings your Space /health route.

Manual mode is also supported:

CLOUDFLARE_PROXY_URL=https://your-worker.workers.dev
CLOUDFLARE_PROXY_SECRET=optional-shared-secret

The manual Worker source is included in cloudflare-worker.js.

Keep Awake

When CLOUDFLARE_WORKERS_TOKEN is present, HuggingMess creates a scheduled Worker that pings your Space's /health route. It automatically detects your Space hostname:

https://your-space.hf.space/health

Default schedule:

*/10 * * * *

Optional variables:

Variable	Default	Description
CLOUDFLARE_KEEPALIVE_ENABLED	true	Set false to skip keep-awake Worker setup
CLOUDFLARE_KEEPALIVE_CRON	*/10 * * * *	Cloudflare cron expression
CLOUDFLARE_KEEPALIVE_URL	https://<auto-detected-space-host>/health	URL to ping
CLOUDFLARE_KEEPALIVE_WORKER_NAME	derived from space host	Custom Worker name

Backup

Set HF_TOKEN with write access to enable backup. HuggingMess syncs /opt/data to a private Dataset named huggingmess-backup every 180 seconds by default.

Variable	Default	Description
BACKUP_DATASET_NAME	huggingmess-backup	Dataset name under your HF account
SYNC_INTERVAL	180	Backup interval in seconds
SYNC_INCLUDE_ENV	false	Include /opt/data/.env in backup

By default .env is excluded from backups because HF Space secrets are already injected at runtime.

Local Development

docker compose up --build

Then open:

http://localhost:7861

Useful Routes

Route	Purpose
/	HuggingMess dashboard
/health	Health check for HF and Cloudflare keep-awake
/status	JSON status
/app/	Proxied Hermes dashboard/app
/v1/*	Proxied Hermes OpenAI-compatible API routes
/telegram	Telegram webhook endpoint

The /v1/* routes require:

Authorization: Bearer <GATEWAY_TOKEN>

Links

• Hermes Agent GitHub
• Hermes Agent Docs
• Hermes Docker Docs
• Hermes Telegram Docs