README.md

# Hermes Agent — Bucket Template

**TL;DR We made it easy for you to onboard to Hermes Agent on our infra and recommended open model and config, takes ~3 mins to get started.**

This is a **template** for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

**Steps are simple, takes ~3 mins:**
1. Login to HF locally with `hf auth login`
2. Run `bash <(curl -fsSL https://huggingface.co/merve/hermes-agent-bootstrap/resolve/main/bootstrap.sh)`
3. Enter your telegram bot id and user id as shown [here](#make-a-telegram-bot), run `hermes gateway start`

Start chatting! We also add some use cases [here](#some-useful-things-to-try).

---

## make a Telegram bot

Hermes lives on Telegram — you talk to it from your phone, it answers, it remembers, it pings you when a cron fires. The bootstrap will ask for a bot token, so grab one first:

1. **Bot token.** Message [@BotFather](https://t.me/BotFather), send `/newbot`, pick a display name and a username ending in `bot`. Copy the **HTTP API token** (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`).
2. **Your numeric user id.** Message [@userinfobot](https://t.me/userinfobot). It replies with your id (looks like `123456789`). This goes into `TELEGRAM_ALLOWED_USERS` so only you can DM the bot.

## Inference

Uses **Inference Providers** with `Qwen/Qwen3.6-35B-A3B`. This model is very cheap: $0.15 per million input tokens, $0.95 per million output tokens. If you have [HF Pro](https://huggingface.co/pro), it comes with $2 quota (along with other benefits) giving you many meaningful conversations. If you don't, you can also enter card details and get started. Even quantized versions of this model work well, so I picked this for you. 


**run it in CLI**

If you want to run in terminal, after the bootstrap, open a new shell (or `source ~/.zshrc`) so `HERMES_HOME=~/.hermes-home` is exported, then:

```bash
hermes                       # chat in your terminal
hermes gateway run           # start the Telegram bot in foreground (Ctrl-C to stop)
hermes gateway install && hermes gateway start   # run gateway as a background service
/new                         # inside hermes — reset, fresh context
```

After a reboot the bucket mount is gone; re-run the bootstrap, or remount manually:
```bash
hf-mount start --hf-token "$HF_TOKEN" bucket <your-username>/hermes-agent ~/hermes-bucket
```

### Some useful things to try

**Plug in your notion/obsidian for reminders**

I plugged Notion in it, for my complex to-dos (aka French bureaucracy), it fetches steps online and writes them there and sets up reminders with deadlines it finds online.

**Try different personas**

SOUL.md file in this bucket gives a personality to agent, modify if you like. On top of it, Hermes comes with `/persona` command, you can switch between different personas. It never breaks the character in the SOUL.md, this is another layer on top.

**Setting up cron jobs that require creativity**

```bash
HERMES_HOME=~/.hermes-home hermes cron add "Every morning at 8am, summarize yesterday's HF trending models and DM me"
```

Cron entries land in `cron/` inside the bucket, so clone the bucket on a fresh machine and your schedules come with it.

## Internals

The bootstrap script clones this bucket into your own (`<your-username>/hermes-agent`), mounts it locally, and launches Hermes. Your memories, skills, and cron jobs live in your bucket — they travel with you across machines and never touch this template.

The script will handle many things for you, but for transparency:

1. Install `hf`, `hf-mount`, and Hermes Agent if missing.
2. Duplicate this bucket to your namespace and mount it at `~/hermes-bucket`.
3. Set up `~/.hermes-home` as a local shadow of `HERMES_HOME` — your bucket's config, SOUL, skills, memories, cron, etc. are symlinked in, but `.env` stays local. So your `HF_TOKEN` and Telegram secrets **never reach the bucket**, even if Hermes itself tries to persist them.
4. **Prompt for your Telegram bot token**, find below instructions to get one and paste it.
5. Save secrets to `~/.hermes-home/.env` (local-only, mode 600).
6. Launch Hermes.
---

## What gets copied into your bucket

| Path | What it is |
|---|---|
| `config.yaml` | Hermes config — model, provider, tools, gateway |
| `SOUL.md` | Persona, auto-injected every turn — edit to taste |
| `skills/` | 89 skills shipped with Hermes |
| `.env.example` | Reference template; your real secrets stay in `~/.hermes-home/.env` (local-only, never uploaded) |

Your bucket keeps everything for you: `memories/` (cross-session memory), `sessions/` (transcripts + FTS index), `cron/` (scheduled jobs), `pairing/` (messaging gateway state).

Your bucket is created **private by default** — memories, sessions, and pairings stay yours. The shadow `HERMES_HOME` keeps `HF_TOKEN` and `TELEGRAM_BOT_TOKEN` out of it on top of that. If you want to share your agent (publish a persona, fork-friendly skills bundle), flip the visibility from the bucket's settings page on huggingface.co.

---

## Troubleshooting

- **"Not logged in to Hugging Face"** → run `hf auth login`, then re-run the bootstrap.