mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-29 01:31:41 +00:00
feat: add documentation website (Docusaurus)
- 25 documentation pages covering Getting Started, User Guide, Developer Guide, and Reference - Docusaurus with custom amber/gold theme matching the landing page branding - GitHub Actions workflow to deploy landing page + docs to GitHub Pages - Landing page at root, docs at /docs/ on hermes-agent.nousresearch.com - Content extracted and restructured from existing repo docs (README, AGENTS.md, CONTRIBUTING.md, docs/) - Auto-deploy on push to main when website/ or landingpage/ changes
This commit is contained in:
teknium1
parent
1708dcd2b2
commit
ada3713e77
45 changed files with 22822 additions and 0 deletions
8
website/docs/getting-started/_category_.json
Normal file
8
website/docs/getting-started/_category_.json
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
{
|
||||
"label": "Getting Started",
|
||||
"position": 1,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Get up and running with Hermes Agent in minutes."
|
||||
}
|
||||
}
|
||||
293
website/docs/getting-started/installation.md
Normal file
293
website/docs/getting-started/installation.md
Normal file
|
|
@ -0,0 +1,293 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
title: "Installation"
|
||||
description: "Install Hermes Agent on Linux, macOS, Windows, or WSL"
|
||||
---
|
||||
|
||||
# Installation
|
||||
|
||||
Get Hermes Agent up and running in under two minutes with the one-line installer, or follow the manual steps for full control.
|
||||
|
||||
## Quick Install
|
||||
|
||||
### Linux / macOS / WSL
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### Windows (PowerShell)
|
||||
|
||||
```powershell
|
||||
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
### Windows (CMD)
|
||||
|
||||
```cmd
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.cmd -o install.cmd && install.cmd && del install.cmd
|
||||
```
|
||||
|
||||
:::warning Windows Note
|
||||
[Git for Windows](https://git-scm.com/download/win) is required. Hermes uses Git Bash internally for shell commands.
|
||||
:::
|
||||
|
||||
### What the Installer Does
|
||||
|
||||
The installer handles everything automatically:
|
||||
|
||||
- Installs [uv](https://docs.astral.sh/uv/) (fast Python package manager) if not present
|
||||
- Installs Python 3.11 via uv if not already available (no sudo needed)
|
||||
- Clones to `~/.hermes/hermes-agent` (with submodules: mini-swe-agent, tinker-atropos)
|
||||
- Creates a virtual environment with Python 3.11
|
||||
- Installs all dependencies and submodule packages
|
||||
- Sets up the `hermes` command globally (no venv activation needed)
|
||||
- Runs the interactive setup wizard
|
||||
|
||||
### After Installation
|
||||
|
||||
Reload your shell and start chatting:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # or: source ~/.zshrc (Windows: restart your terminal)
|
||||
hermes setup # Configure API keys (if you skipped during install)
|
||||
hermes # Start chatting!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Minimum Version | Check Command | Notes |
|
||||
|-------------|----------------|---------------|-------|
|
||||
| **Git** | Any recent | `git --version` | Required |
|
||||
| **Node.js** | 18+ | `node --version` | Optional — needed for browser automation and WhatsApp bridge |
|
||||
| **ripgrep** | Any | `rg --version` | Optional — faster file search (falls back to grep) |
|
||||
|
||||
:::info
|
||||
Python and pip are **not** prerequisites. The installer uses [uv](https://docs.astral.sh/uv/) to provision Python 3.11 automatically (no sudo needed). If you already have Python 3.11+ installed, uv will use it.
|
||||
:::
|
||||
|
||||
<details>
|
||||
<summary><strong>Installing prerequisites by platform</strong></summary>
|
||||
|
||||
**Ubuntu / Debian:**
|
||||
```bash
|
||||
sudo apt update && sudo apt install git
|
||||
# Optional:
|
||||
sudo apt install ripgrep nodejs npm
|
||||
```
|
||||
|
||||
**macOS (Homebrew):**
|
||||
```bash
|
||||
brew install git
|
||||
# Optional:
|
||||
brew install ripgrep node
|
||||
```
|
||||
|
||||
**Windows (native):**
|
||||
Hermes runs natively on Windows using [Git for Windows](https://git-scm.com/download/win) (which provides Git Bash for shell commands). Install Git for Windows first, then use the PowerShell or CMD quick-install command above. WSL also works — follow the Ubuntu instructions.
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Manual Installation
|
||||
|
||||
If you prefer full control over the installation process, follow these steps.
|
||||
|
||||
### Step 1: Clone the Repository
|
||||
|
||||
Clone with `--recurse-submodules` to pull the required submodules:
|
||||
|
||||
```bash
|
||||
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
|
||||
cd hermes-agent
|
||||
```
|
||||
|
||||
If you already cloned without `--recurse-submodules`:
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### Step 2: Install uv & Create Virtual Environment
|
||||
|
||||
```bash
|
||||
# Install uv (if not already installed)
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
|
||||
# Create venv with Python 3.11 (uv downloads it if not present — no sudo needed)
|
||||
uv venv venv --python 3.11
|
||||
```
|
||||
|
||||
:::tip
|
||||
You do **not** need to activate the venv to use `hermes`. The entry point has a hardcoded shebang pointing to the venv Python, so it works globally once symlinked.
|
||||
:::
|
||||
|
||||
### Step 3: Install Python Dependencies
|
||||
|
||||
```bash
|
||||
# Tell uv which venv to install into
|
||||
export VIRTUAL_ENV="$(pwd)/venv"
|
||||
|
||||
# Install with all extras
|
||||
uv pip install -e ".[all]"
|
||||
```
|
||||
|
||||
If you only want the core agent (no Telegram/Discord/cron support):
|
||||
```bash
|
||||
uv pip install -e "."
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary><strong>Optional extras breakdown</strong></summary>
|
||||
|
||||
| Extra | What it adds | Install command |
|
||||
|-------|-------------|-----------------|
|
||||
| `all` | Everything below | `uv pip install -e ".[all]"` |
|
||||
| `messaging` | Telegram & Discord gateway | `uv pip install -e ".[messaging]"` |
|
||||
| `cron` | Cron expression parsing for scheduled tasks | `uv pip install -e ".[cron]"` |
|
||||
| `cli` | Terminal menu UI for setup wizard | `uv pip install -e ".[cli]"` |
|
||||
| `modal` | Modal cloud execution backend | `uv pip install -e ".[modal]"` |
|
||||
| `dev` | pytest & test utilities | `uv pip install -e ".[dev]"` |
|
||||
|
||||
You can combine extras: `uv pip install -e ".[messaging,cron]"`
|
||||
|
||||
</details>
|
||||
|
||||
### Step 4: Install Submodule Packages
|
||||
|
||||
```bash
|
||||
# Terminal tool backend (required for terminal/command-execution)
|
||||
uv pip install -e "./mini-swe-agent"
|
||||
|
||||
# RL training backend
|
||||
uv pip install -e "./tinker-atropos"
|
||||
```
|
||||
|
||||
Both are optional — if you skip them, the corresponding toolsets simply won't be available.
|
||||
|
||||
### Step 5: Install Node.js Dependencies (Optional)
|
||||
|
||||
Only needed for **browser automation** (Browserbase-powered):
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 6: Create the Configuration Directory
|
||||
|
||||
```bash
|
||||
# Create the directory structure
|
||||
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
|
||||
|
||||
# Copy the example config file
|
||||
cp cli-config.yaml.example ~/.hermes/config.yaml
|
||||
|
||||
# Create an empty .env file for API keys
|
||||
touch ~/.hermes/.env
|
||||
```
|
||||
|
||||
### Step 7: Add Your API Keys
|
||||
|
||||
Open `~/.hermes/.env` and add at minimum an LLM provider key:
|
||||
|
||||
```bash
|
||||
# Required — at least one LLM provider:
|
||||
OPENROUTER_API_KEY=sk-or-v1-your-key-here
|
||||
|
||||
# Optional — enable additional tools:
|
||||
FIRECRAWL_API_KEY=fc-your-key # Web search & scraping
|
||||
FAL_KEY=your-fal-key # Image generation (FLUX)
|
||||
```
|
||||
|
||||
Or set them via the CLI:
|
||||
```bash
|
||||
hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here
|
||||
```
|
||||
|
||||
### Step 8: Add `hermes` to Your PATH
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.local/bin
|
||||
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
|
||||
```
|
||||
|
||||
If `~/.local/bin` isn't on your PATH, add it to your shell config:
|
||||
|
||||
```bash
|
||||
# Bash
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
|
||||
|
||||
# Zsh
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
|
||||
|
||||
# Fish
|
||||
fish_add_path $HOME/.local/bin
|
||||
```
|
||||
|
||||
### Step 9: Run the Setup Wizard (Optional)
|
||||
|
||||
```bash
|
||||
hermes setup
|
||||
```
|
||||
|
||||
### Step 10: Verify the Installation
|
||||
|
||||
```bash
|
||||
hermes version # Check that the command is available
|
||||
hermes doctor # Run diagnostics to verify everything is working
|
||||
hermes status # Check your configuration
|
||||
hermes chat -q "Hello! What tools do you have available?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick-Reference: Manual Install (Condensed)
|
||||
|
||||
For those who just want the commands:
|
||||
|
||||
```bash
|
||||
# Install uv
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
|
||||
# Clone & enter
|
||||
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
|
||||
cd hermes-agent
|
||||
|
||||
# Create venv with Python 3.11
|
||||
uv venv venv --python 3.11
|
||||
export VIRTUAL_ENV="$(pwd)/venv"
|
||||
|
||||
# Install everything
|
||||
uv pip install -e ".[all]"
|
||||
uv pip install -e "./mini-swe-agent"
|
||||
uv pip install -e "./tinker-atropos"
|
||||
npm install # optional, for browser tools
|
||||
|
||||
# Configure
|
||||
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
|
||||
cp cli-config.yaml.example ~/.hermes/config.yaml
|
||||
touch ~/.hermes/.env
|
||||
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env
|
||||
|
||||
# Make hermes available globally
|
||||
mkdir -p ~/.local/bin
|
||||
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
|
||||
|
||||
# Verify
|
||||
hermes doctor
|
||||
hermes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| `hermes: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH |
|
||||
| `API key not set` | Run `hermes setup` 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.
|
||||
176
website/docs/getting-started/quickstart.md
Normal file
176
website/docs/getting-started/quickstart.md
Normal file
|
|
@ -0,0 +1,176 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
title: "Quickstart"
|
||||
description: "Your first conversation with Hermes Agent — from install to chatting in 2 minutes"
|
||||
---
|
||||
|
||||
# Quickstart
|
||||
|
||||
This guide walks you through installing Hermes Agent, setting up a provider, and having your first conversation. By the end, you'll know the key features and how to explore further.
|
||||
|
||||
## 1. Install Hermes Agent
|
||||
|
||||
Run the one-line installer:
|
||||
|
||||
```bash
|
||||
# Linux / macOS / WSL
|
||||
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Windows (PowerShell)
|
||||
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
After it finishes, reload your shell:
|
||||
|
||||
```bash
|
||||
source ~/.bashrc # or source ~/.zshrc
|
||||
```
|
||||
|
||||
## 2. Set Up a Provider
|
||||
|
||||
The installer runs the setup wizard automatically. If you skipped it, run:
|
||||
|
||||
```bash
|
||||
hermes setup
|
||||
```
|
||||
|
||||
This walks you through selecting an inference provider:
|
||||
|
||||
| Provider | What it is | How to set up |
|
||||
|----------|-----------|---------------|
|
||||
| **Nous Portal** | Subscription-based, zero-config | OAuth login via `hermes model` |
|
||||
| **OpenRouter** | 200+ models, pay-per-use | Enter your API key |
|
||||
| **Custom Endpoint** | VLLM, SGLang, any OpenAI-compatible API | Set base URL + API key |
|
||||
|
||||
:::tip
|
||||
You can switch providers at any time with `hermes model` — no code changes, no lock-in.
|
||||
:::
|
||||
|
||||
## 3. Start Chatting
|
||||
|
||||
```bash
|
||||
hermes
|
||||
```
|
||||
|
||||
That's it! You'll see a welcome banner with your model, available tools, and skills. Type a message and press Enter.
|
||||
|
||||
```
|
||||
❯ What can you help me with?
|
||||
```
|
||||
|
||||
The agent has access to tools for web search, file operations, terminal commands, and more — all out of the box.
|
||||
|
||||
## 4. Try Key Features
|
||||
|
||||
### Ask it to use the terminal
|
||||
|
||||
```
|
||||
❯ What's my disk usage? Show the top 5 largest directories.
|
||||
```
|
||||
|
||||
The agent will run terminal commands on your behalf and show you the results.
|
||||
|
||||
### Use 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` or `Ctrl+J` to add a new line. Great for pasting code or writing detailed prompts.
|
||||
|
||||
### Interrupt the agent
|
||||
|
||||
If the agent is taking too long, just type a new message and press Enter — it interrupts the current task and switches to your new instructions. `Ctrl+C` also works.
|
||||
|
||||
### Resume a session
|
||||
|
||||
When you exit, hermes prints a resume command:
|
||||
|
||||
```bash
|
||||
hermes --continue # Resume the most recent session
|
||||
hermes -c # Short form
|
||||
```
|
||||
|
||||
## 5. Explore Further
|
||||
|
||||
Here are some things to try next:
|
||||
|
||||
### Set up a 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
|
||||
```
|
||||
|
||||
### Connect messaging platforms
|
||||
|
||||
Chat with Hermes from your phone via Telegram, Discord, Slack, or WhatsApp:
|
||||
|
||||
```bash
|
||||
hermes gateway setup # Interactive platform configuration
|
||||
```
|
||||
|
||||
### Schedule automated tasks
|
||||
|
||||
```
|
||||
❯ Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.
|
||||
```
|
||||
|
||||
The agent will set up a cron job that runs automatically via the gateway.
|
||||
|
||||
### Browse and install skills
|
||||
|
||||
```bash
|
||||
hermes skills search kubernetes
|
||||
hermes skills install openai/skills/k8s
|
||||
```
|
||||
|
||||
Or use the `/skills` slash command inside chat.
|
||||
|
||||
### Try MCP servers
|
||||
|
||||
Connect to external tools via the Model Context Protocol:
|
||||
|
||||
```yaml
|
||||
# Add to ~/.hermes/config.yaml
|
||||
mcp_servers:
|
||||
github:
|
||||
command: npx
|
||||
args: ["-y", "@modelcontextprotocol/server-github"]
|
||||
env:
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `hermes` | Start chatting |
|
||||
| `hermes setup` | Configure providers and settings |
|
||||
| `hermes model` | Switch provider or model |
|
||||
| `hermes tools` | See all available tools |
|
||||
| `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
|
||||
- **[Tools & Toolsets](../user-guide/features/tools.md)** — Explore available capabilities
|
||||
80
website/docs/getting-started/updating.md
Normal file
80
website/docs/getting-started/updating.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
title: "Updating & Uninstalling"
|
||||
description: "How to update Hermes Agent to the latest version or uninstall it"
|
||||
---
|
||||
|
||||
# Updating & Uninstalling
|
||||
|
||||
## Updating
|
||||
|
||||
Update to the latest version with a single command:
|
||||
|
||||
```bash
|
||||
hermes update
|
||||
```
|
||||
|
||||
This pulls the latest code, updates dependencies, and prompts you to configure any new options that were added since your last update.
|
||||
|
||||
:::tip
|
||||
After updating, run `hermes config check` to see if there are new configuration options available, then `hermes config migrate` to interactively add any missing ones.
|
||||
:::
|
||||
|
||||
### Updating from Messaging Platforms
|
||||
|
||||
You can also update directly from Telegram, Discord, Slack, or WhatsApp by sending:
|
||||
|
||||
```
|
||||
/update
|
||||
```
|
||||
|
||||
This pulls the latest code, updates dependencies, and restarts the gateway.
|
||||
|
||||
### 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 and submodules
|
||||
git pull origin main
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Reinstall (picks up new dependencies)
|
||||
uv pip install -e ".[all]"
|
||||
uv pip install -e "./mini-swe-agent"
|
||||
uv pip install -e "./tinker-atropos"
|
||||
|
||||
# Check for new config options
|
||||
hermes config check
|
||||
hermes config migrate # Interactively add any missing options
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
hermes uninstall
|
||||
```
|
||||
|
||||
The uninstaller gives you the option to keep your configuration files (`~/.hermes/`) for a future 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
|
||||
```
|
||||
:::
|
||||
Loading…
Add table
Add a link
Reference in a new issue