===== Installation =====

==== macOS / Linux / WSL2 ====

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

==== Android / Termux ====

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

<WRAP center round tip 60%>
The install script auto-detects Termux and adjusts accordingly (uses Python stdlib venv + pip instead of uv).
</WRAP>

After installation, reload your shell:

<code bash>
source ~/.bashrc   # bash
source ~/.zshrc    # zsh
</code>

Or just close and reopen your terminal.

===== Configure Synthetic as Provider =====

Run the model wizard:

<code bash>
hermes model
</code>

  - Select **(○) Custom endpoint (enter URL manually)**
  - Base URL: %%https://api.synthetic.new/openai/v1%%
  - API key: your key from [[https://dev.synthetic.new/docs/api/getting-started|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

<WRAP center round important 60%>
The base URL must end with %%/v1%% — no trailing slash.
</WRAP>

===== 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.

<WRAP center round info 60%>
%%hf:moonshotai/Kimi-K2.5%% and %%hf:nvidia/Kimi-K2.5-NVFP4%% are aliased internally and can be used interchangeably. Either one works.
</WRAP>

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

==== 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.

<code bash>
# 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"
</code>

===== 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:

<code bash>
hermes plugins install gwyntel/hermes-synthetic-plugin
</code>

  - Ensure %%SYNTHETIC_API_KEY%% is set in %%~/.hermes/.env%%:

<code bash>
echo "SYNTHETIC_API_KEY=your-key-here" >> ~/.hermes/.env
</code>

  - Enable the synthetic toolset:

<code bash>
hermes tools enable synthetic
</code>

<WRAP center round alert 60%>
%%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.
</WRAP>

Repo: [[https://github.com/gwyntel/hermes-synthetic-plugin|gwyntel/hermes-synthetic-plugin]]

===== Start a New Session =====

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

<code bash>
hermes
</code>

Or if already in a session:

<code>
/reset
</code>

===== 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%%