Lunos logoLunos
DocsSDKIntegration

Integration: Hermes Agent with Lunos

This guide shows how to connect Hermes Agent to Lunos using a custom endpoint. Since Lunos is fully OpenAI-compatible, it slots in with zero friction — giving you access to 100+ models through a single API key.

Prerequisites

  • Hermes Agent installed on your machine
  • A Lunos account and API key
  • A model ID available in your Lunos dashboard

Step 1 — Install Hermes Agent

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

Step 2 — Get your Lunos API key

  1. Sign up at lunos.tech (free to start, no credit card required)
  2. Go to your dashboard → API Keys → generate a new key
  3. Note the base URL: https://api.lunos.tech/v1

Step 3 — Point Hermes at Lunos

Run the model selector:

hermes model

Select "Custom endpoint (self-hosted / VLLM / etc.)" from the menu, then enter the three values it asks for:

Field Value
Base URL https://api.lunos.tech/v1
API Key Your Lunos API key
Model e.g. openai/gpt-4o, anthropic/claude-sonnet-4-6, google/gemini-2-0-flash

Hermes saves the selection and uses it for every subsequent run. To switch models later, just run hermes model again.

Step 4 — (Optional) Set via config file

You can also set it directly in ~/.hermes/config.yaml:

provider: custom
base_url: https://api.lunos.tech/v1
api_key: YOUR_LUNOS_KEY
model: openai/gpt-4o   # or any Lunos-supported model ID

Or using hermes config set:

hermes config set base_url https://api.lunos.tech/v1
hermes config set model openai/gpt-4o

Step 5 — (Optional) Add a fallback provider

Hermes supports a chain of fallback providers it tries in order when the primary model fails (rate limits, server errors, auth failures):

fallback_providers:
  - provider: custom
    base_url: https://api.lunos.tech/v1
    model: anthropic/claude-sonnet-4-6

Step 6 — Launch and test

hermes --tui

You'll see a welcome banner with your model, available tools, and skills. If Hermes can't complete a normal chat, get one clean conversation working first before layering on gateway, cron, skills, or voice.

Troubleshooting

  • 401 errors — Re-run hermes model and re-enter your Lunos key carefully; don't use console/session tokens.
  • 404 on requests — Double-check the model ID matches what Lunos supports (check your Lunos dashboard).
  • Timeouts on long steps — Set HERMES_STREAM_READ_TIMEOUT=120 (or higher) before launching Hermes.
  • Diagnose issues — Run hermes doctor.

References