Hermes Agent + TOKNADO
How to use Hermes Agent with TOKNADO as a custom endpoint
Hermes Agent, the open-source agent from Nous Research, can run against a Nous Portal subscription, OpenRouter, or a custom endpoint that implements the OpenAI chat completions API. TOKNADO fits that last option, so you can run Hermes on a single endpoint and key.
Below are the three ways to point Hermes at TOKNADO (wizard, .env, config.yaml), how to confirm it works, and what to check when it doesn't.
Start free trial Jump to setup
What you need
- Hermes Agent installed (the installer puts its files under
~/.hermes/). - Your TOKNADO endpoint and API key from the dashboard.
- A model ID copied from your TOKNADO dashboard.
Setup: Hermes Agent with TOKNADO
Option A: use the setup wizard
Run the model setup and pick Custom endpoint (enter URL manually). Enter the TOKNADO base URL, your key, and the model name when prompted.
hermes setup modelOption B: set environment variables
Hermes reads custom endpoint settings from
~/.hermes/.env.# ~/.hermes/.env OPENAI_BASE_URL=https://toknado.up.railway.app/v1 OPENAI_API_KEY=YOUR_TOKNADO_API_KEYOption C: edit config.yaml
Set the provider to
customand give it the base URL and default model in~/.hermes/config.yaml. Keep the key in.envrather than the YAML.model: default: "toknado/auto" provider: "custom" base_url: "https://toknado.up.railway.app/v1"Start Hermes and send a test message
Launch it and ask for something small. A reply means the endpoint, key and model are all correct.
hermes
Notes for real-world use
- Hermes is built for long-running, tool-heavy sessions, so it can consume requests quickly. Pick a plan whose rolling hourly limit matches how often you run it.
- Use
hermes config editto change settings later, or re-runhermes setup modelto switch models without reinstalling. - Don't commit
~/.hermes/.envor any file holding your key.
Troubleshooting Hermes Agent + TOKNADO
| Symptom | What to check |
|---|---|
| Wizard doesn't list your endpoint | Choose the custom/manual endpoint entry near the bottom of the provider list rather than a named provider. |
| 401 or “invalid API key” | Check OPENAI_API_KEY in ~/.hermes/.env holds the TOKNADO key, not an old OpenAI key. |
| 404 or connection error | Confirm OPENAI_BASE_URL includes the API path (normally /v1) and has no trailing /chat/completions. |
| Model not found | The default model in config.yaml must match a model ID from your dashboard exactly. |
| Chat works but a side tool fails | That feature may be calling OpenRouter on its own; set an OpenRouter key for it or skip the feature. |
FAQ
Can Hermes Agent use a custom OpenAI-compatible API?
Yes. Hermes supports a custom endpoint configured with a base URL and key, for example via OPENAI_BASE_URL and OPENAI_API_KEY in ~/.hermes/.env.
Where does Hermes store its settings?
In ~/.hermes/: config.yaml for settings, .env for keys, and auth.json for OAuth credentials.
Do I need a Nous Portal subscription?
No. Nous Portal is one option; a custom endpoint like TOKNADO is another, and you can switch between them.
How do I switch back?
Run hermes setup model again and choose a different provider.