forked from Zakaria/hermes-agent
Hermes-agent
This commit is contained in:
Zakaria
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 1,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Get up and running with Hermes Agent in minutes."
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,157 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: "Installation"
|
||||
description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows, or Android via Termux"
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
Get Hermes Agent up and running in under two minutes!
|
||||
|
||||
## Quick Install
|
||||
### With the Hermes Desktop installer on macOS or Windows (recommended)
|
||||
To easily install the command-line and desktop applications, [download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/desktop) from our website and run it.
|
||||
|
||||
### Without Hermes Desktop:
|
||||
For a command-line only install without Hermes Desktop, run:
|
||||
|
||||
#### Linux / macOS / WSL2 / Android (Termux)
|
||||
```bash
|
||||
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
|
||||
```
|
||||
|
||||
#### Windows (native)
|
||||
|
||||
Run in powershell:
|
||||
```powershell
|
||||
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
|
||||
```
|
||||
|
||||
If you want to install & run Hermes Desktop after a command-line only install, simply run
|
||||
```bash
|
||||
hermes desktop
|
||||
```
|
||||
|
||||
### What the Installer Does
|
||||
|
||||
The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global `hermes` command setup, and LLM provider configuration. By the end, you're ready to chat.
|
||||
|
||||
#### Install Layout
|
||||
|
||||
Where the installer puts things depends on whether you're installing as a normal user or as root:
|
||||
|
||||
| Installer | Code lives at | `hermes` binary | Data directory |
|
||||
|---|---|---|---|
|
||||
| pip install | Python site-packages | `~/.local/bin/hermes` (console_scripts) | `~/.hermes/` |
|
||||
| Per-user (git installer) | `~/.hermes/hermes-agent/` | `~/.local/bin/hermes` (symlink) | `~/.hermes/` |
|
||||
| Root-mode (`sudo curl … \| sudo bash`) | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes` | `/root/.hermes/` (or `$HERMES_HOME`) |
|
||||
|
||||
The root-mode **FHS layout** (`/usr/local/lib/…`, `/usr/local/bin/hermes`) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's `~/.hermes/` or explicit `HERMES_HOME`.
|
||||
|
||||
### After Installation
|
||||
|
||||
Reload your shell and start chatting:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # or: source ~/.zshrc
|
||||
hermes # Start chatting!
|
||||
```
|
||||
|
||||
To reconfigure individual settings later, use the dedicated commands:
|
||||
|
||||
```bash
|
||||
hermes model # Choose your LLM provider and model
|
||||
hermes tools # Configure which tools are enabled
|
||||
hermes gateway setup # Set up messaging platforms
|
||||
hermes config set # Set individual config values
|
||||
hermes setup # Or run the full setup wizard to configure everything at once
|
||||
```
|
||||
|
||||
:::tip Fastest path: Nous Portal
|
||||
One subscription covers 300+ models plus the [Tool Gateway](/user-guide/features/tool-gateway) (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:
|
||||
|
||||
```bash
|
||||
hermes setup --portal
|
||||
```
|
||||
|
||||
That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Installer:** On non-Windows platforms, the only prerequisite is **Git**. The installer automatically handles everything else:
|
||||
|
||||
- **uv** (fast Python package manager)
|
||||
- **Python 3.11** (via uv, no sudo needed)
|
||||
- **Node.js v22** (for browser automation and WhatsApp bridge)
|
||||
- **ripgrep** (fast file search)
|
||||
- **ffmpeg** (audio format conversion for TTS)
|
||||
|
||||
:::info
|
||||
You do **not** need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure `git` is available (`git --version`).
|
||||
:::
|
||||
|
||||
:::tip Nix users
|
||||
If you use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the **[Nix & NixOS Setup](./nix-setup.md)** guide.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Manual / Developer Installation
|
||||
|
||||
If you want to clone the repo and install from source — for contributing, running from a specific branch, or having full control over the virtual environment — see the [Development Setup](../developer-guide/contributing.md#development-setup) section in the Contributing guide.
|
||||
|
||||
---
|
||||
|
||||
## Non-Sudo / System Service User Installs
|
||||
|
||||
Running Hermes as a dedicated unprivileged user (e.g. a `hermes` systemd service account, or any user without `sudo` access) is supported. The only thing on the install path that genuinely needs root is Playwright's `--with-deps` step, which `apt`-installs shared libraries (`libnss3`, `libxkbcommon`, etc.) used by Chromium. The installer detects whether sudo is available and gracefully degrades when it isn't — it will install the Chromium binary into the service user's own Playwright cache and print the exact command an administrator needs to run separately.
|
||||
|
||||
**Recommended split (Debian/Ubuntu):**
|
||||
|
||||
1. **One time, as an admin user with sudo**, install the system libraries Chromium needs:
|
||||
```bash
|
||||
sudo npx playwright install-deps chromium
|
||||
```
|
||||
(You can run this from anywhere — `npx` will fetch Playwright on the fly.)
|
||||
|
||||
2. **As the unprivileged service user**, run the regular installer. It will detect the missing sudo, skip `--with-deps`, and install Chromium into the user's local Playwright cache:
|
||||
```bash
|
||||
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
|
||||
```
|
||||
|
||||
If you want to skip the Playwright step entirely — for example because you're running headless and don't need browser automation — pass `--skip-browser`:
|
||||
```bash
|
||||
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
|
||||
```
|
||||
|
||||
3. **Make `hermes` available to the service user's shells.** The installer writes the launcher to `~/.local/bin/hermes`. System service accounts often have a minimal PATH that doesn't include `~/.local/bin`. Either add it to the user's environment, or symlink the launcher into a system location:
|
||||
```bash
|
||||
# Option A — add to the service user's profile
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
|
||||
|
||||
# Option B — symlink system-wide (run as an admin)
|
||||
sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes
|
||||
```
|
||||
|
||||
4. **Verify:** `hermes doctor` should now run cleanly. If you get `ModuleNotFoundError: No module named 'dotenv'`, you're invoking the repo source `hermes` file (`~/.hermes/hermes-agent/hermes`) with system Python instead of the venv launcher (`~/.hermes/hermes-agent/venv/bin/hermes`) — fix step 3.
|
||||
|
||||
The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support `--with-deps` at all, so an administrator always installs the system libraries separately. The relevant `dnf`/`zypper` commands are printed by the installer.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| `hermes: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH |
|
||||
| `API key not set` | Run `hermes model` to configure your provider, or `hermes config set OPENROUTER_API_KEY your_key` |
|
||||
| Missing config after update | Run `hermes config check` then `hermes config migrate` |
|
||||
|
||||
For more diagnostics, run `hermes doctor` — it will tell you exactly what's missing and how to fix it.
|
||||
|
||||
## Install method auto-detection
|
||||
|
||||
Hermes auto-detects whether it was installed via `pip`, the git installer, Homebrew, or NixOS, and `hermes update` prints the matching update command for that path. There's no env var to set — the detection is based on the install layout (Python site-packages, `~/.hermes/hermes-agent/`, Homebrew prefix, or Nix store path). `hermes doctor` also surfaces the detected method under its environment summary.
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: 'Learning Path'
|
||||
description: 'Choose your learning path through the Hermes Agent documentation based on your experience level and goals.'
|
||||
---
|
||||
|
||||
# Learning Path
|
||||
|
||||
Hermes Agent can do a lot — CLI assistant, Telegram/Discord bot, task automation, RL training, and more. This page helps you figure out where to start and what to read based on your experience level and what you're trying to accomplish.
|
||||
|
||||
:::tip Start Here
|
||||
If you haven't installed Hermes Agent yet, begin with the [Installation guide](/getting-started/installation) and then run through the [Quickstart](/getting-started/quickstart). Everything below assumes you have a working installation.
|
||||
:::
|
||||
|
||||
:::tip First-time provider setup
|
||||
First-time users almost always want `hermes setup --portal` — one OAuth covers a model plus the four Tool Gateway tools (search/image/TTS/browser). See [Nous Portal](/integrations/nous-portal).
|
||||
:::
|
||||
|
||||
## How to Use This Page
|
||||
|
||||
- **Know your level?** Jump to the [experience-level table](#by-experience-level) and follow the reading order for your tier.
|
||||
- **Have a specific goal?** Skip to [By Use Case](#by-use-case) and find the scenario that matches.
|
||||
- **Just browsing?** Check the [Key Features](#key-features-at-a-glance) table for a quick overview of everything Hermes Agent can do.
|
||||
|
||||
## By Experience Level
|
||||
|
||||
| Level | Goal | Recommended Reading | Time Estimate |
|
||||
|---|---|---|---|
|
||||
| **Beginner** | Get up and running, have basic conversations, use built-in tools | [Installation](/getting-started/installation) → [Quickstart](/getting-started/quickstart) → [CLI Usage](/user-guide/cli) → [Configuration](/user-guide/configuration) | ~1 hour |
|
||||
| **Intermediate** | Set up messaging bots, use advanced features like memory, cron jobs, and skills | [Sessions](/user-guide/sessions) → [Messaging](/user-guide/messaging) → [Tools](/user-guide/features/tools) → [Skills](/user-guide/features/skills) → [Memory](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | ~2–3 hours |
|
||||
| **Advanced** | Build custom tools, create skills, train models with RL, contribute to the project | [Architecture](/developer-guide/architecture) → [Adding Tools](/developer-guide/adding-tools) → [Creating Skills](/developer-guide/creating-skills) → [Contributing](/developer-guide/contributing) | ~4–6 hours |
|
||||
|
||||
## By Use Case
|
||||
|
||||
Pick the scenario that matches what you want to do. Each one links you to the relevant docs in the order you should read them.
|
||||
|
||||
### "I want a CLI coding assistant"
|
||||
|
||||
Use Hermes Agent as an interactive terminal assistant for writing, reviewing, and running code.
|
||||
|
||||
1. [Installation](/getting-started/installation)
|
||||
2. [Quickstart](/getting-started/quickstart)
|
||||
3. [CLI Usage](/user-guide/cli)
|
||||
4. [Code Execution](/user-guide/features/code-execution)
|
||||
5. [Context Files](/user-guide/features/context-files)
|
||||
6. [Tips & Tricks](/guides/tips)
|
||||
|
||||
:::tip
|
||||
Pass files directly into your conversation with context files. Hermes Agent can read, edit, and run code in your projects.
|
||||
:::
|
||||
|
||||
### "I want a Telegram/Discord bot"
|
||||
|
||||
Deploy Hermes Agent as a bot on your favorite messaging platform.
|
||||
|
||||
1. [Installation](/getting-started/installation)
|
||||
2. [Configuration](/user-guide/configuration)
|
||||
3. [Messaging Overview](/user-guide/messaging)
|
||||
4. [Telegram Setup](/user-guide/messaging/telegram)
|
||||
5. [Discord Setup](/user-guide/messaging/discord)
|
||||
6. [Voice Mode](/user-guide/features/voice-mode)
|
||||
7. [Use Voice Mode with Hermes](/guides/use-voice-mode-with-hermes)
|
||||
8. [Security](/user-guide/security)
|
||||
|
||||
For full project examples, see:
|
||||
- [Daily Briefing Bot](/guides/daily-briefing-bot)
|
||||
- [Team Telegram Assistant](/guides/team-telegram-assistant)
|
||||
|
||||
### "I want to automate tasks"
|
||||
|
||||
Schedule recurring tasks, run batch jobs, or chain agent actions together.
|
||||
|
||||
1. [Quickstart](/getting-started/quickstart)
|
||||
2. [Cron Scheduling](/user-guide/features/cron)
|
||||
3. [Batch Processing](/user-guide/features/batch-processing)
|
||||
4. [Delegation](/user-guide/features/delegation)
|
||||
5. [Hooks](/user-guide/features/hooks)
|
||||
|
||||
:::tip
|
||||
Cron jobs let Hermes Agent run tasks on a schedule — daily summaries, periodic checks, automated reports — without you being present.
|
||||
:::
|
||||
|
||||
### "I want to build custom tools/skills"
|
||||
|
||||
Extend Hermes Agent with your own tools and reusable skill packages.
|
||||
|
||||
1. [Plugins](/user-guide/features/plugins)
|
||||
2. [Build a Hermes Plugin](/guides/build-a-hermes-plugin)
|
||||
3. [Tools Overview](/user-guide/features/tools)
|
||||
4. [Skills Overview](/user-guide/features/skills)
|
||||
5. [MCP (Model Context Protocol)](/user-guide/features/mcp)
|
||||
6. [Architecture](/developer-guide/architecture)
|
||||
7. [Adding Tools](/developer-guide/adding-tools)
|
||||
8. [Creating Skills](/developer-guide/creating-skills)
|
||||
|
||||
:::tip
|
||||
For most custom tool creation, start with plugins. The [Adding Tools](/developer-guide/adding-tools)
|
||||
page is for built-in Hermes core development, not the usual user/custom-tool path.
|
||||
:::
|
||||
|
||||
### "I want to train models"
|
||||
|
||||
Use reinforcement learning to fine-tune model behavior with Hermes Agent's RL training pipeline (powered by [Atropos](https://github.com/NousResearch/atropos)).
|
||||
|
||||
1. [Quickstart](/getting-started/quickstart)
|
||||
2. [Configuration](/user-guide/configuration)
|
||||
3. [Atropos RL Environments](https://github.com/NousResearch/atropos) (external)
|
||||
4. [Provider Routing](/user-guide/features/provider-routing)
|
||||
5. [Architecture](/developer-guide/architecture)
|
||||
|
||||
:::tip
|
||||
RL training works best when you already understand the basics of how Hermes Agent handles conversations and tool calls. Run through the Beginner path first if you're new.
|
||||
:::
|
||||
|
||||
### "I want to use it as a Python library"
|
||||
|
||||
Integrate Hermes Agent into your own Python applications programmatically.
|
||||
|
||||
1. [Installation](/getting-started/installation)
|
||||
2. [Quickstart](/getting-started/quickstart)
|
||||
3. [Python Library Guide](/guides/python-library)
|
||||
4. [Architecture](/developer-guide/architecture)
|
||||
5. [Tools](/user-guide/features/tools)
|
||||
6. [Sessions](/user-guide/sessions)
|
||||
|
||||
## Key Features at a Glance
|
||||
|
||||
Not sure what's available? Here's a quick directory of major features:
|
||||
|
||||
| Feature | What It Does | Link |
|
||||
|---|---|---|
|
||||
| **Tools** | Built-in tools the agent can call (file I/O, search, shell, etc.) | [Tools](/user-guide/features/tools) |
|
||||
| **Skills** | Installable plugin packages that add new capabilities | [Skills](/user-guide/features/skills) |
|
||||
| **Memory** | Persistent memory across sessions | [Memory](/user-guide/features/memory) |
|
||||
| **Context Files** | Feed files and directories into conversations | [Context Files](/user-guide/features/context-files) |
|
||||
| **MCP** | Connect to external tool servers via Model Context Protocol | [MCP](/user-guide/features/mcp) |
|
||||
| **Cron** | Schedule recurring agent tasks | [Cron](/user-guide/features/cron) |
|
||||
| **Delegation** | Spawn sub-agents for parallel work | [Delegation](/user-guide/features/delegation) |
|
||||
| **Code Execution** | Run Python scripts that call Hermes tools programmatically | [Code Execution](/user-guide/features/code-execution) |
|
||||
| **Browser** | Web browsing and scraping | [Browser](/user-guide/features/browser) |
|
||||
| **Hooks** | Event-driven callbacks and middleware | [Hooks](/user-guide/features/hooks) |
|
||||
| **Batch Processing** | Process multiple inputs in bulk | [Batch Processing](/user-guide/features/batch-processing) |
|
||||
| **Provider Routing** | Route requests across multiple LLM providers | [Provider Routing](/user-guide/features/provider-routing) |
|
||||
|
||||
## What to Read Next
|
||||
|
||||
Based on where you are right now:
|
||||
|
||||
- **Just finished installing?** → Head to the [Quickstart](/getting-started/quickstart) to run your first conversation.
|
||||
- **Completed the Quickstart?** → Read [CLI Usage](/user-guide/cli) and [Configuration](/user-guide/configuration) to customize your setup.
|
||||
- **Comfortable with the basics?** → Explore [Tools](/user-guide/features/tools), [Skills](/user-guide/features/skills), and [Memory](/user-guide/features/memory) to unlock the full power of the agent.
|
||||
- **Setting up for a team?** → Read [Security](/user-guide/security) and [Sessions](/user-guide/sessions) to understand access control and conversation management.
|
||||
- **Ready to build?** → Jump into the [Developer Guide](/developer-guide/architecture) to understand the internals and start contributing.
|
||||
- **Want practical examples?** → Check out the [Guides](/guides/tips) section for real-world projects and tips.
|
||||
|
||||
:::tip
|
||||
You don't need to read everything. Pick the path that matches your goal, follow the links in order, and you'll be productive quickly. You can always come back to this page to find your next step.
|
||||
:::
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,381 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: "Quickstart"
|
||||
description: "Your first conversation with Hermes Agent — from install to chatting in under 5 minutes"
|
||||
---
|
||||
|
||||
# Quickstart
|
||||
|
||||
This guide gets you from zero to a working Hermes setup that survives real use. Install, choose a provider, verify a working chat, and know exactly what to do when something breaks.
|
||||
|
||||
## Prefer to watch?
|
||||
|
||||
**Onchain AI Garage** put together a Masterclass walkthrough of installation, setup, and basic commands — a good companion to this page if you'd rather follow along on video. For more, see the full [Hermes Agent Tutorials & Use Cases](https://www.youtube.com/playlist?list=PLmpUb_PWAkDxewld5ZYyKifuHxgIbiq2d) playlist.
|
||||
|
||||
<div style={{position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden', maxWidth: '100%', marginBottom: '1.5rem'}}>
|
||||
<iframe
|
||||
style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%'}}
|
||||
src="https://www.youtube-nocookie.com/embed/R3YOGfTBcQg"
|
||||
title="Hermes Agent Masterclass: Installation, Setup, Basic Commands"
|
||||
frameBorder="0"
|
||||
allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
></iframe>
|
||||
</div>
|
||||
|
||||
## Who this is for
|
||||
|
||||
- Brand new and want the shortest path to a working setup
|
||||
- Switching providers and don't want to lose time to config mistakes
|
||||
- Setting up Hermes for a team, bot, or always-on workflow
|
||||
- Tired of "it installed, but it still does nothing"
|
||||
|
||||
## The fastest path
|
||||
|
||||
Pick the row that matches your goal:
|
||||
|
||||
| Goal | Do this first | Then do this |
|
||||
|---|---|---|
|
||||
| I just want Hermes working on my machine | `hermes setup` | Run a real chat and verify it responds |
|
||||
| I already know my provider | `hermes model` | Save the config, then start chatting |
|
||||
| I want a bot or always-on setup | `hermes gateway setup` after CLI works | Connect Telegram, Discord, Slack, or another platform |
|
||||
| I want a local or self-hosted model | `hermes model` → custom endpoint | Verify the endpoint, model name, and context length |
|
||||
| I want multi-provider fallback | `hermes model` first | Add routing and fallback only after the base chat works |
|
||||
|
||||
**Rule of thumb:** if Hermes cannot complete a normal chat, do not add more features yet. Get one clean conversation working first, then layer on gateway, cron, skills, voice, or routing.
|
||||
|
||||
---
|
||||
|
||||
## 1. Install Hermes Agent
|
||||
### With the Hermes Desktop installer on macOS or Windows (recommended)
|
||||
To easily install the command-line and desktop applications, [download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/desktop) from our website and run it.
|
||||
|
||||
### Without Hermes Desktop:
|
||||
For a command-line only install without Hermes Desktop, run:
|
||||
|
||||
#### Linux / macOS / WSL2 / Android (Termux)
|
||||
```bash
|
||||
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
|
||||
```
|
||||
|
||||
#### Windows (native)
|
||||
|
||||
Run in powershell:
|
||||
```powershell
|
||||
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
|
||||
```
|
||||
|
||||
:::tip Android / Termux
|
||||
If you're installing on a phone, see the dedicated [Termux guide](./termux.md) for the tested manual path, supported extras, and current Android-specific limitations.
|
||||
:::
|
||||
|
||||
After it finishes, reload your shell:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # or source ~/.zshrc
|
||||
```
|
||||
|
||||
For detailed installation options, prerequisites, and troubleshooting, see the [Installation guide](./installation.md).
|
||||
|
||||
## 2. Choose a Provider
|
||||
|
||||
The single most important setup step. Use `hermes model` to walk through the choice interactively:
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
:::tip Easiest path: Nous Portal
|
||||
One subscription covers 300+ models plus the [Tool Gateway](../user-guide/features/tool-gateway.md) (web search, image generation, TTS, cloud browser). On a fresh install:
|
||||
|
||||
```bash
|
||||
hermes setup --portal
|
||||
```
|
||||
|
||||
That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.
|
||||
:::
|
||||
|
||||
Good defaults:
|
||||
|
||||
| Provider | What it is | How to set up |
|
||||
|----------|-----------|---------------|
|
||||
| **Nous Portal** | Subscription-based, zero-config | OAuth login via `hermes model` |
|
||||
| **OpenAI Codex** | ChatGPT OAuth, uses Codex models | Device code auth via `hermes model` |
|
||||
| **Anthropic** | Claude models directly — Max plan + extra usage credits (OAuth), or API key for pay-per-token | `hermes model` → OAuth login (requires Max + extra credits), or an Anthropic API key |
|
||||
| **OpenRouter** | Multi-provider routing across many models | Enter your API key |
|
||||
| **Z.AI** | GLM / Zhipu-hosted models | Set `GLM_API_KEY` / `ZAI_API_KEY` (also accepts `Z_AI_API_KEY`) |
|
||||
| **Kimi / Moonshot** | Moonshot-hosted coding and chat models | Set `KIMI_API_KEY` (or the Kimi-Coding-specific `KIMI_CODING_API_KEY`) |
|
||||
| **Kimi / Moonshot China** | China-region Moonshot endpoint | Set `KIMI_CN_API_KEY` |
|
||||
| **Arcee AI** | Trinity models | Set `ARCEEAI_API_KEY` |
|
||||
| **GMI Cloud** | Multi-model direct API | Set `GMI_API_KEY` |
|
||||
| **MiniMax (OAuth)** | MiniMax frontier model via browser OAuth — no API key needed (model name in `hermes_cli/models.py` may change between releases) | `hermes model` → MiniMax (OAuth) |
|
||||
| **MiniMax** | International MiniMax endpoint | Set `MINIMAX_API_KEY` |
|
||||
| **MiniMax China** | China-region MiniMax endpoint | Set `MINIMAX_CN_API_KEY` |
|
||||
| **Alibaba Cloud** | Qwen models via DashScope | Set `DASHSCOPE_API_KEY` (Qwen Coding Plan also accepts `ALIBABA_CODING_PLAN_API_KEY`) |
|
||||
| **Hugging Face** | 20+ open models via unified router (Qwen, DeepSeek, Kimi, etc.) | Set `HF_TOKEN` |
|
||||
| **AWS Bedrock** | Claude, Nova, Llama, DeepSeek via native Converse API | IAM role or `aws configure` ([guide](../guides/aws-bedrock.md)) |
|
||||
| **Azure Foundry** | Azure AI Foundry-hosted models | Set `AZURE_FOUNDRY_API_KEY` + `AZURE_FOUNDRY_BASE_URL` |
|
||||
| **Google AI Studio** | Gemini models via direct API | Set `GOOGLE_API_KEY` / `GEMINI_API_KEY` |
|
||||
| **Google Gemini (OAuth)** | Gemini via the `google-gemini-cli` OAuth flow — no key needed | `hermes model` → Google Gemini (OAuth) |
|
||||
| **xAI** | Grok models via direct API | Set `XAI_API_KEY` |
|
||||
| **xAI Grok OAuth** | SuperGrok / Premium+ subscription, no API key needed | `hermes model` → xAI Grok OAuth |
|
||||
| **NovitaAI** | Multi-model API gateway | Set `NOVITA_API_KEY` |
|
||||
| **StepFun** | Step Plan models | Set `STEPFUN_API_KEY` |
|
||||
| **Xiaomi MiMo** | Xiaomi-hosted models | Set `XIAOMI_API_KEY` |
|
||||
| **Tencent TokenHub** | Tencent-hosted models | Set `TOKENHUB_API_KEY` |
|
||||
| **Ollama Cloud** | Managed Ollama-hosted models | Set `OLLAMA_API_KEY` |
|
||||
| **LM Studio** | Local desktop app exposing an OpenAI-compatible API | Set `LM_API_KEY` (and `LM_BASE_URL` if non-default) |
|
||||
| **Qwen OAuth** | Qwen Portal browser OAuth — no API key needed | `hermes model` → Qwen OAuth |
|
||||
| **Kilo Code** | KiloCode-hosted models | Set `KILOCODE_API_KEY` |
|
||||
| **OpenCode Zen** | Pay-as-you-go access to curated models | Set `OPENCODE_ZEN_API_KEY` |
|
||||
| **OpenCode Go** | $10/month subscription for open models | Set `OPENCODE_GO_API_KEY` |
|
||||
| **DeepSeek** | Direct DeepSeek API access | Set `DEEPSEEK_API_KEY` |
|
||||
| **NVIDIA NIM** | Nemotron models via build.nvidia.com or local NIM | Set `NVIDIA_API_KEY` (optional: `NVIDIA_BASE_URL`) |
|
||||
| **GitHub Copilot** | GitHub Copilot subscription (GPT-5.x, Claude, Gemini, etc.) | OAuth via `hermes model`, or `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` |
|
||||
| **GitHub Copilot ACP** | Copilot ACP agent backend (spawns local `copilot` CLI) | `hermes model` (requires `copilot` CLI + `copilot login`) |
|
||||
| **Custom Endpoint** | VLLM, SGLang, Ollama, or any OpenAI-compatible API | Set base URL + API key |
|
||||
|
||||
For most first-time users: choose a provider, accept the defaults unless you know why you're changing them. The full provider catalog with env vars and setup steps lives on the [Providers](../integrations/providers.md) page.
|
||||
|
||||
:::caution Minimum context: 64K tokens
|
||||
Hermes Agent requires a model with at least **64,000 tokens** of context. Models with smaller windows cannot maintain enough working memory for multi-step tool-calling workflows and will be rejected at startup. Most hosted models (Claude, GPT, Gemini, Qwen, DeepSeek) meet this easily. If you're running a local model, set its context size to at least 64K (e.g. `--ctx-size 65536` for llama.cpp or `-c 65536` for Ollama).
|
||||
:::
|
||||
|
||||
:::tip
|
||||
You can switch providers at any time with `hermes model` — no lock-in. For a full list of all supported providers and setup details, see [AI Providers](../integrations/providers.md).
|
||||
:::
|
||||
|
||||
### How settings are stored
|
||||
|
||||
Hermes separates secrets from normal config:
|
||||
|
||||
- **Secrets and tokens** → `~/.hermes/.env`
|
||||
- **Non-secret settings** → `~/.hermes/config.yaml`
|
||||
|
||||
The easiest way to set values correctly is through the CLI:
|
||||
|
||||
```bash
|
||||
hermes config set model anthropic/claude-opus-4.6
|
||||
hermes config set terminal.backend docker
|
||||
hermes config set OPENROUTER_API_KEY sk-or-...
|
||||
```
|
||||
|
||||
The right value goes to the right file automatically.
|
||||
|
||||
## 3. Run Your First Chat
|
||||
|
||||
```bash
|
||||
hermes # classic CLI
|
||||
hermes --tui # modern TUI (recommended)
|
||||
```
|
||||
|
||||
You'll see a welcome banner with your model, available tools, and skills. Use a prompt that's specific and easy to verify:
|
||||
|
||||
:::tip Pick your interface
|
||||
Hermes ships with two terminal interfaces: the classic `prompt_toolkit` CLI and a newer [TUI](../user-guide/tui.md) with modal overlays, mouse selection, and non-blocking input. Both share the same sessions, slash commands, and config — try each with `hermes` vs `hermes --tui`.
|
||||
:::
|
||||
|
||||
```
|
||||
Summarize this repo in 5 bullets and tell me what the main entrypoint is.
|
||||
```
|
||||
|
||||
```
|
||||
Check my current directory and tell me what looks like the main project file.
|
||||
```
|
||||
|
||||
```
|
||||
Help me set up a clean GitHub PR workflow for this codebase.
|
||||
```
|
||||
|
||||
**What success looks like:**
|
||||
|
||||
- The banner shows your chosen model/provider
|
||||
- Hermes replies without error
|
||||
- It can use a tool if needed (terminal, file read, web search)
|
||||
- The conversation continues normally for more than one turn
|
||||
|
||||
If that works, you're past the hardest part.
|
||||
|
||||
## 4. Verify Sessions Work
|
||||
|
||||
Before moving on, make sure resume works:
|
||||
|
||||
```bash
|
||||
hermes --continue # Resume the most recent session
|
||||
hermes -c # Short form
|
||||
```
|
||||
|
||||
That should bring you back to the session you just had. If it doesn't, check whether you're in the same profile and whether the session actually saved. This matters later when you're juggling multiple setups or machines.
|
||||
|
||||
## 5. Try Key Features
|
||||
|
||||
### Use the terminal
|
||||
|
||||
```
|
||||
❯ What's my disk usage? Show the top 5 largest directories.
|
||||
```
|
||||
|
||||
The agent runs terminal commands on your behalf and shows results.
|
||||
|
||||
### Slash commands
|
||||
|
||||
Type `/` to see an autocomplete dropdown of all commands:
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| `/help` | Show all available commands |
|
||||
| `/tools` | List available tools |
|
||||
| `/model` | Switch models interactively |
|
||||
| `/personality pirate` | Try a fun personality |
|
||||
| `/save` | Save the conversation |
|
||||
|
||||
### Multi-line input
|
||||
|
||||
Press `Alt+Enter`, `Ctrl+J`, or `Shift+Enter` to add a new line. `Shift+Enter` requires a terminal that sends it as a distinct sequence (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). `Alt+Enter` and `Ctrl+J` work in every terminal.
|
||||
|
||||
### Interrupt the agent
|
||||
|
||||
If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. `Ctrl+C` also works.
|
||||
|
||||
## 6. Add the Next Layer
|
||||
|
||||
Only after the base chat works. Pick what you need:
|
||||
|
||||
### Bot or shared assistant
|
||||
|
||||
```bash
|
||||
hermes gateway setup # Interactive platform configuration
|
||||
```
|
||||
|
||||
Connect [Telegram](/user-guide/messaging/telegram), [Discord](/user-guide/messaging/discord), [Slack](/user-guide/messaging/slack), [WhatsApp](/user-guide/messaging/whatsapp), [Signal](/user-guide/messaging/signal), [Email](/user-guide/messaging/email), or [Home Assistant](/user-guide/messaging/homeassistant), or [Microsoft Teams](/user-guide/messaging/teams).
|
||||
|
||||
### Automation and tools
|
||||
|
||||
- `hermes tools` — tune tool access per platform
|
||||
- `hermes skills` — browse and install reusable workflows
|
||||
- Cron — only after your bot or CLI setup is stable
|
||||
|
||||
### Sandboxed terminal
|
||||
|
||||
For safety, run the agent in a Docker container or on a remote server:
|
||||
|
||||
```bash
|
||||
hermes config set terminal.backend docker # Docker isolation
|
||||
hermes config set terminal.backend ssh # Remote server
|
||||
```
|
||||
|
||||
### Voice mode
|
||||
|
||||
```bash
|
||||
# From the Hermes install directory (the curl installer placed it at
|
||||
# ~/.hermes/hermes-agent on Linux/macOS or %LOCALAPPDATA%\hermes\hermes-agent on Windows):
|
||||
cd ~/.hermes/hermes-agent
|
||||
uv pip install -e ".[voice]"
|
||||
# Includes faster-whisper for free local speech-to-text
|
||||
```
|
||||
|
||||
Then in the CLI: `/voice on`. Press `Ctrl+B` to record. See [Voice Mode](../user-guide/features/voice-mode.md).
|
||||
|
||||
### Skills
|
||||
|
||||
Skills are on-demand instruction documents that teach Hermes how to do a specific task — deploy to Kubernetes, open a GitHub PR, fine-tune a model, search for GIFs. Each is a `SKILL.md` file with a name, a description, and a step-by-step procedure. The agent reads the short descriptions for free and only loads a skill's full content when a task actually calls for it, so adding skills doesn't bloat every request.
|
||||
|
||||
Hermes ships with a catalog of bundled skills already installed in `~/.hermes/skills/`. You can add more from the Skills Hub, or write your own.
|
||||
|
||||
**Browse and install from the hub:**
|
||||
|
||||
```bash
|
||||
hermes skills browse # list everything available
|
||||
hermes skills search kubernetes # find skills by keyword
|
||||
hermes skills install openai/skills/k8s # install one (runs a security scan first)
|
||||
```
|
||||
|
||||
The install argument is a `source/path` slug from the hub — `openai/skills/k8s` means the `k8s` skill from OpenAI's catalog. `hermes skills browse` shows the exact slugs to use.
|
||||
|
||||
**Use a skill** — every installed skill becomes a slash command automatically:
|
||||
|
||||
```bash
|
||||
/k8s deploy the staging manifest # run the skill with a request
|
||||
/k8s # load it and let Hermes ask what you need
|
||||
```
|
||||
|
||||
This works in the CLI and in any connected messaging platform. You don't have to install everything up front — the agent picks the right bundled skill on its own during normal conversation when a task matches one.
|
||||
|
||||
See [Skills System](../user-guide/features/skills.md) for writing your own, external skill directories, and the full hub source list.
|
||||
|
||||
### MCP servers
|
||||
|
||||
```yaml
|
||||
# Add to ~/.hermes/config.yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: npx
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
|
||||
```
|
||||
|
||||
### Editor integration (ACP)
|
||||
|
||||
ACP support ships with the standard `[all]` extras, so the curl installer already includes it. Just run:
|
||||
|
||||
```bash
|
||||
hermes acp
|
||||
```
|
||||
|
||||
(If you installed without `[all]`, run `cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]"` first.)
|
||||
|
||||
See [ACP Editor Integration](../user-guide/features/acp.md).
|
||||
|
||||
---
|
||||
|
||||
## Common Failure Modes
|
||||
|
||||
These are the problems that waste the most time:
|
||||
|
||||
| Symptom | Likely cause | Fix |
|
||||
|---|---|---|
|
||||
| Hermes opens but gives empty or broken replies | Provider auth or model selection is wrong | Run `hermes model` again and confirm provider, model, and auth |
|
||||
| Custom endpoint "works" but returns garbage | Wrong base URL, model name, or not actually OpenAI-compatible | Verify the endpoint in a separate client first |
|
||||
| Gateway starts but nobody can message it | Bot token, allowlist, or platform setup is incomplete | Re-run `hermes gateway setup` and check `hermes gateway status` |
|
||||
| `hermes --continue` can't find old session | Switched profiles or session never saved | Check `hermes sessions list` and confirm you're in the right profile |
|
||||
| Model unavailable or odd fallback behavior | Provider routing or fallback settings are too aggressive | Keep routing off until the base provider is stable |
|
||||
| `hermes doctor` flags config problems | Config values are missing or stale | Fix the config, retest a plain chat before adding features |
|
||||
|
||||
## Recovery Toolkit
|
||||
|
||||
When something feels off, use this order:
|
||||
|
||||
1. `hermes doctor`
|
||||
2. `hermes model`
|
||||
3. `hermes setup`
|
||||
4. `hermes sessions list`
|
||||
5. `hermes --continue`
|
||||
6. `hermes gateway status`
|
||||
|
||||
That sequence gets you from "broken vibes" back to a known state fast.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `hermes` | Start chatting |
|
||||
| `hermes model` | Choose your LLM provider and model |
|
||||
| `hermes tools` | Configure which tools are enabled per platform |
|
||||
| `hermes setup` | Full setup wizard (configures everything at once) |
|
||||
| `hermes doctor` | Diagnose issues |
|
||||
| `hermes update` | Update to latest version |
|
||||
| `hermes gateway` | Start the messaging gateway |
|
||||
| `hermes --continue` | Resume last session |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **[CLI Guide](../user-guide/cli.md)** — Master the terminal interface
|
||||
- **[Configuration](../user-guide/configuration.md)** — Customize your setup
|
||||
- **[Messaging Gateway](../user-guide/messaging/index.md)** — Connect Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams, and more
|
||||
- **[Tools & Toolsets](../user-guide/features/tools.md)** — Explore available capabilities
|
||||
- **[AI Providers](../integrations/providers.md)** — Full provider list and setup details
|
||||
- **[Skills System](../user-guide/features/skills.md)** — Reusable workflows and knowledge
|
||||
- **[Tips & Best Practices](../guides/tips.md)** — Power user tips
|
||||
@@ -0,0 +1,236 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "Android / Termux"
|
||||
description: "Run Hermes Agent directly on an Android phone with Termux"
|
||||
---
|
||||
|
||||
# Hermes on Android with Termux
|
||||
|
||||
This is the tested path for running Hermes Agent directly on an Android phone through [Termux](https://termux.dev/).
|
||||
|
||||
It gives you a working local CLI on the phone, plus the core extras that are currently known to install cleanly on Android.
|
||||
|
||||
## What is supported in the tested path?
|
||||
|
||||
The tested Termux bundle installs:
|
||||
- the Hermes CLI
|
||||
- cron support
|
||||
- PTY/background terminal support
|
||||
- Telegram gateway support (manual / best-effort background runs)
|
||||
- MCP support
|
||||
- Honcho memory support
|
||||
- ACP support
|
||||
|
||||
Concretely, it maps to:
|
||||
|
||||
```bash
|
||||
python -m pip install -e '.[termux]' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
## What is not part of the tested path yet?
|
||||
|
||||
A few features still need desktop/server-style dependencies that are not published for Android, or have not been validated on phones yet:
|
||||
|
||||
- `.[all]` is not supported on Android today
|
||||
- the `voice` extra is blocked by `faster-whisper -> ctranslate2`, and `ctranslate2` does not publish Android wheels
|
||||
- automatic browser / Playwright bootstrap is skipped in the Termux installer
|
||||
- Docker-based terminal isolation is not available inside Termux
|
||||
- Android may still suspend Termux background jobs, so gateway persistence is best-effort rather than a normal managed service
|
||||
|
||||
That does not stop Hermes from working well as a phone-native CLI agent — it just means the recommended mobile install is intentionally narrower than the desktop/server install.
|
||||
|
||||
---
|
||||
|
||||
## Option 1: One-line installer
|
||||
|
||||
Hermes now ships a Termux-aware installer path:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
|
||||
```
|
||||
|
||||
On Termux, the installer automatically:
|
||||
- uses `pkg` for system packages
|
||||
- creates the venv with `python -m venv`
|
||||
- attempts the broad `.[termux-all]` extra first and falls back to the smaller `.[termux]` extra (then a base install) — the curl installer matches this order automatically
|
||||
- links `hermes` into `$PREFIX/bin` so it stays on your Termux PATH
|
||||
- skips the untested browser / WhatsApp bootstrap
|
||||
|
||||
If you want the explicit commands or need to debug a failed install, use the manual path below.
|
||||
|
||||
---
|
||||
|
||||
## Option 2: Manual install (fully explicit)
|
||||
|
||||
### 1. Update Termux and install system packages
|
||||
|
||||
```bash
|
||||
pkg update
|
||||
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg
|
||||
```
|
||||
|
||||
Why these packages?
|
||||
- `python` — runtime + venv support
|
||||
- `git` — clone/update the repo
|
||||
- `clang`, `rust`, `make`, `pkg-config`, `libffi`, `openssl` — needed to build a few Python dependencies on Android
|
||||
- `nodejs` — optional Node runtime for experiments beyond the tested core path
|
||||
- `ripgrep` — fast file search
|
||||
- `ffmpeg` — media / TTS conversions
|
||||
|
||||
### 2. Clone Hermes
|
||||
|
||||
```bash
|
||||
git clone https://github.com/NousResearch/hermes-agent.git
|
||||
cd hermes-agent
|
||||
```
|
||||
|
||||
### 3. Create a virtual environment
|
||||
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
|
||||
python -m pip install --upgrade pip setuptools wheel
|
||||
```
|
||||
|
||||
`ANDROID_API_LEVEL` is important for Rust / maturin-based packages such as `jiter`.
|
||||
|
||||
### 4. Install the tested Termux bundle
|
||||
|
||||
```bash
|
||||
python -m pip install -e '.[termux]' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
If you only want the minimal core agent, this also works:
|
||||
|
||||
```bash
|
||||
python -m pip install -e '.' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
### 5. Put `hermes` on your Termux PATH
|
||||
|
||||
```bash
|
||||
ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"
|
||||
```
|
||||
|
||||
`$PREFIX/bin` is already on PATH in Termux, so this makes the `hermes` command persist across new shells without re-activating the venv every time.
|
||||
|
||||
### 6. Verify the install
|
||||
|
||||
```bash
|
||||
hermes version
|
||||
hermes doctor
|
||||
```
|
||||
|
||||
### 7. Start Hermes
|
||||
|
||||
```bash
|
||||
hermes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommended follow-up setup
|
||||
|
||||
### Configure a model
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
Or set keys directly in `~/.hermes/.env`.
|
||||
|
||||
### Re-run the full interactive setup wizard later
|
||||
|
||||
```bash
|
||||
hermes setup
|
||||
```
|
||||
|
||||
### Install optional Node dependencies manually
|
||||
|
||||
The tested Termux path skips Node/browser bootstrap on purpose. If you want to experiment with browser tooling later:
|
||||
|
||||
```bash
|
||||
pkg install nodejs-lts
|
||||
npm install
|
||||
```
|
||||
|
||||
The browser tool automatically includes Termux directories (`/data/data/com.termux/files/usr/bin`) in its PATH search, so `agent-browser` and `npx` are discovered without any extra PATH configuration.
|
||||
|
||||
Treat browser / WhatsApp tooling on Android as experimental until documented otherwise.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `No solution found` when installing `.[all]`
|
||||
|
||||
Use the tested Termux bundle instead:
|
||||
|
||||
```bash
|
||||
python -m pip install -e '.[termux]' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
The blocker is currently the `voice` extra:
|
||||
- `voice` pulls `faster-whisper`
|
||||
- `faster-whisper` depends on `ctranslate2`
|
||||
- `ctranslate2` does not publish Android wheels
|
||||
|
||||
### `uv pip install` fails on Android
|
||||
|
||||
Use the Termux path with the stdlib venv + `pip` instead:
|
||||
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate
|
||||
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
|
||||
python -m pip install --upgrade pip setuptools wheel
|
||||
python -m pip install -e '.[termux]' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
### `jiter` / `maturin` complains about `ANDROID_API_LEVEL`
|
||||
|
||||
Set the API level explicitly before installing:
|
||||
|
||||
```bash
|
||||
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
|
||||
python -m pip install -e '.[termux]' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
### `hermes doctor` says ripgrep or Node is missing
|
||||
|
||||
Install them with Termux packages:
|
||||
|
||||
```bash
|
||||
pkg install ripgrep nodejs
|
||||
```
|
||||
|
||||
### Build failures while installing Python packages
|
||||
|
||||
Make sure the build toolchain is installed:
|
||||
|
||||
```bash
|
||||
pkg install clang rust make pkg-config libffi openssl
|
||||
```
|
||||
|
||||
Then retry:
|
||||
|
||||
```bash
|
||||
python -m pip install -e '.[termux]' -c constraints-termux.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known limitations on phones
|
||||
|
||||
- Docker backend is unavailable
|
||||
- local voice transcription via `faster-whisper` is unavailable in the tested path
|
||||
- browser automation setup is intentionally skipped by the installer
|
||||
- some optional extras may work, but only `.[termux]` and `.[termux-all]` are currently documented as the tested Android bundles
|
||||
|
||||
If you hit a new Android-specific issue, please open a GitHub issue with:
|
||||
- your Android version
|
||||
- `termux-info`
|
||||
- `python --version`
|
||||
- `hermes doctor`
|
||||
- the exact install command and full error output
|
||||
@@ -0,0 +1,287 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
title: "Updating & Uninstalling"
|
||||
description: "How to update Hermes Agent to the latest version or uninstall it"
|
||||
---
|
||||
|
||||
# Updating & Uninstalling
|
||||
|
||||
## Updating
|
||||
|
||||
### Git installs
|
||||
|
||||
Update to the latest version with a single command:
|
||||
|
||||
```bash
|
||||
hermes update
|
||||
```
|
||||
|
||||
This pulls the latest code from `main`, updates dependencies, and prompts you to configure any new options that were added since your last update.
|
||||
|
||||
### pip installs
|
||||
|
||||
PyPI releases track **tagged versions** (major and minor releases), not every commit on `main`. Check for updates and upgrade with:
|
||||
|
||||
```bash
|
||||
hermes update --check # see if a newer release is on PyPI
|
||||
hermes update # runs pip install --upgrade hermes-agent
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
pip install --upgrade hermes-agent # or: uv pip install --upgrade hermes-agent
|
||||
```
|
||||
|
||||
:::tip
|
||||
`hermes update` automatically detects new configuration options and prompts you to add them. If you skipped that prompt, you can manually run `hermes config check` to see missing options, then `hermes config migrate` to interactively add them.
|
||||
:::
|
||||
|
||||
### What happens during an update (git installs)
|
||||
|
||||
When you run `hermes update`, the following steps occur:
|
||||
|
||||
1. **Pairing-data snapshot** — a lightweight pre-update state snapshot is saved (covers `~/.hermes/pairing/`, Feishu comment rules, and other state files that get modified at runtime). Recoverable via the snapshot restore flow described under [Snapshots and rollback](../user-guide/checkpoints-and-rollback.md), or by extracting the most recent quick-snapshot zip Hermes wrote next to your `~/.hermes/` directory.
|
||||
2. **Git pull** — pulls the latest code from the `main` branch and updates submodules
|
||||
3. **Post-pull syntax validation + auto-rollback** — after the pull, Hermes compiles the eight critical files every `hermes` invocation imports at startup. If any fails to parse (e.g. an orphan merge-conflict marker, an accidentally truncated file), Hermes runs `git reset --hard <pre-pull-sha>` to roll the install back so your shell stays bootable. Re-run `hermes update` once the upstream fix lands.
|
||||
4. **Dependency install** — runs `uv pip install -e ".[all]"` to pick up new or changed dependencies
|
||||
5. **Config migration** — detects new config options added since your version and prompts you to set them
|
||||
6. **Gateway auto-restart** — running gateways are refreshed after the update completes so the new code takes effect immediately. Service-managed gateways (systemd on Linux, launchd on macOS) are restarted through the service manager. Manual gateways are relaunched automatically when Hermes can map the running PID back to a profile.
|
||||
|
||||
### Updating against a non-default branch: `--branch`
|
||||
|
||||
By default `hermes update` tracks `origin/main`. Pass `--branch <name>` to update against a different branch — useful for QA channels, feature branches, or release-candidate testing:
|
||||
|
||||
```bash
|
||||
hermes update --branch release-candidate
|
||||
hermes update --check --branch experimental # preview behindness only
|
||||
```
|
||||
|
||||
If your local checkout is on a different branch, Hermes auto-stashes any uncommitted work, switches HEAD to the target branch, and then pulls. Branches that don't exist locally are auto-tracked from `origin/<name>` (`git checkout -B <name> origin/<name>`). Branches that don't exist anywhere fail cleanly — your stashed changes are restored before exit so you're never stranded in a weird state. The `main`-only fork-upstream sync logic is automatically skipped on non-`main` branches.
|
||||
|
||||
### Local changes on non-interactive updates
|
||||
|
||||
When you run `hermes update` in a terminal, Hermes stashes any uncommitted source-tree changes, pulls, then **asks** whether to restore them — exactly as it always has. Nothing changes for interactive updates.
|
||||
|
||||
When the update runs **without a terminal** — from the desktop/chat app's "Update" button or a gateway-triggered update — there's no prompt to answer. The `updates.non_interactive_local_changes` setting decides what happens to your stashed changes:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
updates:
|
||||
non_interactive_local_changes: stash # default: keep + auto-restore
|
||||
# non_interactive_local_changes: discard # throw local source edits away
|
||||
```
|
||||
|
||||
- `stash` (default) — auto-stash, pull, then auto-restore your changes on top of the updated code. Nothing is lost; if a restore hits conflicts they're preserved in a git stash for manual recovery.
|
||||
- `discard` — auto-stash and drop the stash after the pull, so the update always lands on a clean tree. Use this only on machines where you never intend to keep local edits to the Hermes source. It stash-drops (not `git reset --hard` + `git clean -fd`), so ignored paths like `node_modules`, `venv`, and build outputs are never touched.
|
||||
|
||||
In the desktop app this is **Settings → Advanced → In-App Update Local Changes**.
|
||||
|
||||
### Preview-only: `hermes update --check`
|
||||
|
||||
Want to know if an update is available before pulling? Run `hermes update --check` — for git installs it fetches and compares commits against `origin/main`; for pip installs it queries PyPI for the latest release. No files are modified, no gateway is restarted. Useful in scripts and cron jobs that gate on "is there an update".
|
||||
|
||||
### Full pre-update backup: `--backup`
|
||||
|
||||
For high-value profiles (production gateways, shared team installs) you can opt into a full pre-pull backup of `HERMES_HOME` (config, auth, sessions, skills, pairing):
|
||||
|
||||
```bash
|
||||
hermes update --backup
|
||||
```
|
||||
|
||||
Or make it the default for every run:
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
updates:
|
||||
pre_update_backup: true
|
||||
```
|
||||
|
||||
`--backup` was the always-on behavior in earlier builds, but it was adding minutes to every update on large homes, so it's now opt-in. The lightweight pairing-data snapshot above still runs unconditionally.
|
||||
|
||||
### Windows: another `hermes.exe` is running
|
||||
|
||||
On Windows, `hermes update` will refuse to run if it detects another `hermes.exe` process holding the venv's entry-point executable open — most commonly the Hermes Desktop app's spawned backend, an open `hermes` REPL in another terminal, or a running gateway:
|
||||
|
||||
```
|
||||
$ hermes update
|
||||
✗ Another hermes.exe is running:
|
||||
PID 12345 hermes.exe
|
||||
|
||||
Updating now would fail to overwrite ...\venv\Scripts\hermes.exe because
|
||||
Windows blocks REPLACE on a running executable.
|
||||
|
||||
Close Hermes Desktop, exit any open `hermes` REPLs, and
|
||||
stop the gateway (`hermes gateway stop`) before retrying.
|
||||
Override with `hermes update --force` if you've already
|
||||
confirmed those processes will not write to the venv.
|
||||
```
|
||||
|
||||
Close the listed processes and re-run. If you're sure the concurrent process won't interfere (rare — usually only useful when an antivirus shim is mis-attributed), pass `--force` to skip the check. In that case the updater will still retry the `.exe` rename with exponential backoff and, on stubborn locks, schedule the replacement for next reboot via `MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT)` so the update can complete.
|
||||
|
||||
Expected output looks like:
|
||||
|
||||
```
|
||||
$ hermes update
|
||||
Updating Hermes Agent...
|
||||
📥 Pulling latest code...
|
||||
Already up to date. (or: Updating abc1234..def5678)
|
||||
📦 Updating dependencies...
|
||||
✅ Dependencies updated
|
||||
🔍 Checking for new config options...
|
||||
✅ Config is up to date (or: Found 2 new options — running migration...)
|
||||
🔄 Restarting gateways...
|
||||
✅ Gateway restarted
|
||||
✅ Hermes Agent updated successfully!
|
||||
```
|
||||
|
||||
### Recommended Post-Update Validation
|
||||
|
||||
`hermes update` handles the main update path, but a quick validation confirms everything landed cleanly:
|
||||
|
||||
1. `git status --short` — if the tree is unexpectedly dirty, inspect before continuing
|
||||
2. `hermes doctor` — checks config, dependencies, and service health
|
||||
3. `hermes --version` — confirm the version bumped as expected
|
||||
4. If you use the gateway: `hermes gateway status`
|
||||
5. If `doctor` reports npm audit issues: run `npm audit fix` in the flagged directory
|
||||
|
||||
:::warning Dirty working tree after update
|
||||
If `git status --short` shows unexpected changes after `hermes update`, stop and inspect them before continuing. This usually means local modifications were reapplied on top of the updated code, or a dependency step refreshed lockfiles.
|
||||
:::
|
||||
|
||||
### If your terminal disconnects mid-update
|
||||
|
||||
`hermes update` protects itself against accidental terminal loss:
|
||||
|
||||
- The update ignores `SIGHUP`, so closing your SSH session or terminal window no longer kills it mid-install. `pip` and `git` child processes inherit this protection, so the Python environment cannot be left half-installed by a dropped connection.
|
||||
- All output is mirrored to `~/.hermes/logs/update.log` while the update runs. If your terminal disappears, reconnect and inspect the log to see whether the update finished and whether the gateway restart succeeded:
|
||||
|
||||
```bash
|
||||
tail -f ~/.hermes/logs/update.log
|
||||
```
|
||||
|
||||
- `Ctrl-C` (SIGINT) and system shutdown (SIGTERM) are still honored — those are deliberate cancellations, not accidents.
|
||||
|
||||
You no longer need to wrap `hermes update` in `screen` or `tmux` to survive a terminal drop.
|
||||
|
||||
### Checking your current version
|
||||
|
||||
```bash
|
||||
hermes version
|
||||
```
|
||||
|
||||
Compare against the latest release at the [GitHub releases page](https://github.com/NousResearch/hermes-agent/releases).
|
||||
|
||||
### Updating from Messaging Platforms
|
||||
|
||||
You can also update directly from Telegram, Discord, Slack, WhatsApp, or Teams by sending:
|
||||
|
||||
```
|
||||
/update
|
||||
```
|
||||
|
||||
This pulls the latest code, updates dependencies, and restarts running gateways. The bot will briefly go offline during the restart (typically 5–15 seconds) and then resume.
|
||||
|
||||
### Manual Update
|
||||
|
||||
If you installed manually (not via the quick installer):
|
||||
|
||||
```bash
|
||||
cd /path/to/hermes-agent
|
||||
export VIRTUAL_ENV="$(pwd)/venv"
|
||||
|
||||
# Pull latest code
|
||||
git pull origin main
|
||||
|
||||
# Reinstall (picks up new dependencies)
|
||||
uv pip install -e ".[all]"
|
||||
|
||||
# Check for new config options
|
||||
hermes config check
|
||||
hermes config migrate # Interactively add any missing options
|
||||
```
|
||||
|
||||
### Rollback instructions
|
||||
|
||||
If an update introduces a problem, you can roll back to a previous version:
|
||||
|
||||
```bash
|
||||
cd /path/to/hermes-agent
|
||||
|
||||
# List recent versions
|
||||
git log --oneline -10
|
||||
|
||||
# Roll back to a specific commit
|
||||
git checkout <commit-hash>
|
||||
uv pip install -e ".[all]"
|
||||
|
||||
# Restart the gateway if running
|
||||
hermes gateway restart
|
||||
```
|
||||
|
||||
To roll back to a specific release tag (substitute your previous tag — e.g. a recent release like `v2026.5.16`, or any earlier tag from `git tag --sort=-version:refname`):
|
||||
|
||||
```bash
|
||||
git checkout vX.Y.Z
|
||||
uv pip install -e ".[all]"
|
||||
```
|
||||
|
||||
:::warning
|
||||
Rolling back may cause config incompatibilities if new options were added. Run `hermes config check` after rolling back and remove any unrecognized options from `config.yaml` if you encounter errors.
|
||||
:::
|
||||
|
||||
### Note for Nix users
|
||||
|
||||
If you installed via Nix flake, updates are managed through the Nix package manager:
|
||||
|
||||
```bash
|
||||
# Update the flake input
|
||||
nix flake update hermes-agent
|
||||
|
||||
# Or rebuild with the latest
|
||||
nix profile upgrade hermes-agent
|
||||
```
|
||||
|
||||
Nix installations are immutable — rollback is handled by Nix's generation system:
|
||||
|
||||
```bash
|
||||
nix profile rollback
|
||||
```
|
||||
|
||||
See [Nix Setup](./nix-setup.md) for more details.
|
||||
|
||||
---
|
||||
|
||||
## Uninstalling
|
||||
|
||||
### Git installs
|
||||
|
||||
```bash
|
||||
hermes uninstall
|
||||
```
|
||||
|
||||
The uninstaller gives you the option to keep your configuration files (`~/.hermes/`) for a future reinstall.
|
||||
|
||||
### pip installs
|
||||
|
||||
```bash
|
||||
pip uninstall hermes-agent
|
||||
rm -rf ~/.hermes # Optional — keep if you plan to reinstall
|
||||
```
|
||||
|
||||
### Manual Uninstall
|
||||
|
||||
```bash
|
||||
rm -f ~/.local/bin/hermes
|
||||
rm -rf /path/to/hermes-agent
|
||||
rm -rf ~/.hermes # Optional — keep if you plan to reinstall
|
||||
```
|
||||
|
||||
:::info
|
||||
If you installed the gateway as a system service, stop and disable it first:
|
||||
```bash
|
||||
hermes gateway stop
|
||||
# Linux: systemctl --user disable hermes-gateway
|
||||
# macOS: launchctl remove ai.hermes.gateway
|
||||
```
|
||||
:::
|
||||
Reference in New Issue
Block a user