agenticverse/AgentNexa
0
1---2title: HermesFace3emoji: 🔱4colorFrom: purple5colorTo: blue6sdk: docker7pinned: false8license: mit9datasets:10 - tao-shen/HermesFace-data11short_description: Free always-on self-improving AI agent, no hardware required12app_port: 786013tags:14 - huggingface15 - hermes-agent16 - nousresearch17 - chatbot18 - llm19 - ai-assistant20 - whatsapp21 - telegram22 - text-generation23 - openai-api24 - openai-compatible25 - huggingface-spaces26 - docker27 - deployment28 - persistent-storage29 - agents30 - multi-channel31 - free-tier32 - one-click-deploy33 - self-hosted34 - messaging-bot35 - self-improving36---37 38<div align="center">39 <img src="HermesFace.png" alt="HermesFace" width="720"/>40 <br/><br/>41 <strong>Your always-on, self-improving AI agent — free, no server needed</strong>42 <br/>43 <sub>Telegram · Discord · Slack · WhatsApp · Signal · WeChat · 16+ channels · Self-improving skills · Persistent memory · One-click deploy</sub>44 <br/><br/>45 46 [](LICENSE)47 [](https://huggingface.co/spaces/tao-shen/HermesFace)48 [](https://github.com/democra-ai/HermesFace)49 [](https://github.com/NousResearch/hermes-agent)50 [](https://www.docker.com/)51 [](https://github.com/NousResearch/hermes-agent)52 [](https://telegram.org/)53 [](https://discord.com/)54 [](https://huggingface.co/spaces)55</div>56 57---58 59## What you get60 61In 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.62 63| | |64|---|---|65| **Free forever** | HuggingFace Spaces gives you 2 vCPU + 16 GB RAM at no cost |66| **Always online** | Your conversations, skills, memories, and config survive every restart |67| **16+ channels** | Telegram, Discord, Slack, WhatsApp, Signal, WeChat, iMessage, and more |68| **Self-improving** | Hermes creates and refines skills from experience during use |69| **Persistent memory** | LLM-powered memory with search and summarization across sessions |70| **47 built-in tools** | Terminal, file ops, web search, vision, image generation, browser automation |71| **Any LLM** | OpenRouter (200+ models, free tier available), OpenAI, Claude, Gemini, Nous Portal |72| **Web dashboard** | React-based UI for managing config, API keys, and monitoring sessions |73| **One-click deploy** | Duplicate the Space, set two secrets, done |74 75> **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.76 77## Architecture78 79<div align="center">80 <img src="assets/architecture.svg" alt="Architecture" width="720"/>81</div>82 83---84 85## Quick Start86 87### 1. Duplicate this Space88 89Click **Duplicate this Space** on the [HermesFace Space page](https://huggingface.co/spaces/tao-shen/HermesFace).90 91> **After duplicating:** edit your Space's `README.md` and update the `datasets:` field in the YAML header to point to your own dataset repo (e.g. `your-name/YourSpace-data`), or remove it entirely. This prevents your Space from appearing as linked to the original dataset.92 93### 2. Set Secrets94 95Go to **Settings → Repository secrets** and add the following. The only two you *must* set are `HF_TOKEN` and one API key.96 97| Secret | Status | Description | Example |98|--------|:------:|-------------|---------|99| `HF_TOKEN` | **Required** | HF Access Token with write permission ([create one](https://huggingface.co/settings/tokens)) | `hf_AbCdEfGhIjKlMnOpQrStUvWxYz` |100| `AUTO_CREATE_DATASET` | **Recommended** | Set to `true` — HermesFace will automatically create a private backup dataset on first startup. No manual setup needed. | `true` |101| `OPENROUTER_API_KEY` | Recommended | [OpenRouter](https://openrouter.ai) API key — 200+ models, free tier available. Easiest way to get started. | `sk-or-v1-xxxxxxxxxxxx` |102| `OPENAI_API_KEY` | Optional | OpenAI API key | `sk-proj-xxxxxxxxxxxx` |103| `ANTHROPIC_API_KEY` | Optional | Anthropic Claude API key | `sk-ant-xxxxxxxxxxxx` |104| `NOUS_API_KEY` | Optional | Nous Portal API key | `nous-xxxxxxxxxxxx` |105| `GOOGLE_API_KEY` | Optional | Google / Gemini API key | `AIzaSyXxXxXxXxXx` |106 107### Data Persistence108 109HermesFace syncs `/opt/data` (conversations, skills, memories, config) to a private HuggingFace Dataset repo so your data survives every restart.110 111**Option A — Auto mode (recommended)**112 1131. Set `AUTO_CREATE_DATASET` = `true` in your Space secrets1142. Set `HF_TOKEN` with write permission1153. Done — on first startup, HermesFace automatically creates a private Dataset repo named `your-username/SpaceName-data`. Each duplicated Space gets its own isolated dataset.116 117**Option B — Manual mode**118 1191. Go to [huggingface.co/new-dataset](https://huggingface.co/new-dataset) and create a **private** Dataset repo (e.g. `your-name/HermesFace-data`)1202. Set `HERMES_DATASET_REPO` = `your-name/HermesFace-data` in your Space secrets1213. Set `HF_TOKEN` with write permission1224. Done — HermesFace will sync to this repo every 60 seconds123 124### Environment Variables125 126Fine-tune persistence and performance. Set these as **Repository Secrets** in HF Spaces, or in `.env` for local Docker.127 128| Variable | Default | Description |129|----------|---------|-------------|130| `AUTO_CREATE_DATASET` | `true` | Auto-create the Dataset repo on first startup |131| `SYNC_INTERVAL` | `60` | Backup interval in seconds |132| `AGENT_NAME` | `HermesFace` | Agent display name in messaging platforms |133| `TZ` | `UTC` | Timezone for logs and scheduled tasks |134 135> For the full list (including all Hermes Agent variables), see [`.env.example`](.env.example).136 137### 3. Open the Dashboard138 139Visit your Space URL. The Hermes Agent web dashboard provides:140- **Status Page** — agent status and session activity141- **Config Page** — dynamic configuration editor142- **Env Page** — API key management143 144Messaging integrations (Telegram, Discord, WhatsApp) can be configured through the dashboard or via environment variables.145 146## Configuration147 148HermesFace 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](https://github.com/NousResearch/hermes-agent) works out of the box in HF Spaces. This includes:149 150- **API Keys** — `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `NOUS_API_KEY`, `GOOGLE_API_KEY`, `MISTRAL_API_KEY`151- **Messaging** — `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`152- **Terminal** — `TERMINAL_BACKEND`, `TERMINAL_TIMEOUT`153- **Browser** — `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`154 155HermesFace adds its own variables for persistence and deployment: `HF_TOKEN`, `HERMES_DATASET_REPO`, `AUTO_CREATE_DATASET`, `SYNC_INTERVAL`, etc. See [`.env.example`](.env.example) for the complete reference.156 157## Connecting Messaging Platforms158 159Set the appropriate bot token as a Space Secret:160 161| Platform | Secret | Docs |162|----------|--------|------|163| Telegram | `TELEGRAM_BOT_TOKEN` | [BotFather](https://t.me/botfather) |164| Discord | `DISCORD_BOT_TOKEN` | [Discord Developer Portal](https://discord.com/developers/applications) |165| Slack | `SLACK_BOT_TOKEN` | [Slack API](https://api.slack.com/apps) |166| WhatsApp | QR code pairing | Automatic via gateway |167| Signal | Via linked device | Configure in gateway |168| WeChat | `WEIXIN_APP_ID` + `WEIXIN_APP_SECRET` | WeChat Open Platform |169 170## Local Docker171 172```bash173git clone https://github.com/democra-ai/HermesFace.git174cd HermesFace175cp .env.example .env # Edit with your API keys176docker build -t hermesface .177docker run -p 7860:7860 --env-file .env hermesface178```179 180## Security181 182- **Environment isolation** — each Space runs in its own Docker container, sandboxed from your local machine. Unlike running Hermes Agent locally (where it has full system privileges), cloud deployment limits the blast radius.183- **Secrets stay server-side** — API keys and tokens are set as HF Spaces Repository Secrets, never exposed to the browser or the public Dataset.184- **Private backups** — the Dataset repo is created as private by default.185- **DNS over HTTPS** — `dns-resolve.py` bypasses HF Spaces' DNS blocks on Telegram / Discord / WhatsApp via Cloudflare + Google DoH, writing `/etc/hosts` (for Python) and `/tmp/dns-resolved.json` (consumed by the Node `dns-fix.cjs` preload).186 187## Manual backup / restore188 189For one-off snapshots outside the 60-second sync cycle, use the CLI utilities in `scripts/`:190 191```bash192# Full tar.gz snapshot → Dataset repo (keeps last 5, auto-rotates)193python3 scripts/hermes_persist.py save194 195# Restore latest snapshot into /opt/data196python3 scripts/hermes_persist.py load197 198# Inspect current backups199python3 scripts/hermes_persist.py status200```201 202The atomic variants (`save_to_dataset_atomic.py`, `restore_from_dataset_atomic.py`) use HF commit operations with checksum metadata for file-granular restore — useful when you only want to roll back a single file.203 204## Acknowledgments205 206- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** by [Nous Research](https://nousresearch.com/) — the self-improving AI assistant framework HermesFace wraps207- **[HuggingFace Spaces](https://huggingface.co/spaces)** — free Docker hosting for ML apps208- **[HuggingClaw](https://github.com/tao-shen/HuggingClaw)** — sibling project that pioneered the atomic-tar persistence + DoH DNS escape-hatch patterns HermesFace adopts209 210## License211 212MIT213