free-hermes

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 10 Open GitHub ↗

Run Nous Research's Hermes Agent on Fly.io for ~$0/month while idle. Suspends automatically when unused and wakes instantly on inbound Telegram webhooks or scheduled HTTP pokes.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🪽 free-hermes

> Run **Nous Research's Hermes Agent** on Fly.io for ~$0/month while idle. Suspends automatically when unused and wakes instantly on inbound Telegram webhooks or scheduled HTTP pokes.

---

## 🏗️ Architecture Overview

```
Telegram Webhook (HTTPS) ──┐
                           ├──▶ Fly Proxy ──▶ Wakes Machine ──▶ Hermes Gateway (:8644)
cron-job.org HTTP Poke ───┘                                           │
                                                                       ▼
                                                       Fly Volume mounted at /opt/data
                                                  (config, API keys, sessions, skills, memory)
```

---

## ✨ Features

- **Scale-to-Zero Compute**: Costs ~$0/month when idle. Compute bills only accrue while actively processing messages.
- **Instant Wakeup**: Wakes from suspended state in ~1 second upon receiving an inbound HTTPS request.
- **Telegram Webhook Mode**: Eliminates continuous polling so the Fly machine can sleep safely between interactions.
- **External Cron Integration**: Compatible with [cron-job.org](https://cron-job.org) (`external-cronjob` skill included) for $0 extra compute scheduled tasks.
- **Persistent Storage**: All configuration, session history, memory, and skills are safely stored on a dedicated Fly volume (`/opt/data`).

---

## ⚡ Quick Start

### Prerequisites
- [Fly.io Account](https://fly.io) & `flyctl` CLI installed and logged in.
- Model Provider API key (Ollama Cloud, OpenRouter, Anthropic, OpenAI, etc.).
- Telegram Bot Token from [@BotFather](https://t.me/BotFather) (`/newbot`).
- Your numeric Telegram User ID from [@userinfobot](https://t.me/userinfobot) (for access whitelisting).

### 1. Initialize Fly App & Volume
Edit `fly.toml` to set your desired `app` name and `primary_region`:
```bash
fly apps create <your-app-name>
fly volumes create hermes_data --size 1 --region sin -a <your-app-name>
```

### 2. Deploy Machine
```bash
fly deploy --ha=false
```
> ⚠️ **Note**: Hermes is stateful — always deploy with `--ha=false` to enforce a single machine instance.

### 3. Run Interactive Setup Wizard
```bash
fly machine list -a <your-app-name>
fly machine start <machine-id> -a <your-app-name>
fly ssh console --pty -a <your-app-name> -C "hermes setup"
```
*(The `--pty` flag is required for interactive terminal menus).*

---

## 📡 Webhook Mode (Load-Bearing Setting)

Hermes defaults to long-polling, which keeps the machine awake 24/7. **Webhook mode** allows Fly Proxy to wake the machine only when a message arrives.

Add the following three variables to `/opt/data/.env` via `fly ssh console`:
```env
TELEGRAM_WEBHOOK_URL=https://<your-app-name>.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET=<64-character-random-hex>
TELEGRAM_WEBHOOK_PORT=8644
```
*(Generate secret with `openssl rand -hex 32`)*.

Restart the machine to register the webhook with Telegram:
```bash
fly machine restart <machine-id> -a <your-app-name>
```

### Verify Webhook Health
```bash
curl "https://api.telegram.org/bot<BOT_TOKEN>/getWebhookInfo"
```
*Healthy response:* `"url": "https://<your-app-name>.fly.dev/telegram"`, `pending_update_count: 0`.

---

## ⏰ Scheduled Tasks (External Cron)

Because in-container cron processes freeze when scale-to-zero machines suspend, scheduled jobs are triggered via external HTTP pokes from **[cron-job.org](https://cron-job.org)**.

To enable your Hermes agent to manage your cron jobs automatically:
1. Copy the contents of [`skills/external-cronjob/SKILL.md`](skills/external-cronjob/SKILL.md).
2. Paste it directly into your Telegram or CLI chat with your Hermes agent.
3. Instruct your agent: *"Create a new skill from this documentation and save my cron-job.org API key: `<YOUR_API_KEY>`"*.

Just like that, your Hermes agent gains the full ability to programmatically create, update, list, and manage automated `cron-job.org` schedules!

---

## ⚙️ Configuration Reference

---

## 🛠️ CLI Operations & Troubleshooting

```bash
# Wake suspended machine & connect interactive console
fly machine start <machine-id> -a <your-app-name>
fly ssh console --pty -a <your-app-name>

# Inside console:
hermes              # Chat with agent REPL
hermes setup        # Run full setup wizard
hermes doctor       # Check system health
```

### Common Gotchas

---

## 📄 License

MIT License. Built on [Nous Research's Hermes Agent](https://github.com/NousResearch/hermes-agent).

free-hermes

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README