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
- Select (○) Custom endpoint (enter URL manually)
- Base URL: https://api.synthetic.new/openai/v1
- API key: your key from Synthetic API Getting Started
- Default model: pick from the list (e.g. hf:zai-org/GLM-5.1)
- 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:
- synthetic_zdr_search — web search via Synthetic’s API
- synthetic_quota_check — check remaining API quota (free call)
- Install:
hermes plugins install gwyntel/hermes-synthetic-plugin
- Ensure SYNTHETIC_API_KEY is set in ~/.hermes/.env:
echo "SYNTHETIC_API_KEY=your-key-here" >> ~/.hermes/.env
- 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.
Start a New Session
Tool and plugin changes don’t apply mid-conversation. Start fresh:
hermes
Or if already in a session:
/reset
Verify
- Model: type /model — should show your Synthetic model
- Vision: send an image and ask about it
- Search: ask something requiring web search
- Quota: ask the agent to run synthetic_quota_check