Source: raw/Hermes_Agent_Masterclass_-_1._Installation_Setup_Basic_Commands.md, raw/Hermes_Agent_Masterclass_-_2._Deploy_to_VPS_Connect_to_Telegram_Discord_etc..md, raw/Hermes_Agent_Masterclass_-_3._Memory_Plugins_Honcho_and_Obsidian.md, raw/Hermes_Agent_Masterclass_-_4._Skills.md — first 4 episodes of an 11-episode YouTube masterclass (creator runs the onchainaigarage.com / AI Garage Weekly newsletter; full series staged for a Skool community launching June). Recorded against Hermes Agent ~v0.9.0 through v14, MIT, ~7,000 GitHub stars / ~300 contributors at recording.

A cohesive, build-it-live walkthrough that takes a brand-new Windows/WSL2 machine from zero to a 24/7 Hermes agent reachable from Telegram and Discord, with a working memory stack and a self-built skill. This article captures the concrete commands, config paths, character limits, and gotchas from each episode. It deliberately does not re-explain material already covered in depth elsewhere in this topic — see Nate Herk’s 1-hour course (closest sibling: VPS/Telegram/cron), RoboNuggets 15-min intro, the Security Model, MemoryKit + Hermes Console (memory/Obsidian), and Skill Bundles.

Key Takeaways

  • Install is one curl-style command from the nousresearch/hermes-agent repo plus a full-vs-quick setup wizard. On Windows it runs only under WSL 2 (Ubuntu default; the creator uses Debian); macOS and Linux are native.
  • Everything lives in ~/.hermes/config.yaml (settings), .env (secrets/API keys), memories/ (memory.md + user.md), sessions/, skills/, logs/, state.db. Edit the top three by hand if needed; never hand-edit sessions/ or cron — ask the agent.
  • One gateway, 16 platforms. You do not run a separate agent per channel. A single long-running gateway process (installed as a systemd service) exposes the same agent (same memory/sessions/skills) to Telegram, Discord, Slack, iMessage, WhatsApp, WeChat, etc.
  • Backend is a single setting (hermes setup terminal) — Local, Docker (sandbox), or SSH/VPS. Switching backends does not reinstall Hermes or move your memories/skills; it only changes where shell commands execute.
  • Memory is four stackable layers — built-in markdown (memory.md/user.md, hard char caps), always-on FTS5 session search over state.db, one pluggable external provider (Honcho/Memo/Hindsight/Supermemory — only one active at a time, switching does not migrate data), and the Obsidian skill (a skill, not a plugin).
  • Skills are just skill.md files under ~/.hermes/skills/<category>/<name>/. Two required front-matter fields (name, description); the description is the picker hint — vague descriptions never get invoked. Progressive disclosure keeps ~80 bundled skills affordable: only names+descriptions load until a skill fires.
  • Hermes writes its own skills via a background review fork after qualifying turns (5+ tool calls, error-recovery, user correction, novel workflow), and an autonomous curator (v12+) grades/prunes/consolidates them on a 7-day cron. Pin anything you don’t want touched.

Part 1 — Install & Basic Commands

Source: raw/Hermes_Agent_Masterclass_-_1._Installation_Setup_Basic_Commands.md

Install (Windows via WSL 2)

  • Run wsl --install in PowerShell (Administrator) → installs Ubuntu by default. Requires Windows 10+. Launch the distro by typing wsl.
  • Hermes ignores your current directory and always installs to ~/.hermes (i.e., home/<user>/.hermes).
  • Run the quick-install command from the nousresearch/hermes-agent GitHub repo (top of the README). It installs dependencies (Python, Git, Node.js) and compiles. You’ll need your sudo password for build tools.
  • After install you’re offered full setup vs quick setup (the course does full setup to tour every option).

Full-setup wizard options (in order shown)

  • Provider — NousPortal (Nous’s own subscription), OpenRouter, Anthropic (Claude via API key or Claude Code), OpenAI Codex, Qwen, GitHub Copilot, Hugging Face inference, more. Course uses OpenRouter (get key at openrouter.com, requires a card + a few credits; key looks like sk-...). Default model shown was Opus 4.6; course picks a cheaper model (MiMo V2 Pro).
  • Fallback/rotation — add a second API key per provider; Hermes rotates when one is exhausted/rate-limited (preserves primary, reduces interruptions).
  • Max tool calling — set to e.g. 90 (caps how many tool calls per turn).
  • Tool progressall / off / new-only (controls how many tool calls render in chat).
  • Context compression threshold — higher = compress later; course used 0.75. Tune per model’s context-window tolerance.
  • Session reset mode — inactivity / daily / both / never. Course chose inactivity + daily reset, daily reset at midnight. Rationale: each message grows conversation history → growing API cost.
  • Browser / search / image-gen — Firecrawl or Tavily for search (Tavily = AI-native, has a generous free tier; DuckDuckGo is free too); FAL/Flux 2 Pro for image gen (paid; sign in with GitHub for a key). All deferrable — “keep defaults, configure later.”
  • Platforms (Telegram etc.) are configured later — deferred to Part 2.

Top CLI commands

CommandWhat it does
hermes / hermes chatLaunch the TUI chat
hermes gatewayStart the messaging gateway (needed for Telegram/Discord)
hermes doctorCheck for issues
hermes modelOpen the provider/model switcher
hermes statusFull config dump — project path, model, provider, which API keys are set/unset, auth providers
hermes insightsSession insights (empty on a fresh install)
hermes sessions browseCurses picker to resume a past session
hermes skills browseDiscover/install skills (50+ shown; trust labels: official / trusted / community)
hermes skills search <query>Search skills by keyword (e.g. email)
hermes config showShow configuration
hermes updatePull the latest (the agent moves fast — updated mid-recording)
hermes setupRe-run setup; “quick setup, configure missing items only” fills in gaps (e.g. adding a Tavily key)
  • Gotcha: after first install you must reload your shell before the hermes command resolves.

In-chat slash commands

/exit, /new (fresh session), /model (swap model mid-session, no restart — e.g. switch to zai/glm-5.1), /fast (priority routing through OpenAI/Anthropic), /bg (background task while you keep chatting), /btw <q> (side question mid-work), /q <prompt> (queue a next prompt), /compress (manually compact context), /skills (browse/invoke), /yolo (toggle dangerous-command approvals — use with care), /help (lists every slash command, tool, and installed skill).

  • ~/.hermes/ layout (where things live): config.yaml = main settings (editable), .env = secrets/API keys (editable), memories/ (editable), sessions/ = every past conversation (don’t hand-edit), skills/, logs/ (agent + error logs), state.db. On Windows, browse via \\wsl$ → Linux → your distro → home/<user>/.hermes.
  • First task demo: a competitor-research prompt (AI children’s-book business) using Tavily web search — produces a tiered competitive landscape + market-gap report, and the agent silently begins writing user.md.

Part 2 — Deploy to VPS + Telegram/Discord

Source: raw/Hermes_Agent_Masterclass_-_2._Deploy_to_VPS_Connect_to_Telegram_Discord_etc..md

Backends (6 total; course uses 3)

Local · Docker (sandbox) · SSH/VPS (always-on) · Modal (serverless, hibernates when idle — bad for a 24/7 gateway) · Daytona (managed team workspaces) · Singularity (free HPC cluster, Docker banned). Local + Docker + VPS are complementary, not redundant — run Docker/local while at your machine, VPS while away.

Docker (hardened local sandbox)

  • It is one settinghermes setup terminal → switch backend from local to docker. You do NOT reinstall Hermes inside the container. Your install, config, memories, sessions, skills stay on the host; only the terminal backend (where shell commands run) changes.
  • Install Docker Desktop for Windows (not the Linux build) — it has built-in WSL integration. Enable it under Settings → Resources → WSL integration.
  • Verify with docker version inside WSL before switching.
  • Wizard prompts after switching: keep default Docker image (Enter), persistent file system across sessions = yes, CPU cores (e.g. 1), memory (accept default).
  • Proof of isolation: ask the agent to run hostname (returns a container ID) and create docker_test.txt — the file exists only inside the container, not on the host. Asking it to read ~/.ssh/id_... returns “doesn’t exist” because containers only see explicitly mounted paths. SSH keys, GitHub creds, and host env vars are safe by default.

VPS (DigitalOcean $6 droplet)

  • Provider: DigitalOcean (course pick; Hetzner noted as an EU alternative). Create a Droplet → region nearest you → OS: Ubuntu → Basic plan, shared CPU, regular type → $6/mo tier = 1 vCPU / 1 GB RAM / 25 GB storage / 1000 GB transfer.
  • Why $6 / 1 GB: 1 GB RAM is “the floor for smooth Hermes operation — below it the browser tools struggle; above it is overkill for most use.”
  • SSH key auth (more secure than passwords): generate with ssh-keygen (prompts for save path/name + passphrase) → produces id_rsa + id_rsa.pub → paste the .pub contents into DigitalOcean’s “Add SSH Key”. The private key never leaves your machine.
  • Connect: ssh root@<DROPLET_IP>.
  • Install on the VPS = the exact same install command from nousresearch/hermes-agent. Run setup again (quick is fine).
  • Security caveat called out explicitly: the course leaves it as root login on the open internet for demo speed; in production set up a non-root user + firewalls.

Gateway + Telegram + Discord

  • The gateway is one long-running process; each platform is an adapter translating that platform’s message format into Hermes’s common format; all adapters feed one shared agent.
  • Telegram: in Telegram, message @BotFather/newbot → name + username → copy the bot token → paste into the Hermes setup telegram bot token prompt. Get your own numeric user ID from @userinfobot (/start → it returns your ID) → use it to allow-list so only you can talk to the bot. (Never expose a bot token.)
  • Discord (more complex): go to discord.com/developers/applicationsNew Application → in the Bot tab scroll down and enable both Server Members Intent and Message Content Intentgotcha: without Message Content Intent the bot receives empty messages and silently returns nothing. Reset Token to generate the bot token Hermes needs. Then OAuth2 → URL Generator → scopes bot + application commands → bot permissions: Send Messages, Manage Threads, Embed Links, Attach Files, Read Message History → open the generated URL → add the bot to your server → Authorize.
  • Install the gateway as a systemd service (wizard: “system service installed and enabled” → start now). Logged in as root, the gateway runs as a user service.
  • Critical persistence gotcha: a user systemd service stops when you SSH out. Fix with:
    loginctl enable-linger root
    
    Verify by exiting + re-ssh-ing, then systemctl --user status hermes-gateway → still active. Now it’s truly 24/7.
  • Result demonstrated: the same agent (same memory/sessions/skills) answers from Telegram, Discord, and the CLI — a contractor-quote business idea started in Telegram is continued in Discord and the terminal via session search, for $6/mo.

Part 3 — Memory: Honcho + Obsidian Plugins

Source: raw/Hermes_Agent_Masterclass_-_3._Memory_Plugins_Honcho_and_Obsidian.md(this part overlaps the three-tier memory model already documented in the topic overview and MemoryKit; captured here are the masterclass’s specific caps, mechanics, and the live Honcho/Obsidian setup.)

Layer 1 — built-in markdown (~/.hermes/memories/)

  • Two files: memory.md (projects, environment, decisions, lessons — ~2,200 chars / ~800 tokens) and user.md (who you are, role, prefs, style — the course cites ~375 chars / ~500 tokens in one slide and a 1,375-char default cap later; treat the ~1,375 cap as the configurable limit). Entries are separated by the section sign §. Both load into the system prompt at session start. Total budget ~1,300 tokens. Caps are set in config.yaml under memory (memory char limit + user char limit).
  • Frozen snapshot pattern: memory.md/user.md render into the system prompt once at boot. Mid-session memory tool writes hit disk immediately but do not appear in the system prompt until the next session. Why: the system prompt carries the prompt-cache control — mutating it mid-session would invalidate the cache on every memory write. Gotcha to remember: memory writes show up next session, not this one. Tool responses show live disk state; the system prompt is the boot snapshot.
  • memory tool actions: add, replace, removeno read (content is auto-injected at boot). Replace/remove use substring matching via an old_text param (a short unique substring is enough; matching 2+ entries errors). Duplicate detection is a silent no-op (adding identical content returns success, adds nothing — important because LLMs retry).
  • Four “invisible” safety features: (1) cap-as-feature — hitting the cap errors, forcing the agent to consolidate rather than hoard (each header shows current usage %); (2) save/skip policy ships built in (save: prefs, environment, facts, corrections, conventions, completed work, explicit requests; skip: trivia, web-searchable facts, raw dumps, session randomness) — so you don’t need a separate memory-manager agent; (3) dedupe no-op (above); (4) injection scanning before write — entries are scanned for prompt-injection / credential-exfil (SSH keys baked into “facts”, invisible Unicode) before acceptance, closing a persistent-compromise vector. Seed user.md yourself with a few goals/projects for good initial context.

Layer 2 — FTS5 session search (~/.hermes/state.db)

  • Every CLI and gateway session (every Telegram/Discord message) is indexed into a SQLite state.db. The agent has a session-search tool it calls autonomously when prior context seems relevant; results come back through a Gemini-flash summarization layer so it doesn’t re-read raw transcripts. New: auto prune + vacuum on state.db at startup — so you can skip the old cron-to-prune-sessions advice; it self-maintains. Use case: “what were the top 10 names we brainstormed for X?” — too granular for memory.md, so it hits state.db.

Layer 3 — external provider plugins (one active at a time)

  • Pluggable memory provider ABC (since v7). Rule: only one provider active — can’t run Honcho + Memo together; switching does not migrate data. Layer 1 markdown stays on regardless. When a provider is active Hermes auto: injects provider context, prefetches per turn, syncs turns after each response, extracts on session-end, and adds provider-specific tools. CLI: hermes memory setup / hermes memory status / hermes memory off.
  • Landscape (creator’s agent’s own research): Memo (most stars; server-side LLM fact extraction + second-pass insert/update/delete/no-op → less recall noise, adds write cost), Hindsight (knowledge graph + entity resolution + 3 retrieval strategies + Reflect synthesis; densest), Supermemory (multi-container partitioning, context-fencing, session-graph ingest), Honcho (Nous first-party, dialectic user modeling).
  • Honcho setup demo (cloud): sign up at app.honcho.dev (adding a card gave 100 free credits at recording) → get API key → hermes memory setup → pick Honcho → cloud/local = cloud → paste key → username, AI-peer name (Hermes), workspace ID → observational mode (directional / unified) → write frequency (async) → recall mode (hybrid, uncapped) → dialectic cadence (every turn / every other turn — recommended 2) → dialectic reasoning level (low/medium/max). Config lands at ~/.hermes/honcho.json. Tools added to chat: honcho conclude (server-side dialectic reasoning), honcho context, honcho profile, honcho search. Status/management: hermes honcho status, hermes honcho peer, hermes honcho map (map a directory to a session). Hierarchy: workspace → peers → sessions → messages; each Hermes profile gets its own AI peer in a shared workspace. v0.11.0 shipped a major Honcho overhaul (auto context-injection per turn, runaway-think-call cost safety, session isolation).

Layer 4 — Obsidian (a skill, not a plugin)

  • Not in the memory-provider slot — it’s a bundled skill at skills/note-taking/obsidian/. File-system-based: no MCP server, no Obsidian app required (it runs headless on Linux). Config via env var OBSIDIAN_VAULT_PATH. (Gotcha: the old obsidian_vault config option is no longer used — use the env var.) To curate the notes in the desktop app, install Obsidian locally and Open folder as vault at the same path.
  • Invoke with “use the Obsidian skill” or the /obsidian slash command (read/search/create notes). Best for large, structured project knowledge (the demo: HVAC providers + equipment models written as cross-linked markdown notes you’ll return to), not simple memory. The agent also auto-created a skill during the demo (local-provider-research) — foreshadowing Part 4.

Part 4 — Skills

Source: raw/Hermes_Agent_Masterclass_-_4._Skills.md

Anatomy of a skill.md

  • A skill is its skill.md — a plain markdown file. No registration, no build step, no compiler. Path: ~/.hermes/skills/<category>/<name>/skill.md. Optional sibling dirs: reference/ (on-demand context), templates/ (boilerplate), scripts/ (executable helpers — usually Python), assets/ (binaries).
  • Front matter — only two required fields: name and description. Optional: platforms, version, author, license, metadata/tags. Body conventions seen across bundled skills: when to use, procedure, pitfalls/troubleshooting, verification.
  • The description is the picker hint — the only thing the agent sees in the skills list. A concrete description fires reliably; a vague description never gets picked, and the body never matters. The body’s when to use is the expanded trigger the agent reads only after picking the skill.
  • Progressive disclosure is what makes ~80 bundled skills viable: loading all 80 bodies every turn = token bloat. Instead the agent sees only title + description until it picks a skill, then only that body loads; everything else stays on disk.
  • Hot reload: drop a skill folder in → it exists on next boot or run /reload skills (hot reload, no restart).

Bundled skills (course tours 5 of ~24 categories, ~80 skills as of v14)

  • Research: archive (free arXiv API), llm-wiki (Karpathy-style wiki as an Obsidian vault), blog-watcher (RSS + summarize), polymarket, research-paper-writing. Demo: “research recent papers about recursive reasoning models” auto-chains archive + paper-summary.
  • GitHub / software-dev: github-pr-workflow (branch→merge), github-code-review, github-repo-management, github-issues (create/triage/label/assign), systematic-debugging, writing-plans (emit a plan before code), subagent-driven-development. All GitHub skills use gh CLI when available, falling back to Git + REST API so they work on any machine.
  • ML Ops: lean core, mostly optional (categorized further into evaluation / huggingface-hub / inference / models / research / training / vector-databases). llama.cpp skill demoed for local-model repo discovery.
  • Productivity: google-workspace (Gmail/Calendar/Drive/Sheets via gwscli or Python), notion (full overhaul for the new dev platform — read/write pages + DBs), linear (GraphQL), nano-pdf, powerpoint, ocr, documents. PowerPoint skill demoed turning a markdown concept file into a .pptx; it ships scripts/ helpers (add-slide, cleanup).
  • Creative: manim-video, excalidraw (programmatic hand-drawn diagrams), p5js, comfyui (Stable Diffusion via ComfyUI CLI/REST), touchdesigner (MCP), humanizer (strip AI-isms / em-dashes), pixel-art. Pixel-art demo shows scripts + a reference/palettes file (e.g. SNES palette) — and an ambiguous-skill-name disambiguation (qualified as creative/pixel-art).
  • Optional categories: ~17 more (blockchain, finance, health, security…) not bundled; browse via /skills list.

Where skills come from (the skills hub)

  • Bundled (ship with Hermes) · Official optional (opt-in extras, repo-maintained) · skills.sh (Vercel’s public library, searchable from CLI) · GitHub taps (v4 added huggingface/skills; default taps include OpenAI/Anthropic skills; the HuggingFace community index auto-surfaces in hermes skills browse with no config; add your own with hermes skills tap add) · well-known/skills marketplaces (claw-hub, lobe-hub, claw-marketplace) · direct URL / drop-the-folder-in.
  • Install pattern is uniform: hermes skill browse → install → an automatic security scan runs → then /reload skills to hot-enable. Safety stance from the creator: prefer bundled / known-official sources; for anything unverified, build the skill yourself rather than dropping in untrusted skills (real prompt-injection / malicious-skill risk).

Self-written skills + the curator

  • The agent writes its own skills via a skill_manage tool (actions: create / patch / edit / delete + file-management for multi-file skills). After qualifying turns Hermes spawns a background review fork (substantially improved in v12) — rubric-graded, scoped strictly to memory + skills tools (can’t reach shell/web), inherits the parent’s provider/model (not a cheap fallback). It reads the trajectory and asks “was this reusable?” If yes it writes a new skill.md (marked agent-created since v3, so the curator can prune unpinned agent-created skills more aggressively).
  • Triggers (per docs): complex task (5+ successful tool calls), recovery (hit errors then found a working path), correction (user pushed back, agent adjusted), or a novel reusable workflow. The docs call this the agent’s procedural memory.
  • The Curator (landed v12, enhanced v13) = autonomous skill maintenance on a 7-day cron (runs on the gateway’s cron ticker; logs to logs/curator/; configured under auxiliary.curator in config.yaml, model-selectable like any auxiliary slot). It grades every skill against a rubric, prunes dead/unpinned skills, and consolidates drifted near-duplicates. v13 made manual hermes curator run synchronous + added operator subcommands (archive, prune, list, archive, status, pin). Safety: bundled + hub-installed skills are gated (curator can’t touch them); pin custom/agent-created skills with hermes curator pin <category>/<name> → “pinned, the skill will bypass auto transitions.”

Skills vs plugins (and portability)

  • Three plugin types: memory providers, context engines, and specialized backend slots (image-gen, model providers, platforms, video-gen — the things you set in the install wizard). Skills are a separate subsystem plugins can bundle but don’t own.
  • Decision rule: if it changes what the agent knows/how it does something → skill; if it changes Hermes’s actual capabilities/interface (new code, UI, API routes) → plugin.
  • Per-surface + per-OS scoping: a skill can be limited by platform/OS (auto-hidden on incompatible OS) and enabled/disabled per channel (CLI / Telegram / Discord) via hermes skill interactive TUI — e.g. keep heavy ML skills CLI-only.
  • Portability: Hermes skill.md is compatible with the agentskills.io standard (stated in the README + skill-tool code) — the same skill file runs in Claude Code, Cursor, Codex, etc. Skills are portable IP.
  • Worked example: the course builds a business/unit-lookup skill (inputs: HVAC model #, contractor, quoted price → search the Obsidian vault → web-lookup specs if missing → write a vault node + image search → compose a markdown spec card). Hermes builds it using another skill, hermes-agent-skill-authoring, then runs it to produce a spec card with brand/SEER/tonnage + sources.

Try It

  1. Install on your real OS. Windows: wsl --install (PowerShell admin) → launch wsl → run the install command from github.com/nousresearch/hermes-agent. Reload your shell, then hermes doctor.
  2. Configure a provider in the setup wizard — OpenRouter (sk-...) or, for the cheapest non-OSS path, OpenAI Codex via ChatGPT OAuth (see Nate Herk’s course). Set a fallback key, daily reset at midnight, compression ~0.75.
  3. Harden locally with Docker before exposing anything: install Docker Desktop (Windows build, enable WSL integration) → hermes setup terminaldocker. Verify isolation: ask the agent to run hostname and to read ~/.ssh/ (should fail).
  4. Go 24/7 on a $6 DigitalOcean droplet (Ubuntu, 1 GB) → ssh-keygen → add the .pubssh root@IP → reinstall Hermes → install the gateway as a systemd serviceloginctl enable-linger root → verify with systemctl --user status hermes-gateway after re-SSH.
  5. Wire Telegram (@BotFather /newbot → token; @userinfobot → your ID to allow-list) and Discord (enable Message Content Intent + Server Members Intent; OAuth2 URL with bot+application commands and Send Messages/Manage Threads/Embed Links/Attach Files/Read History).
  6. Seed memory + add a provider. Edit ~/.hermes/memories/user.md with a few goals/projects. Optionally hermes memory setup → Honcho (cloud, app.honcho.dev key, cadence 2). Point OBSIDIAN_VAULT_PATH at a real vault for structured project knowledge.
  7. Build one skill by hand, then let Hermes maintain it. Ask it to create a business/<name> skill via a written spec; /reload skills; run it; then hermes curator pin <category>/<name> so the 7-day curator leaves it alone.

Open Questions

  • user.md cap discrepancy — Part 3 cites both “~375 chars / ~500 tokens” and a “1,375-char default” for user.md; the exact default cap and its config.yaml key should be confirmed against the official docs. ^[ambiguous]
  • Version drift — episodes span ~v0.9.0 to v14 and the series is moving fast (curator v12→v13, Honcho v0.11.0 overhaul, session-search auto-prune). Specific subcommands/flags may have changed; verify against the current nousresearch/hermes-agent changelog before quoting.
  • Episodes 5-11 not yet ingested — Part 4 trails episode 5 (models & providers: 20+ providers, smart routing, fallback chains, SuperGrok OAuth with 1M-token context, the OpenAI-compatible local proxy turning a ChatGPT/Claude subscription into a Codex endpoint, auxiliary models). The remaining masterclass episodes are not in this article.
  • Honcho free-credit promotion — the “100 free credits on adding a card” at app.honcho.dev may not persist; confirm current pricing before relying on it.