Table of Contents

Installation

macOS / Linux / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Android / Termux

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The install script auto-detects Termux and adjusts accordingly (uses Python stdlib venv + pip instead of uv).

After installation, reload your shell: 

source ~/.bashrc   # bash
source ~/.zshrc    # zsh

Or just close and reopen your terminal.

Configure Synthetic as Provider

Run the model wizard: 

hermes model
  1. Select (○) Custom endpoint (enter URL manually)
  2. Base URL: https://api.synthetic.new/openai/v1
  3. API key: your key from Synthetic API Getting Started
  4. Default model: pick from the list (e.g. hf:zai-org/GLM-5.1)
  5. Context window length: leave blank for auto-detection

The base URL must end with /v1 — no trailing slash.

Configure Auxiliary Models

Hermes uses auxiliary models for background tasks: vision, web extraction, context compression, session search, etc. When your main provider is Synthetic, you need to point all aux tasks at Synthetic too — otherwise they fall back to OpenRouter (which won’t work without an OpenRouter key).

See the models page for model details and pricing to choose which models to use for each task.

Vision (required)

Kimi K2.5 is the only vision-capable model on Synthetic. Set it for image analysis to work.

hf:moonshotai/Kimi-K2.5 and hf:nvidia/Kimi-K2.5-NVFP4 are aliased internally and can be used interchangeably. Either one works. 

hermes config set auxiliary.vision.provider synthetic
hermes config set auxiliary.vision.model "hf:moonshotai/Kimi-K2.5"

Text auxiliary models

These handle fast background tasks (summarization, search, approvals, etc.). Pick models based on what you see on the models page — cheaper/faster models like Nemotron 3 Super work well for most aux tasks, while compression benefits from a stronger model. 

# Web extraction (summarizes fetched pages)
hermes config set auxiliary.web_extract.provider synthetic
hermes config set auxiliary.web_extract.model "YOUR_CHOICE_HERE"
 
# Context compression (summarizes long conversations to fit context)
hermes config set auxiliary.compression.provider synthetic
hermes config set auxiliary.compression.model "YOUR_CHOICE_HERE"
 
# Session search (searches past conversation transcripts)
hermes config set auxiliary.session_search.provider synthetic
hermes config set auxiliary.session_search.model "YOUR_CHOICE_HERE"
 
# Skills hub (skill search/install assistance)
hermes config set auxiliary.skills_hub.provider synthetic
hermes config set auxiliary.skills_hub.model "YOUR_CHOICE_HERE"
 
# Approval (auto-approves low-risk terminal commands)
hermes config set auxiliary.approval.provider synthetic
hermes config set auxiliary.approval.model "YOUR_CHOICE_HERE"
 
# MCP tool routing
hermes config set auxiliary.mcp.provider synthetic
hermes config set auxiliary.mcp.model "YOUR_CHOICE_HERE"
 
# Memory flush (consolidates memories across sessions)
hermes config set auxiliary.flush_memories.provider synthetic
hermes config set auxiliary.flush_memories.model "YOUR_CHOICE_HERE"

Install Synthetic Search Plugin

Adds two tools:

  1. Install:
hermes plugins install gwyntel/hermes-synthetic-plugin
  1. Ensure SYNTHETIC_API_KEY is set in ~/.hermes/.env:
echo "SYNTHETIC_API_KEY=your-key-here" >> ~/.hermes/.env
  1. Enable the synthetic toolset:
hermes tools enable synthetic

SYNTHETIC_API_KEY must be set in ~/.hermes/.env specifically — the plugin reads this variable. It may differ from the key stored during hermes model setup. Double-check it’s there.

Repo: gwyntel/hermes-synthetic-plugin

Start a New Session

Tool and plugin changes don’t apply mid-conversation. Start fresh: 

hermes

Or if already in a session: 

/reset

Verify

  1. Model: type /model — should show your Synthetic model
  2. Vision: send an image and ask about it
  3. Search: ask something requiring web search
  4. Quota: ask the agent to run synthetic_quota_check