Organic
Page
  • Show pagesource
  • Old revisions
  • Backlinks
  • Back to top
    • Site
  • Recent Changes
  • Media Manager
  • Sitemap
    • User
  • Register

    • Page tools

  • Show pagesource
  • Old revisions
  • Backlinks
  • Back to top

    • Site tools

  • Recent Changes
  • Media Manager
  • Sitemap

    • User tools

  • Register
    •
    You are here: start » harnesses » hermes-agent

    This is an old revision of the document!

    Table of Contents

    Hermes Agent

    This guide covers setting up Hermes Agent with Synthetic as your provider. For the official Hermes docs, see here.

    Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, messaging platforms, and IDEs. It’s provider-agnostic, supports persistent memory, multi-platform gateways (Telegram, Discord, Slack, etc.), skills, plugins, and profiles.

    • Pros: Self-improving through skills. Persistent cross-session memory. Multi-platform gateway. Provider-agnostic — swap models and providers mid-workflow. Plugins and MCP servers. Profiles for isolated configs. Cron scheduling. Extensive toolset (web, terminal, file, browser, code execution, vision, etc.)
    • Cons: More complex setup than some other harnesses. The sheer number of configuration options can be overwhelming. Default aux model behavior falls back to OpenRouter if not explicitly configured for your provider.

    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:

    • synthetic_zdr_search — web search via Synthetic’s API
    • synthetic_quota_check — check remaining API quota (free call)
    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