Hermes Stack — Your own AI server on a free Hugging Face Space

Features

A whole server stack, in one card

Everything the paid PaaS templates give you — rethought for a free Hugging Face Space.

The agent

🧠

Hermes Agent, fully hosted

Multi-turn chat, tools, memory and skills — with the official web dashboard at /hermes/ behind basic auth, and the same agent exposed as an OpenAI-compatible API at /hermes-api/v1.

The gateway

🔀

Model router with a dashboard

9Router gives you a real web UI to manage models and keys, served at the root URL. Its /v1 endpoint speaks OpenAI — plug it into any client.

✈️

Telegram control

Chat with your agent from anywhere. Polling mode is outbound-only, so it works behind any firewall. Locked to your user ID.

Persistence

💾

Hourly backups, auto-restore

Space disks are ephemeral. Your state is tarballed every hour to a private dataset and restored on every boot — this is what makes it a real server.

💓

Built-in keep-alive

A GitHub Action pings /healthz every 10 minutes and wakes the Space if it sleeps. No external cron service needed.

🎁

~78 keyless models

The bundled OmniRouter serves free web models (Qwen, Gemini guest mode and more) with zero API keys — great as a fallback provider.

🛠️

Real-server customization

EXTRA_PIP_PACKAGES, EXTRA_APT_PACKAGES, EXTRA_NPM_PACKAGES and STARTUP_SCRIPT run at every boot — plus a persistent hfkit-boot.sh that survives restarts.

How it works

Three steps. Five minutes.

Railway-style simplicity, powered by GitHub Actions under the hood.

Open the wizard

Paste three tokens — GitHub, Hugging Face (write), Telegram (optional). The wizard validates them live and generates strong passwords for you.

godde3s.github.io/hermes-stack/deploy.html

Press deploy

The wizard creates your repo, encrypts every secret in your browser, and launches the deploy workflow. Then it watches the build until your Space is green.

Actions → Deploy to Hugging Face ✓

Use everything

Open the dashboard, message the bot on Telegram, point any OpenAI client at your API. Keep-alive and backups are already running.

https://you-space.hf.space — live 🟢

Architecture

What runs where

One Space, one public port, four services behind a Caddy front proxy.

ONE FREE HF SPACE (Docker · port 7860)

Telegram ──polling──► agent gateway ──► tools · memory · skills
Browser ──► Caddy :7860
  / ─────────────► router dashboard (Next.js)
  /v1 ───────────► OpenAI-compatible router API
  /hermes/ ──────► agent dashboard (basic auth)
  /hermes-api/v1 ► agent as an API (bearer key)
  /healthz ──────► keep-alive endpoint (200 ok)
GitHub Action ──10 min──► /healthz (wake on sleep)
Backup loop ──hourly──► private dataset ──boot──► auto-restore

Why this way

Railway templates, without the bill

Same developer experience as one-click PaaS templates — on infrastructure that stays free.

	Railway free trial	Hermes Stack on HF
Cost after trial	~$1/month credit — not enough	Free (CPU-basic)
Setup UX	One-click template	Web wizard + template repo
Persistence	Volume included	Hourly backup + auto-restore
Keep-alive	Always-on (paid)	Included GitHub Action
Keyless free models	Bring your own keys	~78 built-in

Staying safe

Built to be a good tenant

Free Spaces are shared infrastructure — this stack is engineered to be quiet, compliant and recoverable.

✅ Moderate resources

CPU-basic only, self-healing supervisor with exponential backoff. No crash loops, no mining, no abuse patterns that get Spaces flagged.

✅ Private by default

One checkbox makes your Space private. Backups always go to a private dataset. Keys live in encrypted secrets only.

✅ Locked-down bot

The Telegram gateway only answers your numeric user IDs — an open relay through HF infrastructure is the fastest way to get reported.

⚠️ Honest expectations

Running an agent is not against the ToS (public projects do it), but free Spaces aren't sold as always-on servers. Use a neutral name, don't share your URL, and keep your usage personal.

FAQ

Quick answers

Is it really free?

Yes — the free CPU-basic Space (2 vCPU / 16 GB RAM) plus free GitHub Actions on public repos cover everything. No credit card required.

What happens when the Space sleeps or restarts?

The built-in GitHub Action pings /healthz every 10 minutes to prevent sleeping. If a restart happens anyway, the hourly backup is restored automatically on boot, so memory, sessions and files survive.

Do my tokens stay safe?

The wizard is a static page. Tokens go only to the official GitHub, Hugging Face and Telegram APIs, and secrets are encrypted in your browser before being stored. Still, rotate your GitHub PAT after deploying — that's good hygiene for any automation.

Can I install my own packages?

Yes — set EXTRA_PIP_PACKAGES, EXTRA_APT_PACKAGES or EXTRA_NPM_PACKAGES in Space settings, or drop commands into the persistent hfkit-boot.sh file. They run at every boot.

Which models can the agent use?

Whatever you connect in the router dashboard, plus ~78 keyless web models from the bundled OmniRouter (Qwen, Gemini guest mode, …) that work with zero API keys.

Can I use this if I don't need Telegram?

Absolutely — skip the Telegram step in the wizard. The dashboards and APIs work on their own.

Your own AI server. One free Space.