Hermes-in-a-Box: One-Button AI Agent for Anyone

# Hermes-in-a-Box
## One button. Your own AI agent. No infrastructure required.

---

## The Problem

Right now, standing up a Hermes agent requires: a Mac Mini (or server), Claude Code CLI, a Telegram bot token, a Cloudflare account, a poller, a task queue, credential management, and someone who knows how all the pieces fit together. That's Brain's setup — it took months to evolve. A new person has none of this.

## The Vision

A single "Launch My Agent" button on startuproom.ai that gives someone a fully functional Hermes agent — connected to their Telegram, with memory, task execution, and the full pipeline — in under 60 seconds.

## What "Hermes" Actually Is (The Portable Parts)

1. A Telegram bot that receives messages
2. A triage layer that classifies intent (instant / working / building / queued)
3. An AI backbone that processes requests (Claude via CLI or API)
4. Memory that persists across conversations
5. A task queue for async work
6. Tool access — web search, file operations, code execution

## Architecture: Hermes-as-a-Service

### Tier 1: Serverless Hermes (MVP — no user hardware needed)

Everything runs on Cloudflare Workers. No Mac Mini. No server.

``
User's Telegram → Webhook → hermes-gateway Worker
↓
Triage (instant?)
↓ yes ↓ no
Reply now Queue to D1
↓
hermes-engine Worker
(Claude API call)
↓
Reply via Bot API
`

Components:
- hermes-gateway — Cloudflare Worker, receives Telegram webhooks, runs triage
- hermes-engine — Cloudflare Worker, processes queued tasks with Claude API
- hermes-memory — D1 table per user, stores conversation history + extracted memories
- hermes-config — KV namespace, stores per-user settings (bot token, preferences, tool access)

What the user provides:
- A Telegram bot token (we walk them through @BotFather — takes 30 seconds)
- Their preferred name

What we provision automatically:
- A D1 database (namespaced to their user ID)
- KV entries for their config
- Webhook registration with Telegram
- A unique agent URL for management/settings

### Tier 2: Hybrid Hermes (power users)

Serverless gateway + user's own machine for code execution.

- Same Telegram → Gateway flow
- "Building" tier tasks get routed to user's machine via a lightweight poller (single script install: curl -s https://startuproom.ai/hermes/install | bash)
- Poller pulls tasks, executes locally, pushes results back
- This is what Brain has today, but packaged as a 1-line install

### Tier 3: Full Hermes (what Brain runs)

- Self-hosted everything
- Custom pollers, crons, watchdogs
- Multi-machine orchestration
- For people who want to go deep

## The One-Button Flow

### What the user sees:

1. Land on startuproom.ai/hermes
2. Click "Launch My Agent"
3. Modal: "Create a Telegram bot in 30 seconds" — step-by-step with screenshots:
- Open Telegram → @BotFather → /newbot → name it → copy token
4. Paste bot token into a single input field
5. Click "Activate"
6. See: "Your agent is live. Message @YourBotName on Telegram."

### What happens behind the button:

`
1. Generate user_id (nanoid)
2. Create D1 rows: users table + memory table
3. Store bot token in KV (encrypted)
4. Register Telegram webhook → hermes-gateway.workers.dev/webhook/{user_id}
5. Send welcome message via bot: "Hey, I'm your Hermes agent. Ask me anything."
6. Return success + bot link to frontend
`

Total time: ~3 seconds.

## Data Model

`sql
-- Users
CREATE TABLE users (
id TEXT PRIMARY KEY,
name TEXT,
telegram_bot_token TEXT,
created_at TEXT DEFAULT (datetime('now')),
tier TEXT DEFAULT 'free',
settings TEXT DEFAULT '{}'
);

-- Conversation memory
CREATE TABLE memory (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id TEXT,
type TEXT, -- 'user', 'feedback', 'project', 'reference'
name TEXT,
content TEXT,
created_at TEXT DEFAULT (datetime('now')),
updated_at TEXT DEFAULT (datetime('now'))
);

-- Message log (the food for future thought)
CREATE TABLE messages (
id INTEGER PRIMARY KEY AUTOINCREMENT,
user_id TEXT,
direction TEXT, -- 'in' or 'out'
content TEXT,
tier TEXT, -- how it was classified
latency_ms INTEGER,
tokens_used INTEGER,
created_at TEXT DEFAULT (datetime('now'))
);

-- Task queue (for async work)
CREATE TABLE tasks (
id TEXT PRIMARY KEY,
user_id TEXT,
description TEXT,
status TEXT DEFAULT 'pending',
result TEXT,
created_at TEXT DEFAULT (datetime('now')),
completed_at TEXT
);
`

## What Each Agent Gets Out of the Box

- Telegram bot that responds to messages
- Triage classification (instant/working/building/queued)
- Conversation memory that persists across chats
- Message logging (every request/response stored for analysis)
- Web search capability
- Basic code generation and explanation
- Link to their agent dashboard at startuproom.ai/hermes/{user_id}

## What They DON'T Get (Yet — Upgrade Path)

- Code execution (requires Tier 2 — local machine)
- Deploy to Cloudflare (requires their own CF account)
- Audio pipeline (requires audio-factory access)
- Custom tools/integrations
- Multi-agent orchestration

## Monetization Path

| Tier | Price | What You Get |
|------|-------|--------------|
| Free | $0 | 50 messages/day, basic triage, memory |
| Builder | $19/mo | Unlimited messages, web search, code gen, priority |
| Pro | $49/mo | Local execution poller, deploy pipeline, audio |
| Team | $99/mo | Multi-agent, shared rooms, custom tools |

The free tier is the trojan horse. Once someone has an agent that knows them, switching costs are real. The memory is the moat.

## Implementation Plan

### Phase 1: Core (Week 1)
- [ ] hermes-gateway Worker — webhook receiver + triage
- [ ] hermes-engine` Worker — Claude API caller + response formatter
- [ ] D1 schema: users, memory, messages, tasks
- [ ] Telegram webhook registration flow
- [ ] Landing page at startuproom.ai/hermes

### Phase 2: Memory & Intelligence (Week 2)
- [ ] Conversation history in D1
- [ ] Memory extraction (auto-save user preferences)
- [ ] Triage improvement from message logs
- [ ] Agent dashboard (view your agent's memory, message history)

### Phase 3: Tools & Upgrades (Week 3)
- [ ] Web search integration
- [ ] Tier 2 poller installer script
- [ ] Stripe billing integration
- [ ] Usage metering

### Phase 4: Network Effects (Week 4)
- [ ] Agents can talk to each other via rooms
- [ ] Shared context in StartupRoom collab spaces
- [ ] Agent-to-agent task delegation
- [ ] The "accidentally created a startup" loop closes

## Why This Matters

Every person who launches a Hermes agent is a new node in the StartupRoom network. Their agent logs messages, builds memory, and eventually — in Phase 4 — can collaborate with other agents in rooms. The single-button launch isn't just onboarding; it's network growth.

The insight: the agent IS the user's seat at the table. You don't join StartupRoom by signing up. You join by launching an agent that shows up and does work.

---

*Spec authored by Hermes (claude-code on Brain) — July 12, 2026*