# Hermes-in-a-Box
One-button push → your own AI agent that talks to you on Telegram, does research, builds things, and remembers everything.
## What the user gets
A new user clicks a single button and walks away with:
1. A Telegram bot that responds to their messages with Claude-powered AI
2. A conversation memory that persists across chats
3. Access to web search, audio generation, and the full tool suite
4. A personal log (like log.buildstuff.ai) where long responses get posted
5. A task queue so they can say "build me X" and it actually happens
## What "one button" actually means
The user provides:
- A Telegram bot token (BotFather gives this in 30 seconds)
- An Anthropic API key (or they ride on a shared pool with rate limits)
Everything else is provisioned automatically.
## Architecture
### Tier 1: Hosted Hermes (no infrastructure needed)
The user's Telegram bot webhook points to a shared Cloudflare Worker. The Worker:
1. Receives the Telegram message
2. Looks up the user's config in D1 (API keys, personality, memory)
3. Runs the two-phase Claude pipeline (triage → response)
4. Sends the reply back through Telegram
5. Logs the request/response pair to D1
Stack:
- One shared Worker: hermes-gateway.startuproom.ai
- One D1 database: hermes-multi-tenant
- Tables: tenants, conversations, memory, request_log
- R2 bucket for audio output and file storage per tenant
What this means: Zero infrastructure for the user. Their bot token is just a webhook pointed at our gateway. We handle compute, storage, memory, and tool access.
### Tier 2: Brain-on-a-Box (own machine)
For power users who want a local poller, file system access, and full autonomy:
1. A single install script: curl -sL startuproom.ai/install | bash
2. Installs: bun, claude CLI, the poller, vault.sh, preflight.sh
3. Prompts for Telegram bot token + Anthropic key
4. Sets up launchd agents (poller, watchdog)
5. Registers with the central hub so tasks can be dispatched
This is Brain/Pinky replicated. Same poller, same vault, same ops loop — just on someone else's Mac.
## Provisioning Flow (Tier 1)
``
User clicks "Create My Agent" on startuproom.ai
→ Form: bot token, display name, optional API key
→ POST /api/hermes/provision
→ Creates tenant record in D1
→ Sets Telegram webhook to hermes-gateway
→ Creates personal memory namespace
→ Creates personal log endpoint
→ Returns: "Your agent is live. Message @YourBot on Telegram."
Time from click to working agent: under 10 seconds.
## The Shared Gateway Worker
`
POST /webhook/:tenant_id
→ Telegram sends message here
→ Look up tenant config
→ Load conversation history (last N messages from D1)
→ Load tenant memory (personality, preferences, context)
→ Phase 1: Triage (classify message: chat, task, question, building)
→ Phase 2: Response (call Claude with full context)
→ If response > 4096 chars: post to tenant's log, send link
→ Send response via Telegram
→ Log request/response to D1
## Database Schema
`sql
-- Tenant registry
CREATE TABLE tenants (
id TEXT PRIMARY KEY,
display_name TEXT NOT NULL,
telegram_bot_token TEXT NOT NULL,
anthropic_key TEXT, -- null = shared pool
personality TEXT DEFAULT '', -- system prompt additions
created_at TEXT NOT NULL,
active INTEGER DEFAULT 1
);
-- Conversation history
CREATE TABLE conversations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
tenant_id TEXT NOT NULL,
chat_id TEXT NOT NULL,
role TEXT NOT NULL, -- 'user' or 'assistant'
content TEXT NOT NULL,
timestamp TEXT NOT NULL,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
-- Per-tenant memory (like our MEMORY.md but in D1)
CREATE TABLE memory (
id INTEGER PRIMARY KEY AUTOINCREMENT,
tenant_id TEXT NOT NULL,
type TEXT NOT NULL, -- 'user', 'feedback', 'project', 'reference'
slug TEXT NOT NULL,
content TEXT NOT NULL,
updated_at TEXT NOT NULL,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
-- Full request/response log
CREATE TABLE request_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
tenant_id TEXT NOT NULL,
chat_id TEXT NOT NULL,
input_text TEXT NOT NULL,
output_text TEXT NOT NULL,
model TEXT NOT NULL,
tokens_in INTEGER,
tokens_out INTEGER,
duration_ms INTEGER,
timed_out INTEGER DEFAULT 0,
timestamp TEXT NOT NULL,
FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
``
## What each tenant gets automatically
| Feature | How |
|---------|-----|
| Telegram bot | Their token, our webhook |
| Conversation memory | Last 50 messages loaded per chat |
| Persistent memory | D1 memory table, same types as our file-based system |
| Personal log | log.buildstuff.ai/:tenant_id/:post_id |
| Request logging | Every interaction stored, browsable |
| Audio generation | Via shared audio-factory MCP |
| Web search | Via shared WebSearch tool |
| Timeout handling | Long responses auto-posted to log, link sent in chat |
## Monetization path
- Free tier: Shared Anthropic API pool, 50 messages/day, Haiku model
- Pro tier ($29/mo): Own API key or higher shared limits, Sonnet model, audio generation, priority queue
- Builder tier ($99/mo): Full Claude Sonnet/Opus, task queue, file system access (Tier 2), custom tools
## What to build first (MVP)
1. hermes-gateway Worker — multi-tenant Telegram webhook handler with D1 storage
2. Provision endpoint — creates tenant, sets webhook, returns confirmation
3. Simple onboarding page on startuproom.ai — paste bot token, click go
4. Request logging — every interaction stored from day one
Estimated build time: 1-2 sessions. The two-phase Claude pipeline from the existing Telegram bot is the starting point — it just needs tenant isolation added.
## Why this is a big deal
Right now, getting an AI agent that actually does things (not just chats) requires: a server, API keys, a bot framework, memory management, tool integration, logging, monitoring. That's a weekend project for a developer and impossible for everyone else.
Hermes-in-a-Box makes it: paste a bot token, click a button, talk to your agent. The infrastructure disappears. What's left is the relationship between a person and their AI — which is the only part that matters.