Connect Hermes to ZBStream: Quick Install & API Configuration Guide

Hermes—the streamlined messenger of the gods—has arrived. This guide will walk you through installing Hermes with a single command, then configuring it to use your Zbstream API endpoint. Get your AI assistant up and running in minutes.

Consider this your digital hermeneutic key to connecting Hermes with Zbstream’s powerful inference backend.

PrerequisitesBefore You Begin

Before we dive in, make sure you have:

• ✓ A Linux, macOS, WSL2, Termux, or Windows environment.
• ✓ A valid Zbstream API Key and Endpoint URL.
• ✓ Basic familiarity with command-line interfaces.

Step 1Quick Install

The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, and a portable Git Bash if needed. One command, zero hassle.

Linux / macOS / WSL2 / Termux:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (Native, PowerShell):

Run this in PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, and a portable Git Bash (MinGit, unpacked to %LOCALAPPDATA%\hermes\git — no admin required, completely isolated from any system Git install). Hermes uses this bundled Git Bash to run shell commands.

If you already have Git installed, the installer detects it and uses that instead. Otherwise a ~45MB MinGit download is all you need — it won’t touch or interfere with any system Git.

Platform Notes

Android / Termux: The tested manual path is documented in the Termux guide. On Termux, Hermes installs a curated .[termux] extra because the full .[all] extra currently pulls Android-incompatible voice dependencies.

Windows: Native Windows is fully supported — the PowerShell one-liner installs everything. If you’d rather use WSL2, the Linux command works there too. Native Windows install lives under %LOCALAPPDATA%\hermes; WSL2 installs under ~/.hermes as on Linux.

After installation, reload your shell:

source ~/.bashrc    # or: source ~/.zshrc
hermes              # start chatting!

Step 2Configuration:Pointing Hermes to Zbstream

This is the crucial part where you direct Hermes to your Zbstream API. Hermes uses a two-layer configuration: system-wide and user-specific.

2.1. Locate the Configuration File

The primary configuration file is config/hermes.yaml. If it doesn’t exist, create it by copying the example:

cp config/hermes.yaml.example config/hermes.yaml

2.2. Edit the Configuration

Open config/hermes.yaml with your favorite text editor (e.g., nano, vim, or code).

Look for the api section. It will initially look like this:

api:
  url: "https://api.default-provider.com/v1"
  key: "YOUR_DEFAULT_API_KEY"
  timeout: 30

Replace the placeholders with your Zbstream credentials:

api:
  url: "https://api.zbstream.com/v1"  # Your Zbstream API URL
  key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  # Your Zbstream API Key
  timeout: 45  # Optional: adjust as needed

Save and close the file.

2.3. Environment Variables (Alternative Method)

For better security, especially in production, we recommend using environment variables. You can override the file-based config by setting:

export HERMES_API_URL="https://api.zbstream.com/v1"
export HERMES_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

To make this permanent, add these lines to your ~/.bashrc or ~/.zshrc.

2.4. Verify Your Configuration

To ensure Hermes can authenticate and connect to Zbstream, run a simple health check:

hermes health --verbose

If successful, you’ll see:

Step 3First Run:Hello, World

Now that everything is configured, let’s send a test prompt to make sure Hermes operates flawlessly through Zbstream.

hermes run --prompt "What is the current status of the network?"

Hermes should process this using your Zbstream API and return a structured response. If you encounter a 401 Unauthorized or 404 Not Found, double-check your API_URL and API_KEY for typos.

Best PracticesNext Steps

If you run into any issues, our community forum and documentation are always open. Have questions or suggestions about this guide? Feel free to reach out or leave a comment below. We’d love to hear how you’re using Hermes with Zbstream.