diff --git a/CHANGELOG.md b/CHANGELOG.md index c6a22e0..1fdd710 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,23 @@ Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepachangelog.com) flavored. +## 2026-06-17 — Hermes v0.16.0 "Surface" Refresh + +### Added +- **Part 24 — Hermes Desktop App**: the native macOS/Windows/Linux GUI introduced in v0.16. Covers `hermes desktop`, `--include-desktop`, the Cmd+K/Ctrl+K command palette, drag-and-drop + clipboard image paste, the composer model picker, per-session YOLO toggle, voice, management panes, background self-update, uninstall flags, and connecting to a remote Hermes gateway over secure WebSocket (OAuth or username/password, multi-profile, cross-profile `@session`). +- **Part 25 — NVIDIA & Local Hardware**: the run-it-on-your-own-GPU story from the Nous × NVIDIA work. RTX PC / RTX PRO / DGX Spark tiers, a model-agnostic local stack (Ollama / LM Studio / llama.cpp), the DGX Spark playbook, OpenShell kernel-level isolation, NemoClaw + the "Build It Yourself" series, and the built-in NVIDIA Skills Hub tap (CUDA-X, AIQ, cuOpt). +- New hero, desktop, and local-hardware banner graphics under `assets/`. +- Part 22 section 8 "Newer Power Moves (v0.15 → v0.16)": `/undo [N]`, default-interface choice (`cli`/`tui`, `--cli`), the everywhere fuzzy model picker, leaner default skills, free instant `session_search`, `hermes kanban swarm`, and Brainworm/promptware defenses. + +### Changed +- README badges, hero, intro, install section, architecture diagram, "Pick Your Path," "What's New," TOC, and repo map now target Hermes **v0.16.0 (v2026.6.5)** and surface the Desktop + local-hardware paths. +- Collapsed the per-version model cheat-sheet tables in the README and `part1-setup.md` into a light, model-agnostic "bring any model" section — the harness is the durable part; the fuzzy picker + hourly catalog replace memorized leaderboards. +- Canonical install commands updated to `https://hermes-agent.nousresearch.com/install.sh` and the native Windows `iex (irm https://hermes-agent.nousresearch.com/install.ps1)`, plus `hermes portal` Quick Setup and the web System page check-before-update / Debug Share flow. + +### Removed +- v0.14-as-current framing from top-level guidance ("native Windows beta," PyPI-as-new, "Android new in v0.9," 24-part counts). +- Stale per-version model recommendation tables that go out of date every release. + ## 2026-06-03 — Part 19 security schema fixes ### Fixed diff --git a/README-ja.md b/README-ja.md index 8d5ef3a..90b845d 100644 --- a/README-ja.md +++ b/README-ja.md @@ -2,7 +2,7 @@ > [英語版はこちら](./README.md) · このページは入口の要約。本文の章は英語のまま。 -[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)（v0.14.0 まで反映）向けの実戦ガイド + インストール可能な成果物（Skills・設定テンプレ・インフラスクリプト）。 +[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)（v0.16.0 “Surface” まで反映。ネイティブデスクトップアプリと NVIDIA ローカルハードウェアを含む）向けの実戦ガイド + インストール可能な成果物（Skills・設定テンプレ・インフラスクリプト）。 ## ワンコマンドで起動 @@ -15,7 +15,7 @@ curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/m ## 主なコンテンツ -- **24 章の本文**（README 内の章 + `part6`〜`part23`） — v0.14 Foundation、Grok OAuth、`hermes proxy`、LINE/SimpleX、Kanban、`/goal`、Checkpoints v2、Curator、TUI、プラグイン、LightRAG、Telegram、MCP、セキュリティ、可観測性、リモートサンドボックス +- **26 章の本文**（README 内の章 + `part6`〜`part25`） — v0.16 デスクトップアプリ、NVIDIA / DGX Spark ローカル実行、v0.15 Velocity マルチエージェント Swarm、`/undo`、あいまい検索モデルピッカー、Grok OAuth、`hermes proxy`、Kanban、`/goal`、Checkpoints v2、Curator、TUI、プラグイン、LightRAG、Telegram、MCP、セキュリティ、可観測性、リモートサンドボックス - **13 個のインストール可能 Skill**（`skills/`） — 監査、バックアップ、依存スキャン、コストレポート、Telegram トリアージ、PR レビュー、受信トレイ整理、Hermes 週報、スパムフィルタ、会議準備 など - **5 つのプロダクション設定テンプレ**（`templates/config/`） — minimum / telegram-bot / production / cost-optimized / security-hardened - **インフラ一式**（`templates/compose/`, `templates/caddy/`, `templates/systemd/`, `scripts/`） — Langfuse セルフホスト、Caddy リバースプロキシ、systemd 強化、VPS ブートストラップ @@ -31,6 +31,8 @@ curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/m 3. コストを下げたい → [part20-observability.md](./part20-observability.md) の "Cost-routing playbook" 4. 本番運用したい → [docs/reference-architectures/](./docs/reference-architectures/) から近いものを選ぶ 5. 公開エンドポイント → [part19-security-playbook.md](./part19-security-playbook.md) を必ず読む +6. ターミナルではなく GUI が欲しい → [part24-desktop-app.md](./part24-desktop-app.md)（Hermes デスクトップアプリ） +7. 自分の GPU でローカル実行したい → [part25-nvidia-local.md](./part25-nvidia-local.md)（RTX / DGX Spark） ## ライセンス・貢献 diff --git a/README-zh.md b/README-zh.md index c364fdb..b634d56 100644 --- a/README-zh.md +++ b/README-zh.md @@ -2,7 +2,7 @@ > [English 完整版](./README.md) · 本页是入口摘要，章节正文仍为英文。 -实用指南 + 可安装制品（Skills、配置模板、基础设施脚本），针对 [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)（当前覆盖到 v0.14.0）。 +实用指南 + 可安装制品（Skills、配置模板、基础设施脚本），针对 [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)（当前覆盖到 v0.16.0 “Surface”，含原生桌面应用与 NVIDIA 本地硬件）。 ## 一键起步 @@ -15,7 +15,7 @@ curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/m ## 内容一览 -- **24 章正文**（README 内章节 + `part6` 到 `part23`） — v0.14 Foundation、Grok OAuth、`hermes proxy`、LINE/SimpleX、Kanban、`/goal`、Checkpoints v2、Curator、TUI、插件、LightRAG、Telegram、MCP、安全、可观测性、远程沙箱 +- **26 章正文**（README 内章节 + `part6` 到 `part25`） — v0.16 桌面应用、NVIDIA / DGX Spark 本地运行、v0.15 Velocity 多智能体 Swarm、`/undo`、模糊模型选择器、Grok OAuth、`hermes proxy`、Kanban、`/goal`、Checkpoints v2、Curator、TUI、插件、LightRAG、Telegram、MCP、安全、可观测性、远程沙箱 - **13 个可安装 Skill**（`skills/`） — 审计、备份、依赖扫描、成本报告、Telegram 分类、PR 审查、收件箱分类、Hermes 周报、垃圾过滤、会议准备 等 - **5 套生产配置模板**（`templates/config/`） — minimum / telegram-bot / production / cost-optimized / security-hardened - **基础设施**（`templates/compose/`, `templates/caddy/`, `templates/systemd/`, `scripts/`） — Langfuse 自托管、Caddy 反代、systemd 硬化、VPS 引导脚本 @@ -31,6 +31,8 @@ curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/m 3. 想省钱 → [part20-observability.md](./part20-observability.md) 的 "Cost-routing playbook" 4. 想上生产 → [docs/reference-architectures/](./docs/reference-architectures/) 选一个最接近的 5. 用户面公开部署 → [part19-security-playbook.md](./part19-security-playbook.md) 必看 +6. 想要图形界面而非终端 → [part24-desktop-app.md](./part24-desktop-app.md)（Hermes 桌面应用） +7. 想用自己的 GPU 本地运行 → [part25-nvidia-local.md](./part25-nvidia-local.md)（RTX / DGX Spark） ## 许可与贡献 diff --git a/README.md b/README.md index 55fd62f..2421d45 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,50 @@ # Hermes Optimization Guide +

+ Hermes Optimization Guide — the practical playbook for the Nous Research Hermes Agent across CLI, TUI, web, and the new native desktop app +

+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) -[![Hermes](https://img.shields.io/badge/Hermes-v0.14.0%20%282026.5.16%29-9146FF)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.16) -[![Last updated](https://img.shields.io/badge/Last%20updated-2026--05--25-brightgreen)](./CHANGELOG.md) -[![Parts](https://img.shields.io/badge/parts-24-blue)](#table-of-contents) +[![Hermes](https://img.shields.io/badge/Hermes-v0.16.0%20%282026.6.5%29-9146FF)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5) +[![Last updated](https://img.shields.io/badge/Last%20updated-2026--06--17-brightgreen)](./CHANGELOG.md) +[![Parts](https://img.shields.io/badge/parts-26-blue)](#table-of-contents) [![Skills](https://img.shields.io/badge/installable%20skills-13-blue)](./skills/) [![Configs](https://img.shields.io/badge/config%20templates-5-blue)](./templates/config/) [![CI](https://github.com/OnlyTerp/hermes-optimization-guide/actions/workflows/ci.yml/badge.svg)](./.github/workflows/ci.yml) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) -> **Current through Hermes Agent v0.14.0 (v2026.5.16)** · **24 parts, 13 installable guide skills, 5 opinionated configs, 4 reference architectures, one-command VPS bootstrap** · Updated for the Foundation release: PyPI installs, Grok OAuth + 1M context, `hermes proxy`, `x_search`, Teams end-to-end, LINE/SimpleX, `/handoff`, faster browser/CDP paths, native Windows beta, durable Kanban, `/goal`, Checkpoints v2, no-agent cron, Curator, plugins, and current May 2026 model routing +> **Current through Hermes Agent v0.16.0 (v2026.6.5) — "The Surface Release"** · **26 parts, 13 installable guide skills, 5 opinionated configs, 4 reference architectures, one-command VPS bootstrap** · Now covering the **native Hermes Desktop app** (macOS/Windows/Linux), the **NVIDIA RTX / DGX Spark** local-hardware story + OpenShell, multi-agent **swarms** (`hermes kanban swarm`), the browser **admin panel**, `/undo`, the fuzzy model picker, Quick Setup via Nous Portal, and a leaner default skill set. **Bring any model** — this guide is about the *harness*, not the weights. > > Other languages: [中文](./README-zh.md) · [日本語](./README-ja.md) ### The End-to-End Hermes Guide — docs + runnable artifacts -Every part you need to go from fresh install to a production Hermes deployment that talks on 22+ built-in/plugin platforms, orchestrates Claude Code / Codex / Gemini CLI through durable Kanban lanes, plugs into any MCP server, traces every call in Langfuse, curates its own skills, and runs heavy work on disposable Modal/Daytona/Vercel sandboxes — without burning $100/day on frontier tokens. +Every part you need to go from fresh install to a production Hermes deployment — driven from the **native desktop app**, the CLI/TUI, a browser admin panel, or 22+ chat platforms. Orchestrate Claude Code / Codex / Gemini CLI through durable Kanban lanes and **multi-agent swarms**, plug into any MCP server, trace every call in Langfuse, let it curate its own skills, push heavy work onto disposable Modal/Daytona/Vercel sandboxes — or run the whole thing **locally on your own GPU / NVIDIA DGX Spark**. It's all **model-agnostic**: bring whatever weights you want, the guide is about the *harness*. Unlike most guides, the prescriptions come with **working files**: [`skills/`](./skills) you can `ln -s` into `~/.hermes/skills/`, [`templates/config/`](./templates/config) you `cp` to `~/.hermes/config.yaml`, [`scripts/vps-bootstrap.sh`](./scripts/vps-bootstrap.sh) that takes a fresh VPS to production in one command. -*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **May 25, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) +*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **June 17, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) --- -## Install Everything (one command) +## Install + +Pick the surface that fits you — they all drive the **same** agent, config, keys, sessions, and skills. + +**Easiest — the desktop app.** Grab the [Hermes Desktop](https://hermes-agent.nousresearch.com/docs/user-guide/desktop) installer for macOS/Windows/Linux (or run `hermes desktop` if you already have the CLI). First launch offers **Quick Setup via Nous Portal** — sign in, pick a model, start chatting. Full tour: **[Part 24: Hermes Desktop App](./part24-desktop-app.md)**. + +**Terminal — one line.** macOS / Linux: + +```bash +curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash +``` + +Windows (native, PowerShell): + +```powershell +iex (irm https://hermes-agent.nousresearch.com/install.ps1) +``` -On a fresh Debian 12 / Ubuntu 24.04 box (Hetzner CX22 works great for ~$5/mo): +**Server — one command to production.** On a fresh Debian 12 / Ubuntu 24.04 box (Hetzner CX22 works great for ~$5/mo): ```bash curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/main/scripts/vps-bootstrap.sh | sudo bash @@ -48,6 +68,7 @@ Prefer a 5-minute local-only setup? → **[docs/quickstart.md](./docs/quickstart | [`templates/cron/`](./templates/cron) | Recommended production cron schedule. | | [`scripts/vps-bootstrap.sh`](./scripts/vps-bootstrap.sh) | One-command fresh VPS → production Hermes. | | [`diagrams/`](./diagrams) | 6 Mermaid diagrams (architecture, MCP flow, delegation, sandbox sync, observability, security layers). | +| [`assets/`](./assets) | Banner graphics used across the guide. | | [`benchmarks/`](./benchmarks) | Reproducible cost + latency table across 12 models × 5 tasks. | | [`docs/wizard/`](./docs/wizard) | **Interactive config wizard** — 8 questions → ready-to-drop `config.yaml`. Runs in your browser. | | [`docs/reference-architectures/`](./docs/reference-architectures) | **4 blueprints** — Homelab, Solo Dev, Small Agency, Road Warrior. Full parts list + cost + install. | @@ -55,7 +76,7 @@ Prefer a 5-minute local-only setup? → **[docs/quickstart.md](./docs/quickstart | [`docs/quickstart.md`](./docs/quickstart.md) | 5-minute zero-to-Telegram-bot. | | [`ECOSYSTEM.md`](./ECOSYSTEM.md) | Curated directory of MCP servers, coding agents, dashboard plugins. | | [`ROADMAP.md`](./ROADMAP.md) · [`CHANGELOG.md`](./CHANGELOG.md) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) | The usual suspects. | -| README + `part1-*.md` … `part23-*.md` | The 24-part guide itself. | +| README + `part1-*.md` … `part25-*.md` | The 26-part guide itself (now incl. Desktop App + NVIDIA / local hardware). | --- @@ -63,13 +84,20 @@ Prefer a 5-minute local-only setup? → **[docs/quickstart.md](./docs/quickstart ```mermaid flowchart LR - Inputs[22+ platforms
Telegram · Discord · Slack
Google Chat · LINE · SimpleX
Teams · QQBot · Yuanbao
iMessage · WeChat · Email
SMS · Webhooks · Cron · Voice · CLI] --> Gateway + subgraph Surfaces[Surfaces — one agent, many front ends] + direction TB + Desktop[Desktop app
macOS · Windows · Linux] + Term[CLI · TUI] + Web[Web admin panel] + Chat[22+ chat platforms
Telegram · Discord · Slack
Teams · LINE · WeChat · …] + end + Surfaces --> Gateway Gateway --> Router[Model Router
cost + context + capability] - Router --> Providers[Anthropic · OpenAI
Google · Cerebras · Moonshot
z.ai · xAI · Local] + Router --> Providers[Any provider / model
Cloud APIs · OpenAI-compatible
Local: llama.cpp · LM Studio · Ollama
NVIDIA RTX · DGX Spark] Gateway --> Approval[Approval Layer
denylist · allowlist · quarantine] - Approval --> Tools[Tools
Native · Tool Gateway
MCP · Subagents · Coding Agents] + Approval --> Tools[Tools
Native · Tool Gateway · MCP
Subagents · Coding Agents · Swarms] Tools --> Memory[Memory
Vector · LightRAG · mem0] - Tools --> Logs[(Audit log
+ Langfuse/Helicone traces)] + Tools --> Logs[(Audit log
+ Langfuse / Helicone traces)] ``` Full set of diagrams: [`diagrams/architecture.md`](./diagrams/architecture.md). @@ -78,10 +106,10 @@ Full set of diagrams: [`diagrams/architecture.md`](./diagrams/architecture.md). ## Pick Your Path -This guide grew to 24 parts because *Hermes grew*. Six sections (Parts 1–5 plus SOUL.md) live in this README; Parts 6–23 live as separate files. You don't have to read them all — pick the shortest path to what you need: +This guide grew to 26 parts because *Hermes grew*. Six sections (Parts 1–5 plus SOUL.md) live in this README; Parts 6–25 live as separate files. You don't have to read them all — pick the shortest path to what you need: ### 🎯 "I just want it working in 10 minutes" -[Part 1: Setup](#part-1-setup-stop-fumbling-with-installation) → [Part 12: Web Dashboard](./part12-web-dashboard.md) → done. Use the dashboard to point-and-click the rest. +Skip the terminal: install the [desktop app](./part24-desktop-app.md) and let first-run **Quick Setup via Nous Portal** pick a model for you. Prefer the CLI? [Part 1: Setup](#part-1-setup-stop-fumbling-with-installation) → [Part 12: Web Dashboard](./part12-web-dashboard.md) and point-and-click the rest. ### 📱 "I want a Telegram bot that's actually useful" [Part 1](#part-1-setup-stop-fumbling-with-installation) → [Part 4: Telegram](./part4-telegram-setup.md) → [Part 5: On-the-fly Skills](./part5-creating-skills.md) → [Part 7: Memory](./part7-memory-system.md). @@ -101,58 +129,49 @@ This guide grew to 24 parts because *Hermes grew*. Six sections (Parts 1–5 plu ### 🛡️ "I'm worried about prompt injection (you should be)" [Part 19: Security Playbook](./part19-security-playbook.md) — read this first if your agent reads any untrusted input (email, webhooks, Discord, public Telegram groups). ---- +### 🖥️ "Just give me an app, not a terminal" +[Part 24: Hermes Desktop App](./part24-desktop-app.md) — download, Quick Setup, and drive everything from a real GUI: streaming chat, a Cmd+K command palette, drag-and-drop files, a model picker, and an optional connection to a remote Hermes box. -## What's New (May 2026) +### 🔒 "Run it all locally on my own GPU" +[Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md) — RTX / DGX Spark, OpenShell isolation, and a model-agnostic local stack (llama.cpp / LM Studio / Ollama) so your data never leaves the machine. -Hermes moved again after the Tenacity refresh. The current stable target is **[v0.14.0 — 2026.5.16 — "The Foundation Release"](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.16)**. This update folds the landed install, proxy, platform, live-search, and performance features into the guide and removes v0.13-as-current framing. +--- -### v0.14.0 — "Foundation" +## What's New (June 2026) -- **PyPI + lighter installs** — `pip install hermes-agent` now works, heavy extras lazy-install on first use, `[all]` is debloated, and launch is roughly 19 seconds faster. See [Part 1](#part-1-setup-stop-fumbling-with-installation). -- **Grok/SuperGrok OAuth + 1M context** — Grok 4.3 is now a native OAuth-backed provider with live X search, Custom Voices, and million-token research lanes. See [Part 9](./part9-custom-models.md). -- **`hermes proxy`** — one OpenAI-compatible localhost endpoint for OAuth-backed Claude Pro, ChatGPT Pro, and SuperGrok so Codex, Aider, Cline, Continue, and scripts can reuse subscriptions. See [Part 13](./part13-tool-gateway.md#openai-compatible-local-proxy). -- **`x_search`** — first-class X/Twitter search with OAuth or API-key auth for live threads and post lookup. See [Part 13](./part13-tool-gateway.md#x_search-first-class-x-search). -- **Teams end-to-end + LINE + SimpleX Chat** — Microsoft Graph auth/listener/runtime/delivery is wired through, and the gateway reaches 22 messaging platforms. See [Part 15](./part15-new-platforms.md). -- **Live `/handoff`** — transfer an active session to another model/profile/persona without losing messages or tool context. See [Part 23](./part23-tenacity-stack.md#8-upgrade-checklist-from-v013-to-v014). -- **Performance wave** — persistent CDP makes browser-console work dramatically faster; `computer_use` gains a provider-agnostic CUA backend; Claude prompt prefixes cache for 1 hour across sessions. See [Part 20](./part20-observability.md). -- **Editor + OS reach** — Zed ACP Registry integration via `uvx`, clickable terminal URLs, and native Windows beta widen how Hermes is driven. See [Part 18](./part18-coding-agents.md#agent-tooling-updates-may-25-2026). +Two big releases landed since the Foundation refresh — **v0.15.0 "Velocity"** and **[v0.16.0 "The Surface Release"](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5)** — plus a deepening **NVIDIA** partnership. The headline themes: a native **desktop app**, run-it-**local** on NVIDIA hardware, multi-agent **swarms**, a browser **admin panel**, and a deliberately **leaner** default skill set. None of it is model-specific — bring whatever weights you want. -### v0.13.0 — "Tenacity" +### v0.16.0 — "Surface" (latest) -- **Durable multi-agent Kanban** — boards, heartbeats, reclaim, retry budgets, zombie detection, and human unblock/review flow make long work auditable instead of fragile. See [Part 23](./part23-tenacity-stack.md#1-treat-kanban-as-the-durable-execution-layer). -- **`/goal` persistent objectives** — keep a session locked on an observable target until done, paused, cleared, or out of budget. See [Part 23](./part23-tenacity-stack.md#3-use-goal-for-do-not-stop-until-it-is-done). -- **Checkpoints v2 + no-agent cron** — real pruning, gateway auto-resume, script-only watchdogs, and provider/platform plugin surfaces. See [Part 23](./part23-tenacity-stack.md). +- **Hermes Desktop** — a native macOS/Windows/Linux app: streaming chat with live tool activity, a session list with archive/search, drag-and-drop files, clipboard image paste, a **Cmd+K command palette**, a model picker in the composer, a per-session **YOLO toggle**, and in-app self-update. It's "another surface over one agent, not a fork." See [Part 24](./part24-desktop-app.md). +- **Remote backend** — desktop and clients can connect to a remote Hermes gateway over a secure WebSocket (OAuth or username/password), with per-profile hosts, concurrent multi-profile sessions, and cross-profile `@session` links. Thin GUI local, heavy agent remote. See [Part 24](./part24-desktop-app.md#7-connect-to-a-remote-hermes). +- **Browser admin panel** — the web dashboard grew into a full admin panel: a Channels page that sets up every messaging platform from the browser, MCP catalog enable/disable, credentials, webhooks, memory config, and a System page with **check-before-update** and one-click **Debug Share**. See [Part 12](./part12-web-dashboard.md). +- **Quick Setup via Nous Portal** — `hermes portal` opens a guided first-run that signs you in and picks a model; Quick Setup vs Full Setup paths on first launch. See [Part 1](#part-1-setup-stop-fumbling-with-installation). +- **`/undo [N]`** — take back the last N turns and prefill your last message to edit and resend, with CLI / TUI / messaging parity. See [Part 22](./part22-latest-power-moves.md). +- **Fuzzy model picker + default interface choice** — type-to-filter model search across desktop/web/TUI/CLI, grouped multi-endpoint providers, an hourly-refreshed catalog, and a `cli`-or-`tui` default for `hermes chat` (with a `--cli` per-invocation override). See [Part 22](./part22-latest-power-moves.md). +- **Leaner default skills** — rarely-used bundled skills moved to optional, a new `environments:` relevance gate, and the Curator can now prune built-in skills. See [Part 22](./part22-latest-power-moves.md). +- **NVIDIA Skills Hub tap** — a built-in trusted Skills source alongside OpenAI/Anthropic/HuggingFace (CUDA-X, AIQ, cuOpt), part of the broader NVIDIA local-hardware story. See [Part 25](./part25-nvidia-local.md). +- **Security** — CVE-2026-48710 Starlette pin, SSRF off-loop hardening, and subprocess credential stripping. See [Part 19](./part19-security-playbook.md). -### v0.12.0 — "Curator" +### v0.15.0 — "Velocity" -- **Autonomous Curator** — `hermes curator` grades, consolidates, pins, archives, and restores agent-created skills on a default 7-day cadence. See [Part 22](./part22-latest-power-moves.md#1-turn-on-curator-before-your-skill-library-becomes-noise). -- **Self-improvement loop upgraded** — the review fork is rubric-based, active-skill-biased, restricted to memory + skills tools, and correctly inherits the parent provider/model/credentials. See [Part 5](./part5-creating-skills.md#curator-v012-keep-the-skill-library-from-rotting). -- **Provider expansion** — LM Studio became a first-class provider; GMI Cloud, Azure AI Foundry, MiniMax OAuth, Tencent TokenHub, AWS Bedrock, NVIDIA NIM, Vercel AI Gateway, Step Plan, Gemini OAuth, and Codex OAuth are now part of the realistic routing menu. See [Part 9](./part9-custom-models.md). -- **Plugin-first gateway** — gateway platforms can ship as plugins; Microsoft Teams is the first plugin-shipped platform, and Tencent Yuanbao is the 18th native platform. See [Part 15](./part15-new-platforms.md#2026-update-teams-line-simplex-google-chat-qqbot-and-yuanbao). -- **Bundled plugins worth enabling** — Spotify tools, Google Meet transcription/duplex audio, Langfuse observability, achievements, extra image providers, and dashboard skins. See [Part 22](./part22-latest-power-moves.md#4-use-plugins-for-integrations-not-one-off-scripts). -- **Dashboard caught up** — Models tab, auxiliary-model configuration, dashboard Chat backed by the real `hermes --tui`, plugin slots, themes, update/restart controls, and better session analytics. See [Part 12](./part12-web-dashboard.md). -- **TUI is now the primary interface** — `hermes --tui` adds sticky composer, slash autocomplete, live tool cards, `/steer`, `/queue`, `/background`, `/busy`, `/indicator`, voice parity, LaTeX, and better resume/delete flows. See [Part 22](./part22-latest-power-moves.md#2-use-the-tui-as-your-daily-driver). -- **Remote model catalog** — OpenRouter and Nous Portal picker lists update from a hosted manifest, so users see new models without waiting for a Hermes release. See [Part 9](./part9-custom-models.md#remote-model-catalog-stop-hardcoding-this-weeks-winner). -- **Cron got serious** — per-job `workdir`, per-job toolsets, `context_from` chaining, and zero-LLM direct webhook delivery make scheduled automations cheaper and more predictable. -- **Tool/runtime hardening** — hardline command blocklists, Docker host-user bind mounts, Vercel Sandbox backend, SSH permission fixes, local Chromium for localhost/LAN browser tasks, and richer approval hooks. +- **Multi-agent swarms** — `hermes kanban swarm` turns the durable Kanban into a platform: a root planner, parallel workers, a gated verifier and synthesizer, a shared blackboard, per-task model overrides, and a worktree per task. See [Part 23](./part23-tenacity-stack.md). +- **Huge perf wave** — `run_agent.py` was split into focused `agent/*` modules (−76% lines), cold start dropped sharply (`hermes --version` −63%), per-turn function calls fell ~47%, and `session_search` got **~4,500× faster — and free**. See [Part 20](./part20-observability.md). +- **Brainworm / promptware defense** — a defense layer against instructions smuggled through tool output and untrusted content. See [Part 19](./part19-security-playbook.md). +- **More surfaces & integrations** — Bitwarden Secrets Manager bootstrap, skill bundles (one slash command loads a whole workflow), an Ink TUI multi-session orchestrator, Krea 2 image generation, an interactive Nous-approved MCP catalog picker, ntfy as the 23rd messaging platform, and a deep xAI round (Web Search plugin, `hermes migrate xai`). See [Part 15](./part15-new-platforms.md) and [Part 17](./part17-mcp-servers.md). -### v0.11.0 — "Interface" +### NVIDIA partnership — run it local -- **Ink TUI rewrite** — `hermes --tui` is a React/Ink interface over a Python JSON-RPC backend with streaming, status bars, pickers, and subagent observability. -- **Transport layer rewrite** — Anthropic, Chat Completions, OpenAI Responses, and Bedrock transports are separate, making native providers more reliable than generic OpenAI-compatible shims. -- **AWS Bedrock native provider** — IAM credentials, Converse API, cross-region inference profiles, and Bedrock Guardrails. See [Part 9](./part9-custom-models.md#aws-bedrock-and-azure-ai-foundry-enterprise-routing-without-proxy-glue). -- **Auxiliary model UI** — choose separate models for compression, vision, session search, title generation, and curator instead of silently burning your main model on side tasks. -- **Smarter delegation** — orchestrator-role subagents, configurable spawn depth, and file coordination between sibling workers reduce multi-agent clobbering. See [Part 18](./part18-coding-agents.md). -- **Plugin and hook surface expanded** — plugins can register slash commands, dispatch tools, block tool execution, rewrite tool results, transform terminal output, add image backends, and add dashboard tabs. -- **Webhook direct delivery** — push alerts to a platform chat without waking the LLM, ideal for uptime checks and event streams. +Hermes is now optimized for always-on **local** use on **NVIDIA RTX PCs, RTX PRO workstations, and DGX Spark** (128GB unified memory, ~1 petaflop of AI performance, runs 120B-class MoE models all day). Tensor Cores accelerate inference, there's a dedicated **DGX Spark playbook**, and **OpenShell** adds kernel-level isolation between the agent and your OS. It stays model-agnostic — bring any weights. See [Part 25](./part25-nvidia-local.md). -### Still important from v0.9/v0.10 +### Earlier milestones (still relevant) -- **Local web dashboard** (`hermes dashboard`) — config, API keys, sessions, logs, analytics, cron, skills, models, plugins, and optional browser Chat. See [Part 12](./part12-web-dashboard.md). -- **Tool Gateway + local proxy** — Nous Portal subscribers can route web/image/TTS/browser calls through one subscription, and v0.14 `hermes proxy` exposes OAuth-backed Claude/OpenAI/xAI through a loopback OpenAI-compatible endpoint. See [Part 13](./part13-tool-gateway.md). -- **Fast Mode** (`/fast`) and **guided compression** (`/compress `) still matter, but they are no longer the whole story; pair them with auxiliary model routing and `/steer`. See [Part 14](./part14-fast-mode-watchers.md). -- **MCP + coding-agent delegation + remote sandboxes** remain the high-leverage developer stack. See [Part 17](./part17-mcp-servers.md), [Part 18](./part18-coding-agents.md), and [Part 21](./part21-remote-sandboxes.md). +- **v0.14 "Foundation"** — PyPI installs + lighter launch, Grok OAuth + 1M context, `hermes proxy` (OpenAI-compatible localhost), `x_search`, Teams/LINE/SimpleX, live `/handoff`, and the first native Windows support. See [Part 23](./part23-tenacity-stack.md) and [Part 13](./part13-tool-gateway.md). +- **v0.13 "Tenacity"** — durable multi-agent Kanban, `/goal` persistent objectives, Checkpoints v2, and no-agent cron. See [Part 23](./part23-tenacity-stack.md). +- **v0.12 "Curator"** — the autonomous Curator (`hermes curator`), a rubric-based self-improvement loop, a much wider provider menu, and a plugin-first gateway. See [Part 22](./part22-latest-power-moves.md) and [Part 9](./part9-custom-models.md). +- **v0.11 "Interface"** — the Ink TUI rewrite, a per-transport provider layer, native AWS Bedrock, and auxiliary-model routing for side tasks. See [Part 22](./part22-latest-power-moves.md). + +**Fundamentals that haven't changed:** the local web dashboard (`hermes dashboard`), the Tool Gateway + `hermes proxy`, Fast Mode (`/fast`) and guided compression (`/compress `), and the MCP + coding-agent + remote-sandbox developer stack. See [Part 12](./part12-web-dashboard.md), [Part 13](./part13-tool-gateway.md), [Part 14](./part14-fast-mode-watchers.md), [Part 17](./part17-mcp-servers.md), [Part 18](./part18-coding-agents.md), and [Part 21](./part21-remote-sandboxes.md). --- @@ -181,7 +200,9 @@ Hermes moved again after the Tenacity refresh. The current stable target is **[v 21. [Observability & Cost Control](./part20-observability.md) — Langfuse plugin, Helicone, OpenTelemetry → Phoenix, prompt-prefix caching, CDP spans, auxiliary routing, evals 22. [Remote Sandboxes & Bulk File Sync](./part21-remote-sandboxes.md) — SSH, Modal, Daytona, Vercel Sandbox, Fly Machines, E2B. Diff-based sync-back on teardown 23. [Latest Power Moves](./part22-latest-power-moves.md) — Curator, TUI habits, context-file hygiene, plugins, dashboard Chat, cron chaining, and the 2026 upgrade checklist -24. [Foundation + Tenacity Stack](./part23-tenacity-stack.md) — PyPI/lazy deps, `hermes proxy`, `/handoff`, durable Kanban, `/goal`, Checkpoints v2, no-agent cron, worker lanes, and v0.14 upgrade checklist +24. [Foundation + Tenacity Stack](./part23-tenacity-stack.md) — PyPI/lazy deps, `hermes proxy`, `/handoff`, durable Kanban, `/goal`, Checkpoints v2, no-agent cron, worker lanes, multi-agent swarms, and the upgrade checklist +25. [Hermes Desktop App](./part24-desktop-app.md) — Native macOS/Windows/Linux GUI, Quick Setup, Cmd+K palette, drag-and-drop, model picker, remote gateway, multi-profile, voice, self-update +26. [NVIDIA & Local Hardware](./part25-nvidia-local.md) — Run Hermes on your own GPU: RTX / DGX Spark, OpenShell isolation, NemoClaw, and a model-agnostic local stack --- @@ -243,20 +264,23 @@ LLM Provider (Claude, GPT, local models) ## Quick Start ```bash -# 1. Install Hermes (Linux/macOS/WSL2/Android) -curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +# 1. Install Hermes (Linux/macOS/WSL2/Android) — or grab the desktop app +curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -# 2. Configure providers and tools +# 2. Configure providers and tools (or `hermes portal` for guided Quick Setup) hermes setup -# 3a. Start chatting in the terminal +# 3a. Start chatting in the terminal (CLI or TUI) hermes -# 3b. Or launch the new browser dashboard (v0.9+) +# 3b. Or open the browser dashboard / admin panel hermes dashboard + +# 3c. Or launch the native desktop app +hermes desktop ``` -The dashboard is the fastest way to configure everything without touching YAML. See [Part 12](./part12-web-dashboard.md) for the full tour. +The dashboard — and the new desktop app — are the fastest way to configure everything without touching YAML. See [Part 12](./part12-web-dashboard.md) and [Part 24](./part24-desktop-app.md) for the full tours. For the full walkthrough including optimization, read each part in order. @@ -266,27 +290,27 @@ For the full walkthrough including optimization, read each part in order. ## The Install -One command. That's it. v0.14 also ships on PyPI, so use the installer for the full local stack or `pip install hermes-agent` for the leanest CLI path. +One command. That's it. Hermes also ships on PyPI, so use the installer for the full local stack or `pip install hermes-agent` for the leanest CLI path. Prefer a GUI? Install the [desktop app](./part24-desktop-app.md) instead — same agent, same config, same keys. ### Linux / macOS / WSL2 ```bash -curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -# Lean v0.14+ path when you already manage Python yourself: +# Lean path when you already manage Python yourself: pip install hermes-agent ``` > **Security tip:** Piping scripts directly from the internet to bash executes them sight-unseen. If you prefer to inspect first: > ```bash -> curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh +> curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh > less install.sh # Review the script > bash install.sh > ``` -> **Windows users:** Native Windows is in beta in v0.14. For the most reliable path, use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install); if you test native Windows, keep a backup and expect PTY/dashboard edge cases. +> **Windows users:** Hermes now has a native Windows installer — in PowerShell run `iex (irm https://hermes-agent.nousresearch.com/install.ps1)`. [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) is still a great option if you prefer a Linux environment, and the [desktop app](./part24-desktop-app.md) installs like any other Windows program. -> **Android users (new in v0.9):** the same installer detects Termux and installs the tested `[termux]` extra bundle automatically — CLI, cron, PTY/background terminal, Telegram gateway, MCP, Honcho, ACP. See [Part 15 — Android / Termux](./part15-new-platforms.md#android--termux-running-hermes-on-your-phone). +> **Android users:** the same installer detects Termux and installs the tested `[termux]` extra bundle automatically — CLI, cron, PTY/background terminal, Telegram gateway, MCP, Honcho, ACP. See [Part 15 — Android / Termux](./part15-new-platforms.md#android--termux-running-hermes-on-your-phone). ### What the Installer Does @@ -316,48 +340,20 @@ hermes # Start chatting! The setup wizard (`hermes setup`) walks you through: -### 1. Choose Your LLM Provider +### 1. Choose Your Model (bring any) ```bash hermes model ``` -Supported providers and recommended models: - -| Provider | Top Models | Best For | Env Variable | -|----------|-----------|----------|-------------| -| **Nous Portal** | Hermes 5, Hermes 4 405B | Built-in [Tool Gateway](./part13-tool-gateway.md) — web search/image/TTS/browser with no extra keys | Auth via `hermes model` | -| **Anthropic** | Sonnet 5, Opus 4.7, Sonnet 4.6 | Best coding reliability, long unattended PR work, `/fast` priority tier | `ANTHROPIC_API_KEY` | -| **OpenAI** | GPT-5.5, GPT-5 Codex, o-series | Strong tool use, sandboxed coding loops, deep reasoning, `/fast` priority tier | `OPENAI_API_KEY` | -| **Xiaomi MiMo** | MiMo V2 Pro *(native adapter)* | Fast, cheap, native reasoning modes, great for orchestration | `XIAOMI_API_KEY` | -| **xAI** | Grok 4.3, Grok Mini *(native adapter + SuperGrok OAuth)* | 1M context, native live-X search, Custom Voices | `XAI_API_KEY` or OAuth | -| **Kimi / Moonshot** | Kimi K2.6, Kimi 2.5 | Big context, excellent $/pass for code and extraction | `MOONSHOT_API_KEY` | -| **z.ai / GLM** | GLM-5, GLM-5 Air | Strong open-weight tool use, great for translation + cheap reasoning | `ZAI_API_KEY` | -| **Google** | Gemini 3.1 Pro/Flash | Massive context, multimodal/video, cheap; OAuth supported via `hermes model` | `GEMINI_API_KEY` or OAuth | -| **MiniMax** | M2.7+ | Good balance of speed, TTS, and quality | `MINIMAX_API_KEY` | -| **Cerebras** | Llama 4 Scout, Qwen 3 32B | Blazing fast inference (2000+ tok/s), cheap | `CEREBRAS_API_KEY` | -| **Groq** | Llama 4, Qwen 3 | Very fast inference, limited context | `GROQ_API_KEY` | -| **Arcee** | AFM-4.5, Caller | Function-calling specialists, cheap | `ARCEE_API_KEY` | -| **Hugging Face** | Any TGI/TEI endpoint | Self-hosted and Inference Endpoints | `HF_TOKEN` | -| **OpenRouter** | All of the above + 200 more | Access every model from one key, auto-fallback | `OPENROUTER_API_KEY` | -| **Ollama** (local) | DeepSeek V4-Pro/Flash, Qwen3-Coder-Next, Qwen3.6, Gemma 4, Nemotron | Free/private local inference — great for embeddings, drafts, and offline work | None needed | - -### Local Models (Ollama) - -Run models on your own hardware for free. Recommended local models: - -| Model | Size | Best For | Min VRAM | -|-------|------|----------|----------| -| Qwen3-Coder-Next | 30B+ | Best local coding lane | 24GB | -| DeepSeek V4-Flash | MoE | Cheap local/open inference if you can host it | 24GB+ | -| Qwen3.6-27B | 27B | Single-GPU reasoning/coding balance | 16GB | -| Gemma 4 | 27B | Fast general assistant, long context | 16GB | -| Nemotron 30B | 30B | Fine-tunable, good general purpose | 16GB | -| nomic-embed-text | 274M | Free embeddings for memory search | 2GB | +**Hermes is model-agnostic — the harness is the point, not the weights.** Open the picker and fuzzy-search across every provider Hermes knows about; the catalog refreshes hourly, so new models show up without waiting for a release. You don't need to memorize this week's leaderboard — pick what's good *right now*: -> **Recommendation:** Use a cloud frontier model (Anthropic/OpenAI/Gemini) as your primary and a local Ollama or LM Studio model for embeddings, fallback, and simple tasks. Best of both worlds. +- **Cloud APIs** — Anthropic, OpenAI, Google, xAI / Grok (OAuth), Moonshot / Kimi, z.ai / GLM, MiniMax, Cerebras, Groq, and more. Set the matching `*_API_KEY` (or sign in by OAuth where supported) and you're done. +- **One key for everything** — point Hermes at **OpenRouter** (`OPENROUTER_API_KEY`) to reach hundreds of models with automatic fallback. +- **Local / private** — run on your own hardware with **Ollama**, **LM Studio**, or **llama.cpp** (no key needed). Ideal for embeddings, drafts, offline work, and privacy. For the full local-hardware story — NVIDIA RTX / DGX Spark and OpenShell isolation — see **[Part 25](./part25-nvidia-local.md)**. +- **Nous Portal** — sign in once and get the built-in [Tool Gateway](./part13-tool-gateway.md) (web search / image / TTS / browser) with no extra keys. -You can configure **multiple providers** with automatic fallback. If one goes down, Hermes switches to the next. +Configure **multiple providers** with automatic fallback — if one goes down, Hermes switches to the next. A common, cheap setup: a frontier cloud model as your primary plus a small local model for embeddings and side tasks. Deep routing, aliases, and fallback chains live in **[Part 9: Custom Models](./part9-custom-models.md)**. ### 2. Set Your API Keys @@ -1805,8 +1801,10 @@ You've now got the full picture: - **[Part 3: LightRAG](#part-3-lightrag--graph-rag-that-actually-works)** — Graph-based knowledge - **[Part 4: Telegram](#part-4-telegram-setup-chat-from-anywhere)** — Mobile access - **[Part 5: On-the-Fly Skills](#part-5-on-the-fly-skills-let-hermes-build-its-own-playbook)** — Self-improving workflows -- **[Part 22: Latest Power Moves](./part22-latest-power-moves.md)** — Curator, TUI habits, plugins, and context hygiene -- **[Part 23: Tenacity Stack](./part23-tenacity-stack.md)** — Kanban, `/goal`, Checkpoints v2, no-agent cron, and the current upgrade checklist +- **[Part 22: Latest Power Moves](./part22-latest-power-moves.md)** — Curator, TUI habits, plugins, `/undo`, fuzzy model picker, and context hygiene +- **[Part 23: Tenacity Stack](./part23-tenacity-stack.md)** — Kanban, `/goal`, Checkpoints v2, multi-agent swarms, and the current upgrade checklist +- **[Part 24: Hermes Desktop App](./part24-desktop-app.md)** — The native GUI: Quick Setup, command palette, model picker, and remote backends +- **[Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md)** — Run it on your own GPU: RTX / DGX Spark, OpenShell, and a model-agnostic local stack Start with setup, add what you need, and let Hermes build the rest. diff --git a/ROADMAP.md b/ROADMAP.md index 8157a2b..798dfa9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -24,6 +24,7 @@ What's landing next. PRs welcome. ## Done (recent) +- ✅ 2026-06-17 — v0.16 "Surface" refresh: Part 24 Hermes Desktop App, Part 25 NVIDIA & local hardware (DGX Spark / OpenShell / NemoClaw), new banner graphics, `/undo` + default-interface + fuzzy-picker power moves, native Windows installer, `hermes portal` Quick Setup, and a trim of stale per-version model tables to a model-agnostic section - ✅ 2026-05-25 — v0.14 refresh: PyPI install, Grok OAuth, `hermes proxy`, `x_search`, Teams end-to-end, LINE/SimpleX, `/handoff`, Windows beta, and May 25 model SOTA - ✅ 2026-05-14 — v0.13 refresh: Kanban, `/goal`, Checkpoints v2, Google Chat, no-agent cron, provider plugins, and May 2026 model SOTA - ✅ 2026-04-30 — v0.11/v0.12 refresh: Curator, TUI, plugins, Bedrock/Azure/LM Studio, Teams/Yuanbao/QQBot, Vercel Sandbox, Part 22 diff --git a/assets/desktop-app.png b/assets/desktop-app.png new file mode 100644 index 0000000..19238af Binary files /dev/null and b/assets/desktop-app.png differ diff --git a/assets/hero-banner.png b/assets/hero-banner.png new file mode 100644 index 0000000..92ab0c1 Binary files /dev/null and b/assets/hero-banner.png differ diff --git a/assets/nvidia-local.png b/assets/nvidia-local.png new file mode 100644 index 0000000..612e28d Binary files /dev/null and b/assets/nvidia-local.png differ diff --git a/part1-setup.md b/part1-setup.md index 5c28a66..58a2a27 100644 --- a/part1-setup.md +++ b/part1-setup.md @@ -6,25 +6,37 @@ ## The Install -One command. That's it. v0.14 also ships on PyPI, so use the installer for the full local stack or `pip install hermes-agent` for the leanest CLI path. +One command. That's it. Hermes also ships on PyPI, so use the installer for the full local stack or `pip install hermes-agent` for the leanest CLI path. Prefer a GUI? Install the [desktop app](./part24-desktop-app.md) — same agent, same config, same keys. ### Linux / macOS / WSL2 ```bash -curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -# Lean v0.14+ path when you already manage Python yourself: +# Lean path when you already manage Python yourself: pip install hermes-agent ``` > **Security tip:** Piping scripts directly from the internet to bash executes them sight-unseen. If you prefer to inspect first: > ```bash -> curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o install.sh +> curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh > less install.sh # Review the script > bash install.sh > ``` -> **Windows users:** Native Windows is in beta in v0.14. Use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) for production/stable gateway work; try native Windows only after backing up config and expecting PTY/dashboard quirks. +### Windows (native) + +Hermes now has a first-class native Windows installer. In PowerShell: + +```powershell +iex (irm https://hermes-agent.nousresearch.com/install.ps1) +``` + +[WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) is still a solid choice if you prefer a Linux environment for gateway work. + +### Desktop app + +Want a GUI instead of a terminal? Install the [Hermes Desktop app](./part24-desktop-app.md) (macOS/Windows/Linux) — or add it to a CLI install with `--include-desktop`. It runs the same agent, config, and keys. Full tour in [Part 24](./part24-desktop-app.md). ### What the Installer Does @@ -54,25 +66,20 @@ hermes # Start chatting! The setup wizard (`hermes setup`) walks you through: -### 1. Choose Your LLM Provider +### 1. Choose Your Model (bring any) ```bash -hermes model +hermes model # fuzzy-search every provider Hermes knows about ``` -Supported providers: +**Hermes is model-agnostic** — the picker fuzzy-searches a catalog that refreshes hourly, so you're never stuck on last release's list. You don't have to commit to a single provider: -| Provider | Best For | Env Variable | -|----------|----------|-------------| -| Anthropic (Claude) | Highest quality, best at complex tasks | `ANTHROPIC_API_KEY` | -| OpenAI (GPT-5.5/Codex) | Strong tool use, sandboxed coding, deep reasoning | `OPENAI_API_KEY` | -| OpenRouter | Access 100+ models from one key | `OPENROUTER_API_KEY` | -| Cerebras | Fast inference, good for simple tasks | `CEREBRAS_API_KEY` | -| Groq | Very fast, limited context | `GROQ_API_KEY` | -| xAI (Grok / SuperGrok OAuth) | Live X search, Grok 4.3 1M context, Custom Voices | `XAI_API_KEY` or OAuth | -| Google (Gemini) | Huge context, cheap | `GEMINI_API_KEY` | +- **Cloud APIs** — Anthropic, OpenAI, Google, xAI / Grok (OAuth), Moonshot / Kimi, z.ai / GLM, MiniMax, Cerebras, Groq, and more. Set the matching `*_API_KEY` or sign in by OAuth. +- **One key for everything** — OpenRouter (`OPENROUTER_API_KEY`) reaches hundreds of models with automatic fallback. +- **Local / private** — Ollama, LM Studio, or llama.cpp with no key needed. See [Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md). +- **Nous Portal** — `hermes portal` runs a guided **Quick Setup** that signs you in and picks a model for you. -You can configure **multiple providers** with automatic fallback. If one goes down, Hermes switches to the next. +Configure **multiple providers** with automatic fallback — if one goes down, Hermes switches to the next. Routing, aliases, and fallback chains are covered in [Part 9](./part9-custom-models.md). ### 2. Set Your API Keys @@ -195,7 +202,7 @@ Expected output: Hermes responds with a greeting, confirming the model connectio hermes update ``` -This pulls the latest code, updates dependencies, migrates config, and restarts the gateway. Run it regularly — Hermes ships frequent improvements. +This pulls the latest code, updates dependencies, migrates config, and restarts the gateway. Run it regularly — Hermes ships frequent improvements. The web admin panel's **System page** adds a **check-before-update** step and a one-click **Debug Share** for support, and the [desktop app](./part24-desktop-app.md) checks in the background and updates in one click. --- @@ -205,3 +212,5 @@ This pulls the latest code, updates dependencies, migrates config, and restarts - **Want smarter memory?** → [Part 3: LightRAG Setup](./part3-lightrag-setup.md) - **Need mobile access?** → [Part 4: Telegram Setup](./part4-telegram-setup.md) - **Want the agent to self-improve?** → [Part 5: On-the-Fly Skills](./part5-creating-skills.md) +- **Prefer a GUI?** → [Part 24: Hermes Desktop App](./part24-desktop-app.md) +- **Run it on your own GPU?** → [Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md) diff --git a/part22-latest-power-moves.md b/part22-latest-power-moves.md index 5e8fc2a..68d1a40 100644 --- a/part22-latest-power-moves.md +++ b/part22-latest-power-moves.md @@ -1,6 +1,6 @@ # Part 22: Latest Power Moves — Curator, TUI, Plugins, Context Files -*If you already know Hermes but missed the v0.11/v0.12 wave, read this part first for Curator, TUI, plugins, and context hygiene. For the v0.13/v0.14 durability + foundation layer — Kanban, `/goal`, `/handoff`, Checkpoints v2, no-agent cron, PyPI installs, proxy, and new platforms — go next to [Part 23](./part23-tenacity-stack.md).* +*If you already know Hermes but missed the v0.11/v0.12 wave, read this part first for Curator, TUI, plugins, and context hygiene. For the v0.13/v0.14 durability + foundation layer — Kanban, `/goal`, `/handoff`, Checkpoints v2, no-agent cron, PyPI installs, proxy, and new platforms — go next to [Part 23](./part23-tenacity-stack.md). The newest everyday moves from v0.15 "Velocity" and v0.16 "Surface" — `/undo`, a default-interface choice, the fuzzy model picker, and leaner default skills — are in [section 8](#8-newer-power-moves-v015--v016). For the native GUI and the run-it-local story, see [Part 24](./part24-desktop-app.md) and [Part 25](./part25-nvidia-local.md).* --- @@ -165,6 +165,52 @@ Then: --- +## 8. Newer Power Moves (v0.15 → v0.16) + +The Velocity and Surface releases added a handful of small things you'll reach for daily: + +### `/undo [N]` — take back turns + +Made a mess, or sent the wrong prompt? `/undo` rewinds the last turn; `/undo N` rewinds the last `N`. It also **prefills your last message** so you can edit and resend instead of retyping. Works the same in the CLI, TUI, and messaging surfaces. + +```text +/undo # undo the last turn +/undo 3 # undo the last three turns +``` + +### Pick your default interface + +`hermes chat` can default to either the **CLI** or the **TUI** — set it once and override per-invocation with `--cli`: + +```bash +hermes config set interface tui # or: cli +hermes chat --cli # one-off override +``` + +The TUI also unified its model switcher under `/model` and added a Sessions overlay. + +### The fuzzy model picker is everywhere + +Desktop, web, TUI, and CLI all share the same **fuzzy model picker**. Multi-endpoint providers are grouped, and the catalog **refreshes hourly**, so new models appear without waiting for a Hermes release. Just type part of a name in `hermes model` and pick. + +### Leaner default skills + +v0.16 trimmed the built-in skill set so the agent isn't carrying dead weight. Several skills became **native plugins** or moved to **MCP** (for example, Spotify is now a native plugin; Linear is `hermes mcp install linear`), others moved to **optional**, and a new `environments:` relevance gate keeps irrelevant skills from loading. Curator can now prune **built-in** skills too, not just agent-created ones. + +If you relied on a skill that disappeared, check whether it's now a plugin (`hermes plugins list`) or an MCP server (`hermes mcp ...`) before recreating it. + +### Free, instant session search + +`session_search` is now ~4,500× faster and runs locally for free — searching your own history no longer burns tokens. Combine it with desktop's search-by-id (see [Part 24](./part24-desktop-app.md)) to jump back into past work fast. + +### Scale durable work into a swarm + +When one board outgrows a single worker, `hermes kanban swarm` turns Kanban into a multi-agent platform (root, parallel workers, gated verifier/synthesizer, shared blackboard, per-task model overrides). Full details in [Part 23](./part23-tenacity-stack.md). + +> **Security note:** v0.15 added **Brainworm/promptware defenses** against malicious instructions hidden in tool output. Keep them on, and read [Part 19](./part19-security-playbook.md) before wiring up untrusted inputs. + +--- + ## What to Ignore Some old advice is no longer worth optimizing around: diff --git a/part24-desktop-app.md b/part24-desktop-app.md new file mode 100644 index 0000000..a49ce46 --- /dev/null +++ b/part24-desktop-app.md @@ -0,0 +1,153 @@ +# Part 24: Hermes Desktop App — A Real GUI Over the Same Agent + +

+ Hermes Desktop — the native macOS, Windows, and Linux app for the Hermes Agent +

+ +*The v0.16.0 "Surface Release" shipped **Hermes Desktop**: a native macOS/Windows/Linux app that runs the exact same agent as the CLI, TUI, and gateway. Same config, same keys, same sessions, same skills, same memory — it's "another surface over one agent, not a fork." If you've avoided Hermes because you didn't want to live in a terminal, this is your on-ramp.* + +--- + +## 1. Install and Launch + +If Hermes is already installed, the app is one command away: + +```bash +hermes desktop +``` + +The first run downloads or builds the desktop bundle (e.g. `Hermes.app` on macOS) and launches it. To build the desktop app as part of a fresh install, pass the installer flag: + +```bash +# macOS / Linux +curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --include-desktop +``` + +On **Windows**, the native installer ships a signed bootstrap that can include the desktop app: + +```powershell +iex (irm https://hermes-agent.nousresearch.com/install.ps1) +``` + +Once installed it behaves like any other desktop program — pin it to your dock/taskbar and launch it without the terminal. + +> **Same brain, new face.** The desktop app talks to the same agent core as everything else. A session you start in the app shows up in `hermes sessions`, and a skill the agent wrote from Telegram is available in the app. Nothing is siloed. + +--- + +## 2. The Chat Surface + +The main window is a streaming chat with **live tool activity** — you watch tool calls run inline instead of staring at a spinner. Highlights: + +- **Shared history across surfaces** — desktop, CLI, TUI, and messaging all read/write the same sessions. +- **Drag-and-drop files** — drop a file onto the composer to attach it. +- **Clipboard image paste** — paste a screenshot straight in. +- **Right-hand preview rail** — rendered output (files, images, results) opens beside the chat instead of scrolling away. +- **Composer history and queue editing** — press up/down in the composer to recall previous messages and edit a queued message before it sends. + +--- + +## 3. Command Palette and Keyboard + +- **Command palette:** `Cmd+K` (macOS) / `Ctrl+K` (Windows/Linux) opens a fuzzy command palette for nearly everything — switch sessions, change model, open settings, run commands. +- **Rebindable shortcuts:** remap keys to taste. +- **Custom zoom:** scale the whole UI up or down. +- **Language switcher:** the desktop UI is fully internationalized. v0.16 added **Simplified Chinese (简体中文)**; English is the default. Switch via the UI language picker (`display.language`). + +--- + +## 4. The Model Picker + +Hermes is model-agnostic, and the desktop makes switching trivial. The **model picker** sits in the composer (left of the mic) and lets you change the **model**, **reasoning effort**, and **fast mode** per message: + +- The picker is **sticky per device** and **never writes your profile default** — experiment freely without rewriting config. +- Set your actual default in **Settings → Model**, including per-model reasoning-effort and fast-mode presets. +- It's the same fuzzy, hourly-refreshed catalog you get in the TUI/CLI/web (see [Part 9](./part9-custom-models.md) for routing and aliases). + +--- + +## 5. Status Bar and the YOLO Toggle + +The status bar shows live session state and exposes a **per-session YOLO toggle**. Flipping YOLO on bypasses approval prompts for that session so the agent runs tools without stopping to ask. + +> **Use YOLO deliberately.** It is genuinely useful for trusted, low-stakes loops on your own machine. Do **not** enable it for any session that reads untrusted input (email, webhooks, public chats) or has destructive tools wired up. Read [Part 19: Security Playbook](./part19-security-playbook.md) first, and keep the approval layer on for anything that touches production. + +--- + +## 6. First-Run Quick Setup via Nous Portal + +First launch offers two paths: + +- **Quick Setup** — `hermes portal` signs you in through the [Nous Portal](https://portal.nousresearch.com) and picks a model for you. The fastest way from zero to a working agent without touching YAML or hunting for API keys. +- **Full Setup** — the complete onboarding UI: providers and keys, models, tools, MCP servers, gateway, and sessions. xAI Grok OAuth is first-class here. + +You can re-open onboarding any time from Settings. + +--- + +## 7. Connect to a Remote Hermes + +The desktop app doesn't have to run the agent locally. It can connect to a **remote Hermes gateway** over a secure WebSocket (`/api/ws`): + +- **Auth:** OAuth or username/password. +- **Per-profile remote host:** point each profile at a different Hermes box. +- **Concurrent multi-profile sessions:** run several profiles at once, and link across them with cross-profile `@session` references. + +The model is "**thin GUI local, heavy agent remote**" — keep a lightweight app on your laptop while the agent, tools, and memory live on a workstation, a DGX Spark, or a VPS. (Pair this with [Part 21: Remote Sandboxes](./part21-remote-sandboxes.md) and [Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md).) + +--- + +## 8. Sessions, Files, and Voice + +- **Sessions:** archive, search, and **search-by-id**; run concurrent multi-profile sessions with cross-profile `@session` links. +- **File browser:** set the initial working directory with `hermes desktop --cwd PATH` or the `HERMES_DESKTOP_CWD` environment variable. +- **Voice:** click the mic to talk; macOS prompts for microphone permission once. + +### Management Panes + +Beyond chat, the app has dedicated panes for **Skills**, **Cron**, **Profiles**, **Messaging**, and **Agents**, plus a **Command Center** — the same surfaces you'd otherwise drive from the [web admin panel](./part12-web-dashboard.md), now native. + +--- + +## 9. Updating + +The app checks for updates in the background and offers **one-click update**; manual updates work too. This mirrors the gateway's **check-before-update** flow (verify before pulling) introduced alongside the System page in the web admin panel — see [Part 12](./part12-web-dashboard.md). + +--- + +## 10. Uninstalling + +Remove the app from **Settings → About → Danger zone**, or from the CLI: + +```bash +hermes uninstall --gui # remove the desktop GUI only +hermes uninstall # remove GUI + agent, keep your data +hermes uninstall --full # remove everything, including data +``` + +--- + +## 11. `hermes desktop` Flags + +For development and troubleshooting, `hermes desktop` accepts: + +| Flag | What it does | +|------|--------------| +| `--skip-build` | Launch without rebuilding the bundle | +| `--force-build` | Force a rebuild before launch | +| `--build-only` | Build the bundle and exit (no launch) | +| `--source` | Run from source instead of a packaged build | +| `--cwd PATH` | Set the initial working directory | +| `--hermes-root PATH` | Point at a specific Hermes install root | +| `--ignore-existing` | Ignore an already-running instance | +| `--fake-boot` | Boot the UI without starting the agent (UI dev) | + +--- + +## When to Use Desktop vs CLI/TUI + +- **Desktop** — you want a real GUI: drag-and-drop, image paste, a preview rail, point-and-click model switching, and one-click updates. Great for non-terminal users and for connecting to a remote agent. +- **TUI** (`hermes --tui`) — you live in the terminal but want live tool cards, `/steer`, queueing, and a sticky composer. See [Part 22](./part22-latest-power-moves.md). +- **CLI** (`hermes`) — scripting, cron, CI, and quick one-shots. + +It's the same agent underneath — pick the surface that fits the moment and switch whenever you want. diff --git a/part25-nvidia-local.md b/part25-nvidia-local.md new file mode 100644 index 0000000..b448717 --- /dev/null +++ b/part25-nvidia-local.md @@ -0,0 +1,100 @@ +# Part 25: NVIDIA & Local Hardware — Run Hermes on Your Own GPU + +

+ Run Hermes locally on NVIDIA RTX and DGX Spark hardware +

+ +*Hermes is provider- and model-agnostic, and that cuts both ways: you can bring a frontier cloud model **or** run the whole thing on hardware you own. Nous Research and NVIDIA worked together to make Hermes a great **always-on local agent** on **NVIDIA RTX PCs, RTX PRO workstations, and DGX Spark** — your data never leaves the machine, there are no per-token bills, and there are no rate limits. This part is about the harness on local hardware; the specific weights are up to you.* + +> Background reading: NVIDIA's writeup, [*Hermes Agent on RTX and DGX Spark*](https://blogs.nvidia.com/blog/rtx-ai-garage-hermes-agent-dgx-spark/). + +--- + +## 1. Why Run Local + +- **Privacy** — prompts, files, and memory stay on your hardware. Good for regulated data and for anything you simply don't want to send to a vendor. +- **Cost** — no per-token billing. An always-on agent that watches inboxes, runs cron, and drafts work is far cheaper on owned silicon. +- **No rate limits** — hammer it as hard as your GPU allows. +- **Always-on** — a local box is a natural home for a 24/7 gateway, watchers, and scheduled jobs (see [Part 14](./part14-fast-mode-watchers.md) and [Part 23](./part23-tenacity-stack.md)). + +The trade-off is capability per watt: a local model won't match the largest frontier models on the hardest tasks. The fix is **routing**, not religion — keep a cloud model in the fallback chain for the hard 5% and let local handle the rest (see [Part 9](./part9-custom-models.md)). + +--- + +## 2. Hardware Tiers + +| Tier | Good for | Notes | +|------|----------|-------| +| **NVIDIA RTX PC** (GeForce RTX) | A capable personal agent, embeddings, drafts, coding lanes | The mainstream entry point; Tensor Cores accelerate inference | +| **RTX PRO workstation** | Heavier, faster local inference | NVIDIA reports up to ~3× faster token generation on RTX PRO GPUs for current open models via `llama.cpp` | +| **DGX Spark** | An always-on local agent that runs big MoE models all day | **128GB unified memory**, ~**1 petaflop** of AI performance; comfortably runs 120B-class MoE models continuously | + +All three are first-class targets — pick the one that matches your workload and budget. + +--- + +## 3. The Model-Agnostic Local Stack + +Hermes doesn't ship its own inference engine; it points at whatever you're running locally: + +- **Ollama** — easiest to start; `ollama pull` a model and select it in `hermes model`. +- **LM Studio** — a first-class Hermes provider with a friendly GUI for managing local models. +- **llama.cpp** — maximum control and the path NVIDIA highlights for RTX PRO throughput. + +```bash +# Example: run a local model with Ollama, then point Hermes at it +ollama pull +hermes model # pick the local model in the fuzzy picker +``` + +Any of these expose an OpenAI-compatible endpoint, so Hermes treats them like any other provider — including in fallback chains. A common, cheap pattern: **local model as primary**, small local model for embeddings, **cloud frontier model as fallback** for the hard cases. + +--- + +## 4. The DGX Spark Playbook + +DGX Spark is the flagship local target: 128GB of unified memory means a 120B-class MoE model and its context can sit in memory and stay resident, so the agent is responsive all day instead of paging models in and out. + +A strong setup: + +1. Run the **gateway** on the DGX Spark so watchers, cron, and messaging stay always-on. +2. Keep a **big local model resident** for the bulk of the work, with a cloud model in the fallback chain for the hardest tasks. +3. Drive it from your laptop with the **[desktop app's remote backend](./part24-desktop-app.md#7-connect-to-a-remote-hermes)** — thin GUI local, heavy agent on the Spark. +4. Put durable work on **[Kanban](./part23-tenacity-stack.md)** so long-running jobs survive restarts. + +--- + +## 5. OpenShell — Kernel-Level Isolation + +**OpenShell** is a security runtime from NVIDIA and Microsoft that gives the agent **kernel-level isolation** from the rest of your OS, connecting Hermes to native Windows security primitives. The point: let a capable agent run tools on your machine without handing it the keys to everything. + +Treat OpenShell as a complement to — not a replacement for — Hermes' own [approval layer and security playbook](./part19-security-playbook.md). Defense in depth: OS-level isolation underneath, Hermes' denylist/allowlist/quarantine and prompt-injection defenses on top. + +--- + +## 6. NemoClaw and "Build It Yourself" + +NVIDIA's **"Build It Yourself"** agentic-AI series teaches building local agents with **NemoClaw** and **OpenShell**. **NemoClaw** is NVIDIA's open-source stack that optimizes **OpenClaw** — the predecessor agent framework many Hermes users migrated from (see [Part 2: OpenClaw Migration](./part2-openclaw-migration.md)) — to run well on NVIDIA devices, now including **WSL2** so Windows users get the optimized path without leaving Windows. + +If you're coming from OpenClaw and want a local-first path, NemoClaw + Hermes is the natural pairing. + +--- + +## 7. The NVIDIA Skills Hub Tap + +v0.16 added **NVIDIA as a built-in trusted Skills source**, alongside OpenAI, Anthropic, and Hugging Face. That means curated, signed skills for the NVIDIA ecosystem — **CUDA-X**, **AIQ**, and **cuOpt** — are one install away from the [Skills](./part5-creating-skills.md) system, with the same trust model as the other built-in sources. + +--- + +## 8. A Note on Models (Kept Deliberately Light) + +Because Hermes is model-agnostic, the "best local model" changes constantly — don't hard-code this week's winner. As a *current* data point, NVIDIA highlights **Qwen 3.6** (27B/35B) running on RTX / DGX Spark and reports it matching or beating prior-generation 120B–400B models while fitting on far smaller hardware. Use that as a starting point, not gospel: open `hermes model`, fuzzy-search, and pick what's good *right now*. The harness is the durable part. + +--- + +## What to Ignore + +- **Don't obsess over the leaderboard.** Pick a capable local model, wire a cloud fallback, and move on. +- **Don't run local with no fallback** if you depend on the agent — keep a cloud model in the chain for the hard 5%. +- **Don't skip isolation.** A local agent with shell and file tools is powerful; pair OpenShell (or containers/sandboxes from [Part 21](./part21-remote-sandboxes.md)) with Hermes' approval layer. +- **Don't assume bigger is always better.** A resident mid-size MoE that responds instantly often beats a giant model that pages constantly.