xulei123/HermesFace2

<div align="center">

🔱 HermesFace

Your always-on, self-improving AI assistant — free, no server needed

No Mac Mini? No problem. Get a fully-featured AI assistant running 24/7 on HuggingFace's free tier — 2 vCPU, 16 GB RAM, 50 GB storage, zero cost.

_{Telegram · Discord · Slack · WhatsApp · Signal · WeChat · 16+ channels · Self-improving skills · Persistent memory}

        

</div>

What you get

In about 5 minutes, you'll have a free, always-on, self-improving AI assistant connected to Telegram, Discord, Slack, WhatsApp, and 16+ other channels — no server, no subscription, no hardware required.

Powered by [Hermes Agent](https://github.com/NousResearch/hermes-agent) — Nous Research's open-source, self-improving AI assistant that normally requires your own machine. HermesFace makes it run for free on HuggingFace Spaces by adding data persistence via HF Dataset sync.

Architecture

┌─────────────────────────────────────────────────────┐
│  HuggingFace Space (Docker, cpu-basic)              │
│                                                     │
│  ┌──────────────┐    ┌────────────────────────────┐ │
│  │ sync_hf.py   │───▶│  Hermes Agent              │ │
│  │ (persistence │    │  ├─ Web Dashboard (:7860)   │ │
│  │  manager)    │    │  ├─ Gateway (messaging)     │ │
│  │              │    │  ├─ Skills Engine            │ │
│  └──────┬───────┘    │  ├─ Memory System           │ │
│         │            │  ├─ Cron Scheduler           │ │
│         ▼            │  └─ 47 Tools                 │ │
│  ┌──────────────┐    └────────────────────────────┘ │
│  │ HF Dataset   │  ◀── Auto-sync every 60s         │
│  │ (private)    │      Config, skills, memories     │
│  └──────────────┘                                   │
└─────────────────────────────────────────────────────┘

Quick Start

1. Duplicate this Space

Click Duplicate this Space on the HermesFace Space page.

2. Set Secrets

Go to Settings → Repository secrets and add the following. The only two you must set are HF_TOKEN and one API key.

Data Persistence

HermesFace syncs /opt/data (conversations, skills, memories, config) to a private HuggingFace Dataset repo so your data survives every restart.

Option A — Auto mode (recommended)

1. 1.Set AUTO_CREATE_DATASET = true in your Space secrets
2. 2.Set HF_TOKEN with write permission
3. 3.Done — on first startup, HermesFace automatically creates a private Dataset repo named your-username/SpaceName-data. Each duplicated Space gets its own isolated dataset.

Option B — Manual mode

1. 1.Go to huggingface.co/new-dataset and create a private Dataset repo (e.g. your-name/HermesFace-data)
2. 2.Set HERMES_DATASET_REPO = your-name/HermesFace-data in your Space secrets
3. 3.Set HF_TOKEN with write permission
4. 4.Done — HermesFace will sync to this repo every 60 seconds

Environment Variables

Fine-tune persistence and performance. Set these as Repository Secrets in HF Spaces, or in .env for local Docker.

For the full list (including all Hermes Agent variables), see `.env.example`.

3. Open the Dashboard

Visit your Space URL. The Hermes Agent web dashboard provides:

• —Status Page — agent status and session activity
• —Config Page — dynamic configuration editor
• —Env Page — API key management

Messaging integrations (Telegram, Discord, WhatsApp) can be configured through the dashboard or via environment variables.

Configuration

HermesFace supports all Hermes Agent environment variables — it passes the entire environment to the Hermes process (env=os.environ.copy()), so any variable from the Hermes Agent docs works out of the box in HF Spaces. This includes:

• —API Keys — OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, NOUS_API_KEY, GOOGLE_API_KEY, MISTRAL_API_KEY
• —Messaging — TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN
• —Terminal — TERMINAL_BACKEND, TERMINAL_TIMEOUT
• —Browser — BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID

HermesFace adds its own variables for persistence and deployment: HF_TOKEN, HERMES_DATASET_REPO, AUTO_CREATE_DATASET, SYNC_INTERVAL, etc. See `.env.example` for the complete reference.

Connecting Messaging Platforms

Set the appropriate bot token as a Space Secret:

Local Docker

git clone https://github.com/democra-ai/HermesFace.git
cd HermesFace
cp .env.example .env    # Edit with your API keys
docker build -t hermesface .
docker run -p 7860:7860 --env-file .env hermesface

Acknowledgments

• —[Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research — the self-improving AI assistant framework
• —[HuggingFace Spaces](https://huggingface.co/spaces) — free Docker hosting for ML apps

License

MIT