ChatHermes is an autonomous-agent SaaS built on Nous Research's Hermes 4 and Moonshot AI's Kimi K2 Thinking — the official sponsors of the Hermes Agent Creative Hackathon. It pairs streaming multi-model chat with persistent memory, real tools, and agent infrastructure that lets a paid user spin up their own dedicated server. The same code that runs chathermes.com is in this repo.

This documentation covers everything you need to: install ChatHermes, configure it, use the public REST API, build skills, integrate Telegram, deploy a private agent, and self-host the whole thing.

Three install paths. Pick one.

Option 1 — Docker Compose

The recommended path. One command, works on macOS, Linux, Windows / WSL.

git clone https://github.com/ai-co-id/chathermes.git
cd chathermes
./bin/setup.sh           # interactive .env wizard (60s)
docker compose up -d
# → open http://localhost:7000

Option 2 — Hetzner one-click

If you already have a Hetzner Cloud token. Cloud-init bootstraps Bun + Docker + clones repo + writes .env + runs docker compose up.

curl -X POST https://your-self-host.com/api/deploy/hetzner \
  -H "Content-Type: application/json" \
  -d '{
    "token": "hcloud_...",
    "server_type": "cx22",
    "location": "nbg1",
    "llm_keys": { "nous": "..." }
  }'

# Returns: { ok: true, ip, url, ssh_command }

Option 3 — Bun runtime

No Docker. Requires Bun ≥ 1.3 and Node ≥ 22.

# Orchestrator
cd orchestrator
bun install
bun run src/index.ts &

# Web (in another terminal)
cd web
bun install
bun run build
PORT=7000 ORCH_URL=http://127.0.0.1:7010 bun run start

ChatHermes reads everything from environment variables. The minimum viable .env:

PUBLIC_BASE_URL=http://localhost:7000
SESSION_SECRET=$(openssl rand -hex 32)
NOUS_API_KEY=hf_...     # OR another LLM provider key — pick one

Everything else degrades gracefully. See the full env var reference below.

Provider keys

You need at least one LLM provider configured. ChatHermes supports:

The agent has 14 tools available during chat. All are real APIs — no mockups. Tools are called via <tool_call> XML blocks in the assistant response and parsed by the orchestrator.

Skills are user-toggleable capabilities listed at /app/skills. The system prompt mentions which are active for the user; the agent uses that context to decide when to invoke tools.

Twelve skills ship enabled by default:

• Research — web_search + browse + cite
• Code & Build — vibe coding at /app/projects, publish to /p/<slug>
• Persistent memory — save_memory / recall_memory
• Scheduler — natural-language cron at /app/schedules
• Telegram push — telegram_send via connector
• Subagent dispatch — Claude / GPT-5 / Kimi parallel reasoning
• Image generation — Flux via Replicate
• Vision analysis — Gemini 2.0 Flash + GPT-4o fallback
• Browser — browse() + fetch_url()
• GitHub recon — github_repo()
• Weather + News — open-meteo + Google News RSS
• Run JS — calculations, regex, JSON parsing

Memory is per-user, scoped via WHERE user_id = ? on every query. The schema:

CREATE TABLE memories (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  topic TEXT NOT NULL,
  body TEXT NOT NULL,
  created_at INTEGER NOT NULL
);
CREATE INDEX idx_memories_user ON memories(user_id, created_at DESC);

Memories are surfaced to the agent two ways:

1. System prompt context — the latest 20 memories are injected into every chat turn's system message.
2. recall_memory tool — the agent calls this explicitly when it needs to look something up before answering personal questions.

Users can read, edit, and delete memories at /app/memory. No black box.

"Build me a landing page for X" → agent generates HTML/CSS/JS that renders live in a sandboxed iframe. Three modes:

Per-plan project quotas enforce free-tier limits. POST /api/me/projects returns 402 if the user is over their monthly cap. GET /api/me/projects/quota returns:

{
  "plan": "free",
  "used_this_month": 3,
  "limit_per_month": 5,
  "is_unlimited": false,
  "remaining": 2,
  "pct": 60,
  "lifetime_total": 12,
  "lifetime_published": 4
}

Projects can be published at /p/<slug> for public preview. The orchestrator injects a "Made with ChatHermes" floating badge into published HTML (this is required by the license).

The public REST API is Bearer-authenticated with API keys created at /app/api-keys. OpenAPI 3.0.3 spec available at /api/openapi.json.

Authentication

curl https://your-self-host.com/api/v1/me \
  -H "Authorization: Bearer ck_..."

Core endpoints

ChatHermes can POST to your endpoints when events fire. Configured at /app/webhooks. Each delivery is HMAC-signed using your webhook secret.

Verifying signatures

import crypto from "node:crypto";

const sig = req.headers["x-chathermes-signature"];
const body = await readRawBody(req);
const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(body)
  .digest("hex");

if (sig !== expected) {
  res.status(401).send("invalid signature");
}

Events

Failed deliveries retry with exponential backoff (3 attempts: ~1s, ~5s, ~30s). After that, the delivery is logged at /admin/email for manual replay.

Connectors at /app/connectors let users wire ChatHermes into external services. Currently shipping: Telegram.

Telegram

1. Talk to @BotFather on Telegram → /newbot → save the token.
2. Open ChatHermes → Connectors → Telegram → paste token → Save.
3. In Telegram, find your new bot → /start — this binds your Telegram user to your ChatHermes account.
4. The agent can now call telegram_send(message) tool to push you messages.

Natural-language cron at /app/schedules. Examples:

• "Daily briefing at 9am — top 5 stories from Hacker News"
• "Every 6 hours — check competitor.com/pricing, notify if changed"
• "Sundays at 8am — summarize what I worked on this week, email it"

The orchestrator parses the natural-language schedule into a cron expression and a target tool chain. When it fires, the agent runs as if the schedule's prompt were sent in a fresh chat.

Free-tier users share a single Hermes Agent proxy on the orchestrator's :19002. Paid-tier users can have a dedicated Hetzner server provisioned for them — fully isolated CPU, fully isolated rate limits, fully isolated tool tokens.

Architecture

// resolveHermesEndpoint() in private_agent.ts
// Free user → shared :19002 (this server)
// Paid user + status=ready → user's dedicated server
// Paid user + status=pending/provisioning → falls back to shared

Provisioning flow

1. Stripe webhook fires customer.subscription.created with active paid status.
2. Orchestrator marks the user as private_agent_status = pending.
3. Gated mode (default): an admin opens /admin/private-agents, clicks Provision per user.
4. Auto mode: set AUTO_PROVISION_PRIVATE_AGENT=true in .env; webhook spawns immediately.
5. Hetzner Cloud API spawns a fresh server with cloud-init that installs Bun + a per-user proxy + auth token.
6. Orchestrator polls readiness; when :19002 answers, status flips to ready.
7. Future hermes-agent requests for that user route to their endpoint.

The deploy logic lives in orchestrator/src/deploy.ts. Two surfaces:

Public one-click — /deploy/hetzner

Anyone with a Hetzner token can paste it, pick a server type and region, paste at least one LLM API key, and click Deploy ChatHermes. Cloud-init bootstraps the new server in around 90 seconds.

Admin fleet management — /admin/hetzner

Admins set the Hetzner token once via the UI (stored in system_settings), then manage all servers in their account: list, status, power on/off/reboot, delete. Servers labeled app=chathermes are highlighted as managed.

Before going live with self-hosted ChatHermes:

• HTTPS — set up nginx + Certbot. See INSTALL.md Path 3.
• SESSION_SECRET — generate with openssl rand -hex 32. Don't reuse the example value.
• ADMIN_EMAILS — set in .env to grant your email admin role on first signup.
• Backups — set up cron to sqlite3 .backup the SQLite file daily, and rsync off-server.
• Resend — verify your domain at resend.com/domains for magic links.
• Stripe — set up products + webhook endpoint. See INSTALL.md "Optional integrations".
• Hermes Agent native — for the hermes-agent model option, install nous-hermes-agent separately. The orchestrator's shared proxy works without it (proxies to Nous API directly).
• Required Attribution — don't strip _attribution.ts. The runtime guard refuses to start without it. This is the license.

Every environment variable. Copy orchestrator/.env.example to orchestrator/.env and fill what you need.

ChatHermes is licensed under the ChatHermes Open Source License v1.0 — AGPL-3.0 with a Required Attribution Addendum and Trademark Reservation.

The runtime guard in orchestrator/src/_attribution.ts refuses to start the orchestrator if the attribution module is tampered. See /opensource for full terms.