mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-29 06:31:32 +00:00
docs: dedicated Nous Portal integration page and setup guide (#31296)
If Nous Portal is the recommended way to run Hermes Agent, it deserves more than a sub-section buried under `## Inference Providers`. Add two new pages and shrink the existing providers.md section to a stub that points at them. New pages: - `website/docs/integrations/nous-portal.md` — landing page. What's in the subscription (300+ model catalog table, Tool Gateway breakdown, Nous Chat, cross-platform parity, no-dotfile-credentials). Hermes 4 recommendation note. Setup paths (fresh install, existing install, headless / SSH, profiles). Day-to-day usage (portal status / portal tools / portal open, switching models, mixing gateway with own backends, subscription management). Configuration reference. Token handling. Troubleshooting. Cross-links. Sidebar-position 1 — first entry under Integrations. - `website/docs/guides/run-hermes-with-nous-portal.md` — task script. Eight numbered steps: subscribe → setup --portal → verify with portal status → first chat → switch models → customize gateway routing → voice mode → cron/always-on. Per-step troubleshooting. 'What this gets you in plain numbers' comparison table. Sidebar position 1 — first entry under Guides & Tutorials. Existing providers.md: - Replace the 80-line `### Nous Portal` deep-dive with a 13-line stub that summarizes the value prop, lists the three CLI commands, and links to the new pages. Saves ~6KB. Other provider sections and callouts (Codex Note, Two Commands, Tool Gateway tip) preserved. Sidebar: - `integrations/nous-portal` inserted right after `integrations/index`, before `integrations/providers`. - `guides/run-hermes-with-nous-portal` inserted first in Guides & Tutorials.
This commit is contained in:
Teknium
GitHub
parent
2b10024ee8
commit
2666009ccc
4 changed files with 549 additions and 73 deletions
273
website/docs/guides/run-hermes-with-nous-portal.md
Normal file
273
website/docs/guides/run-hermes-with-nous-portal.md
Normal file
|
|
@ -0,0 +1,273 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
title: "Run Hermes Agent with Nous Portal"
|
||||
description: "Start-to-finish walkthrough: subscribe, set up, switch models, enable gateway tools, and verify routing"
|
||||
---
|
||||
|
||||
# Run Hermes Agent with Nous Portal
|
||||
|
||||
This guide walks you through running Hermes Agent on a [Nous Portal](https://portal.nousresearch.com) subscription end to end — from signing up to verifying that every tool routes correctly. If you just want the overview of what the Portal is and what's in the subscription, see the [Nous Portal integration page](/docs/integrations/nous-portal). This page is the task script.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Hermes Agent installed ([Quickstart](/docs/getting-started/quickstart))
|
||||
- A web browser on the machine you're setting up (or SSH port forwarding — see [OAuth over SSH](/docs/guides/oauth-over-ssh))
|
||||
- About 5 minutes
|
||||
|
||||
You do **not** need: an OpenAI key, an Anthropic key, a Firecrawl account, a FAL account, a Browser Use account, or any other per-vendor credential. That's the whole point.
|
||||
|
||||
## 1. Get a subscription
|
||||
|
||||
Open [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription), sign up, and pick a plan.
|
||||
|
||||
Already subscribed? Skip to step 2.
|
||||
|
||||
## 2. Run the one-shot setup
|
||||
|
||||
```bash
|
||||
hermes setup --portal
|
||||
```
|
||||
|
||||
This single command does five things:
|
||||
|
||||
1. Opens your browser to portal.nousresearch.com for OAuth login
|
||||
2. Stores the refresh token at `~/.hermes/auth.json`
|
||||
3. Sets `model.provider: nous` in `~/.hermes/config.yaml`
|
||||
4. Picks a default agentic model (`anthropic/claude-sonnet-4.6` or similar)
|
||||
5. Turns on the Tool Gateway for web search, image generation, TTS, and browser automation
|
||||
|
||||
When it finishes, you're back at your terminal ready to chat.
|
||||
|
||||
### What if I'm SSH'd into a server?
|
||||
|
||||
OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. Two options:
|
||||
|
||||
```bash
|
||||
# Option A: SSH port forwarding (preferred)
|
||||
ssh -N -L 8642:127.0.0.1:8642 user@remote-host # in a local terminal
|
||||
hermes setup --portal # on the remote, open the printed URL in your local browser
|
||||
|
||||
# Option B: manual paste (for Cloud Shell, Codespaces, EC2 Instance Connect)
|
||||
hermes auth add nous --type oauth --manual-paste
|
||||
# Then re-run `hermes setup --portal` to wire the provider + gateway
|
||||
```
|
||||
|
||||
See [OAuth over SSH / Remote Hosts](/docs/guides/oauth-over-ssh) for the full walkthrough including ProxyJump chains, mosh/tmux, and ControlMaster gotchas.
|
||||
|
||||
## 3. Verify it worked
|
||||
|
||||
```bash
|
||||
hermes portal status
|
||||
```
|
||||
|
||||
You should see:
|
||||
|
||||
```
|
||||
Nous Portal
|
||||
───────────
|
||||
Auth: ✓ logged in
|
||||
Portal: https://portal.nousresearch.com
|
||||
Model: ✓ using Nous as inference provider
|
||||
|
||||
Tool Gateway
|
||||
────────────
|
||||
Web search & extract via Nous Portal
|
||||
Image generation via Nous Portal
|
||||
Text-to-speech via Nous Portal
|
||||
Browser automation via Nous Portal
|
||||
```
|
||||
|
||||
If any line shows something other than "via Nous Portal" or the auth line says "not logged in", jump to [Troubleshooting](#troubleshooting) below.
|
||||
|
||||
## 4. Run your first conversation
|
||||
|
||||
```bash
|
||||
hermes chat
|
||||
```
|
||||
|
||||
Try something that exercises both the model and the Tool Gateway:
|
||||
|
||||
```
|
||||
Hey, search the web for "Hermes Agent release notes" and summarize the top 3 hits.
|
||||
```
|
||||
|
||||
You should see Hermes call `web_search` (Firecrawl-backed, through the gateway) and respond with a summary. If the search runs and the response makes sense, you're done — the Portal is wired up end to end.
|
||||
|
||||
## 5. Pick the model you actually want
|
||||
|
||||
The default after `hermes setup --portal` is a sensible general-purpose model, but the whole point of the subscription is access to the full catalog. Switch with `/model` mid-session:
|
||||
|
||||
```bash
|
||||
/model anthropic/claude-sonnet-4.6 # best general-purpose agentic
|
||||
/model openai/gpt-5.4 # strong reasoning + tool calling
|
||||
/model google/gemini-2.5-pro # huge context window
|
||||
/model deepseek/deepseek-v3.2 # cost-effective coder
|
||||
/model anthropic/claude-opus-4.6 # heavyweight for hard problems
|
||||
```
|
||||
|
||||
Or pop the picker to browse:
|
||||
|
||||
```bash
|
||||
/model
|
||||
```
|
||||
|
||||
Pick a different default permanently:
|
||||
|
||||
```bash
|
||||
# in your terminal, outside any session
|
||||
hermes config set model.default anthropic/claude-sonnet-4.6
|
||||
```
|
||||
|
||||
### Don't pick Hermes-4 for agent work
|
||||
|
||||
Hermes-4-70B and Hermes-4-405B are available on the Portal at deep discounts, but they're **chat/reasoning models**, not tool-call-tuned. They will struggle with multi-step agent loops. Use them via [Nous Chat](https://chat.nousresearch.com) for conversation/research work, or through the [subscription proxy](/docs/user-guide/features/subscription-proxy) from non-agent tools. For Hermes Agent itself, stick to the frontier agentic models above.
|
||||
|
||||
The Portal's own [info page](https://portal.nousresearch.com/info) carries this warning too — it's the official Nous guidance, not just a Hermes-side opinion.
|
||||
|
||||
## 6. (Optional) Customize Tool Gateway routing
|
||||
|
||||
The gateway is opt-in per tool, not all-or-nothing. If you already have a Browserbase account and want to keep using it while routing web search and image generation through Nous, that's supported:
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
# → Web search → "Nous Subscription" (recommended)
|
||||
# → Image generation → "Nous Subscription" (recommended)
|
||||
# → Browser → "Browserbase" (your existing key)
|
||||
# → TTS → "Nous Subscription" (recommended)
|
||||
```
|
||||
|
||||
Verify your mix with:
|
||||
|
||||
```bash
|
||||
hermes portal tools
|
||||
```
|
||||
|
||||
You'll see per-tool routing — `via Nous Portal` for the ones routed through the subscription, and the partner name (`browserbase`, `firecrawl`, etc.) for the ones using your own keys.
|
||||
|
||||
## 7. (Optional) Enable voice mode
|
||||
|
||||
Because the Tool Gateway includes OpenAI TTS, [voice mode](/docs/user-guide/features/voice-mode) works without a separate OpenAI key:
|
||||
|
||||
```bash
|
||||
hermes setup voice
|
||||
# → pick "Nous Subscription" for TTS
|
||||
# → pick a speech-to-text backend (local faster-whisper is free, no setup)
|
||||
```
|
||||
|
||||
Then in any messaging-platform session (Telegram, Discord, Signal, etc.), send a voice message and Hermes will transcribe it, respond, and reply with synthesized voice — all on your Portal subscription.
|
||||
|
||||
## 8. (Optional) Cron + always-on workflows
|
||||
|
||||
The Portal subscription works for [cron jobs](/docs/user-guide/features/cron) and [batch processing](/docs/user-guide/features/batch-processing) the same way it works for interactive chat — the OAuth refresh token is reused automatically. No additional setup; just schedule cron jobs and they'll bill against your subscription.
|
||||
|
||||
```bash
|
||||
hermes cron add "Daily AI news summary" "every day at 9am" \
|
||||
"Search the web for top AI news and summarize the 5 most important stories"
|
||||
```
|
||||
|
||||
The cron job runs unattended, calls the model + web search + summarization all through your Portal subscription.
|
||||
|
||||
## Profiles and multi-user setups
|
||||
|
||||
If you use [Hermes profiles](/docs/user-guide/profiles) (e.g. a separate config per project), the Portal refresh token is automatically shared across all profiles via a shared token store. Sign in once on any profile, and the rest pick it up automatically.
|
||||
|
||||
For team setups where multiple humans share a machine, each human has their own Portal account → each home directory holds its own `~/.hermes/auth.json` → no token sharing across users. This is the right boundary.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `hermes portal status` shows "not logged in" after `hermes setup --portal`
|
||||
|
||||
The OAuth flow didn't complete. Re-run it:
|
||||
|
||||
```bash
|
||||
hermes auth add nous --type oauth
|
||||
```
|
||||
|
||||
If your browser doesn't open or the callback fails, you're likely on a remote/headless host — see [OAuth over SSH](/docs/guides/oauth-over-ssh) for the port-forwarding and manual-paste workarounds.
|
||||
|
||||
### "Model: currently openrouter" (or some other provider) instead of "using Nous as inference provider"
|
||||
|
||||
Your local config drifted. The OAuth worked but `model.provider` is still pointing at a different provider. Fix:
|
||||
|
||||
```bash
|
||||
hermes config set model.provider nous
|
||||
```
|
||||
|
||||
Or interactively:
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
# pick Nous Portal
|
||||
```
|
||||
|
||||
Re-verify with `hermes portal status`.
|
||||
|
||||
### Tool Gateway tools showing partner names instead of "via Nous Portal"
|
||||
|
||||
Per-tool config is overriding the gateway. Run:
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
# pick "Nous Subscription" for any tool you want gateway-routed
|
||||
```
|
||||
|
||||
Some users intentionally mix — e.g. routing web through Nous but using their own Browserbase key for browser. If that's intentional, leave it alone. If not, this command fixes it.
|
||||
|
||||
### "Re-authentication required" mid-session
|
||||
|
||||
Your Portal refresh token was invalidated (password change, manual revoke, session expiry). The token is now quarantined locally so Hermes doesn't replay it endlessly. Just log in again:
|
||||
|
||||
```bash
|
||||
hermes auth add nous
|
||||
```
|
||||
|
||||
The quarantine clears automatically on successful re-login.
|
||||
|
||||
### Model I want isn't in the `/model` picker
|
||||
|
||||
The Portal catalog mirrors OpenRouter's model list (300+). If a model is missing, try typing the OpenRouter-style slug directly:
|
||||
|
||||
```bash
|
||||
/model anthropic/claude-opus-4.6
|
||||
/model openai/o1-2025-12-17
|
||||
```
|
||||
|
||||
If a model is genuinely unavailable, [open an issue](https://github.com/NousResearch/hermes-agent/issues) — most gaps are routing config we can update.
|
||||
|
||||
### Billing not appearing on my Portal account
|
||||
|
||||
`hermes portal status` will tell you whether you're actually routing through the Portal or some other provider. Common causes:
|
||||
|
||||
- `model.provider` set to `openrouter`/`anthropic`/etc. instead of `nous`
|
||||
- An OAuth refresh failure that fell back to a different configured provider
|
||||
- Multiple Hermes profiles where you're using the wrong one (check `hermes profile current`)
|
||||
|
||||
### Want to revoke and start clean
|
||||
|
||||
```bash
|
||||
hermes auth remove nous # wipes the local refresh token
|
||||
# Then re-run setup or remove the subscription from the Portal web UI
|
||||
```
|
||||
|
||||
## What this gets you, in plain numbers
|
||||
|
||||
| Without Portal | With Portal |
|
||||
|----------------|-------------|
|
||||
| 1× OpenRouter / Anthropic / OpenAI key in `.env` | 1× OAuth refresh token, no `.env` keys |
|
||||
| 1× Firecrawl key for web | Web routed through gateway |
|
||||
| 1× FAL key for image gen | Image gen routed through gateway |
|
||||
| 1× Browser Use / Browserbase key for browser | Browser routed through gateway |
|
||||
| 1× OpenAI key for TTS / voice mode | TTS routed through gateway |
|
||||
| 5 separate dashboards, top-ups, invoices | 1 subscription, 1 invoice |
|
||||
| Cross-machine: replicate all 5 keys | Cross-machine: re-OAuth once |
|
||||
|
||||
That's the deal. If you're using more than two of those backends anyway, the subscription pays for itself.
|
||||
|
||||
## See also
|
||||
|
||||
- **[Nous Portal integration page](/docs/integrations/nous-portal)** — Overview of what's in the subscription
|
||||
- **[Tool Gateway](/docs/user-guide/features/tool-gateway)** — Full details on every gateway-routed tool
|
||||
- **[Subscription proxy](/docs/user-guide/features/subscription-proxy)** — Use your Portal subscription from non-Hermes tools
|
||||
- **[Voice mode](/docs/user-guide/features/voice-mode)** — Set up voice conversations on the Portal subscription
|
||||
- **[OAuth over SSH](/docs/guides/oauth-over-ssh)** — Remote / headless login patterns
|
||||
- **[Profiles](/docs/user-guide/profiles)** — Share one Portal login across multiple Hermes configurations
|
||||
268
website/docs/integrations/nous-portal.md
Normal file
268
website/docs/integrations/nous-portal.md
Normal file
|
|
@ -0,0 +1,268 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
title: "Nous Portal"
|
||||
description: "One subscription, 300+ frontier models, the Tool Gateway, and Nous Chat — the recommended way to run Hermes Agent"
|
||||
---
|
||||
|
||||
# Nous Portal
|
||||
|
||||
[Nous Portal](https://portal.nousresearch.com) is Nous Research's unified subscription gateway and **the recommended way to run Hermes Agent**. One OAuth login replaces the juggling act of separate accounts, API keys, and billing relationships across every model lab, search API, image generator, and browser provider you'd otherwise need to wire up by hand.
|
||||
|
||||
If you only have time to set up one thing, set up this. The fastest path:
|
||||
|
||||
```bash
|
||||
hermes setup --portal
|
||||
```
|
||||
|
||||
That single command runs the Portal OAuth, sets Nous as your inference provider in `config.yaml`, and turns on the Tool Gateway. You're ready to `hermes chat` immediately after.
|
||||
|
||||
Don't have a subscription yet? [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) — sign up, then come back and run the command above.
|
||||
|
||||
## What's in the subscription
|
||||
|
||||
### 300+ frontier models, one bill
|
||||
|
||||
The Portal proxies a curated catalog of agentic models from across the ecosystem — billed against your Nous subscription instead of one credit balance per lab.
|
||||
|
||||
| Family | Models |
|
||||
|--------|--------|
|
||||
| **Anthropic Claude** | Opus, Sonnet, Haiku (4.x series) |
|
||||
| **OpenAI** | GPT-5.4, o-series reasoning models |
|
||||
| **Google Gemini** | 2.5 Pro, 2.5 Flash |
|
||||
| **DeepSeek** | DeepSeek V3.2, DeepSeek-R1 |
|
||||
| **Qwen** | Qwen3 family, Qwen Coder |
|
||||
| **Kimi / Moonshot** | Kimi-K2, Kimi-Latest |
|
||||
| **GLM / Zhipu** | GLM-4.6, GLM-4-Plus |
|
||||
| **MiniMax** | M2.7, M1 |
|
||||
| **xAI** | Grok-4, Grok-3 |
|
||||
| **Hermes** | Hermes-4-70B, Hermes-4-405B (chat, see [note below](#a-note-on-hermes-4)) |
|
||||
| **+ everything else** | 240+ additional models — the full agentic frontier |
|
||||
|
||||
Routing happens through OpenRouter under the hood, so model availability and failover behavior matches what you'd get with an OpenRouter key — just billed against your Nous subscription instead. Switch between Claude Sonnet 4.6 for code and Gemini 2.5 Pro for long context with `/model` mid-session — no new credentials, no top-ups, no surprise zero-balance errors.
|
||||
|
||||
### The Nous Tool Gateway
|
||||
|
||||
The same subscription unlocks the [Tool Gateway](/docs/user-guide/features/tool-gateway), which routes Hermes Agent's tool calls through Nous-managed infrastructure. Five backends, one login:
|
||||
|
||||
| Tool | Partner | What it does |
|
||||
|------|---------|--------------|
|
||||
| **Web search & extract** | Firecrawl | Agent-grade search and full-page extraction. No Firecrawl API key, no rate limit babysitting. |
|
||||
| **Image generation** | FAL | Nine models under one endpoint: FLUX 2 Klein 9B, FLUX 2 Pro, Z-Image Turbo, Nano Banana Pro (Gemini 3 Pro Image), GPT Image 1.5, GPT Image 2, Ideogram V3, Recraft V4 Pro, Qwen Image. |
|
||||
| **Text-to-speech** | OpenAI TTS | High-quality TTS without a separate OpenAI key. Enables [voice mode](/docs/user-guide/features/voice-mode) across messaging platforms. |
|
||||
| **Cloud browser automation** | Browser Use | Headless Chromium sessions for `browser_navigate`, `browser_click`, `browser_type`, `browser_vision`. No Browserbase account needed. |
|
||||
| **Cloud terminal sandbox** | Modal | Serverless terminal sandboxes for code execution (optional add-on). |
|
||||
|
||||
Without the gateway, hooking each of those up means a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key, and a Modal account — five separate signups, five separate dashboards, five separate top-up flows. With the gateway, all of it routes through one subscription.
|
||||
|
||||
You can also enable just specific gateway tools (e.g. web search but not image generation) — see [Mixing the gateway with your own backends](#mixing-the-gateway-with-your-own-backends) below.
|
||||
|
||||
### Nous Chat
|
||||
|
||||
Your Portal account also covers [chat.nousresearch.com](https://chat.nousresearch.com) — Nous Research's web chat interface with the same model catalog. Useful when you're away from your terminal, or for non-agent conversation work.
|
||||
|
||||
### No credentials in your dotfiles
|
||||
|
||||
Because everything routes through one OAuth-authenticated Portal session, you don't accumulate a `.env` file with a dozen long-lived API keys. The refresh token at `~/.hermes/auth.json` is the only credential on disk, and Hermes mints short-lived JWTs from it per request — see [Token handling](#token-handling) below.
|
||||
|
||||
### Cross-platform parity
|
||||
|
||||
[Native Windows](/docs/user-guide/windows-native) is still early beta, and per-tool API key setup is its rough edge — installing a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key from Windows is the highest-friction part of getting a useful agent. A Portal subscription smooths that out: one OAuth covers the model and every gateway tool, so Windows users get the same experience as macOS/Linux without manually configuring four backends.
|
||||
|
||||
## A note on Hermes 4
|
||||
|
||||
Nous Research's own **Hermes 4** family (Hermes-4-70B, Hermes-4-405B) is available through the Portal at heavily discounted rates. These are **frontier hybrid-reasoning chat models** — strong at math, science, instruction following, schema adherence, roleplay, and long-form writing.
|
||||
|
||||
They are **not recommended for use inside Hermes Agent**, however. Hermes 4 is tuned for chat and reasoning, not the rapid-fire tool-calling loop the agent relies on. Use them for [Nous Chat](https://chat.nousresearch.com), for research workflows, or via the [subscription proxy](/docs/user-guide/features/subscription-proxy) from other tooling — but for agent work, pick a frontier agentic model from the catalog instead:
|
||||
|
||||
```bash
|
||||
/model anthropic/claude-sonnet-4.6 # best general-purpose agentic model
|
||||
/model openai/gpt-5.4 # strong reasoning + tool calling
|
||||
/model google/gemini-2.5-pro # huge context window
|
||||
/model deepseek/deepseek-v3.2 # cost-effective coder
|
||||
```
|
||||
|
||||
The Portal's own [model info page](https://portal.nousresearch.com/info) carries the same warning, so this isn't a Hermes-side opinion — it's the official guidance from Nous Research.
|
||||
|
||||
## Setup
|
||||
|
||||
### Fresh install — one command
|
||||
|
||||
```bash
|
||||
hermes setup --portal
|
||||
```
|
||||
|
||||
This runs the full setup in one shot:
|
||||
|
||||
1. Opens your browser to portal.nousresearch.com for OAuth login
|
||||
2. Stores the refresh token at `~/.hermes/auth.json`
|
||||
3. Sets Nous as your inference provider in `~/.hermes/config.yaml`
|
||||
4. Turns on the Tool Gateway (web, image, TTS, browser routing)
|
||||
5. Returns you to your terminal ready to `hermes chat`
|
||||
|
||||
If you don't have a subscription yet, sign up at [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) first.
|
||||
|
||||
### Existing install — add Portal alongside other providers
|
||||
|
||||
If you already have Hermes configured with OpenRouter, Anthropic, or any other provider and you want to add the Portal alongside them:
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
# pick "Nous Portal" from the provider list
|
||||
# browser opens, sign in, done
|
||||
```
|
||||
|
||||
Your existing providers stay configured. You can switch between them with `/model` mid-session or `hermes model` between sessions — the Portal becomes one of your available providers, not your only one.
|
||||
|
||||
### Headless / SSH / remote setup
|
||||
|
||||
OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. For remote hosts, see [OAuth over SSH / Remote Hosts](/docs/guides/oauth-over-ssh) — the same patterns work for the Portal as for any other OAuth-based provider (`ssh -L` port forwarding, `--manual-paste` for browser-only environments like Cloud Shell / Codespaces).
|
||||
|
||||
### Profile setup
|
||||
|
||||
If you use [Hermes profiles](/docs/user-guide/profiles), the Portal refresh token is automatically shared across all profiles via a shared token store. Sign in once on any profile, and the rest pick it up automatically — no need to repeat the OAuth flow per profile.
|
||||
|
||||
## Using the Portal day-to-day
|
||||
|
||||
### Inspecting what's wired up
|
||||
|
||||
```bash
|
||||
hermes portal status # login status, subscription info, model + gateway routing
|
||||
hermes portal tools # detailed Tool Gateway catalog with per-tool routing
|
||||
hermes portal open # open the subscription management page in your browser
|
||||
```
|
||||
|
||||
`hermes portal status` (or just `hermes portal`) gives you the high-level overview:
|
||||
|
||||
```
|
||||
Nous Portal
|
||||
───────────
|
||||
Auth: ✓ logged in
|
||||
Portal: https://portal.nousresearch.com
|
||||
Model: ✓ using Nous as inference provider
|
||||
|
||||
Tool Gateway
|
||||
────────────
|
||||
Web search & extract via Nous Portal
|
||||
Image generation via Nous Portal
|
||||
Text-to-speech via Nous Portal
|
||||
Browser automation via Nous Portal
|
||||
Cloud terminal not configured
|
||||
```
|
||||
|
||||
### Switching models
|
||||
|
||||
Inside a session:
|
||||
|
||||
```bash
|
||||
/model anthropic/claude-sonnet-4.6
|
||||
/model openai/gpt-5.4
|
||||
/model google/gemini-2.5-pro
|
||||
```
|
||||
|
||||
Or open the picker:
|
||||
|
||||
```bash
|
||||
/model
|
||||
# arrow keys, enter to select
|
||||
```
|
||||
|
||||
Outside a session (the full setup wizard, useful when adding a new provider):
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
```
|
||||
|
||||
### Mixing the gateway with your own backends
|
||||
|
||||
If you already have, say, a Browserbase account and want to keep using it while routing web search and image generation through Nous, that's supported. Use `hermes tools` to pick backends per tool:
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
# → Web search → "Nous Subscription"
|
||||
# → Image generation → "Nous Subscription"
|
||||
# → Browser → "Browserbase" (your existing key)
|
||||
# → TTS → "Nous Subscription"
|
||||
```
|
||||
|
||||
The Tool Gateway is opt-in per tool, not all-or-nothing. See the [Tool Gateway docs](/docs/user-guide/features/tool-gateway) for the full per-tool configuration matrix.
|
||||
|
||||
### Subscription management
|
||||
|
||||
Manage your plan, view usage, or upgrade/cancel at any time:
|
||||
|
||||
- **Web:** [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription)
|
||||
- **CLI shortcut:** `hermes portal open` (opens the same page in your default browser)
|
||||
|
||||
## Configuration reference
|
||||
|
||||
After `hermes setup --portal`, `~/.hermes/config.yaml` will look like:
|
||||
|
||||
```yaml
|
||||
model:
|
||||
provider: nous
|
||||
default: anthropic/claude-sonnet-4.6 # or whatever model you picked
|
||||
base_url: https://inference.nousresearch.com/v1
|
||||
```
|
||||
|
||||
The Tool Gateway settings live under their respective tool sections:
|
||||
|
||||
```yaml
|
||||
web:
|
||||
backend: nous # web search/extract routes through Tool Gateway
|
||||
|
||||
image_gen:
|
||||
provider: nous
|
||||
|
||||
tts:
|
||||
provider: nous
|
||||
|
||||
browser:
|
||||
backend: nous
|
||||
```
|
||||
|
||||
The OAuth refresh token is stored separately at `~/.hermes/auth.json` (not in `config.yaml` — credentials and configuration are kept separate by design).
|
||||
|
||||
## Token handling
|
||||
|
||||
Hermes mints a short-lived JWT from your stored Portal refresh token on each inference call rather than reusing a long-lived API key. The token lifecycle is fully automatic — refresh, mint, retry on transient 401 — and you never see it.
|
||||
|
||||
If the Portal invalidates the refresh token (password change, manual revoke, session expiry), the invalid refresh token is **quarantined locally** so Hermes stops replaying it and you don't see a stream of identical 401s. The next call surfaces a clear "re-authentication required" message. Run `hermes auth add nous` to log in again; the quarantine clears on the next successful login.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `hermes portal status` shows "not logged in"
|
||||
|
||||
You haven't completed the OAuth flow, or your refresh token was wiped. Run:
|
||||
|
||||
```bash
|
||||
hermes auth add nous --type oauth
|
||||
```
|
||||
|
||||
or use `hermes model` and re-select Nous Portal.
|
||||
|
||||
### Got a "re-authentication required" message mid-session
|
||||
|
||||
Your Portal refresh token was invalidated (password change, manual revoke, or session expiry). Run `hermes auth add nous` and your next request will use the new credentials. Any quarantine on the old token clears automatically on successful re-login.
|
||||
|
||||
### Want to use a specific provider model that the Portal doesn't expose
|
||||
|
||||
The Portal proxies through OpenRouter, so any model that OpenRouter supports is generally available. If a specific model isn't appearing in `/model`, try the OpenRouter-style slug directly:
|
||||
|
||||
```bash
|
||||
/model anthropic/claude-opus-4.6
|
||||
```
|
||||
|
||||
If a model is genuinely missing, [open an issue](https://github.com/NousResearch/hermes-agent/issues) — we surface the Portal's catalog to Hermes and gaps usually mean a routing config we can update.
|
||||
|
||||
### Bills not appearing on my Portal account
|
||||
|
||||
Check `hermes portal status` first — if it shows you're using a different provider (`Model: currently openrouter` instead of `using Nous as inference provider`), your local config has drifted. Run `hermes model`, pick Nous Portal, and the next request will route through your subscription.
|
||||
|
||||
## See also
|
||||
|
||||
- **[Tool Gateway](/docs/user-guide/features/tool-gateway)** — Full details on every gateway tool, per-tool config, and pricing
|
||||
- **[Subscription proxy](/docs/user-guide/features/subscription-proxy)** — Use your Portal subscription from non-Hermes tools (other agents, scripts, third-party clients)
|
||||
- **[Voice mode](/docs/user-guide/features/voice-mode)** — Voice conversations using the Portal's OpenAI TTS
|
||||
- **[AI Providers](/docs/integrations/providers)** — Full provider catalog if you want to compare alternatives
|
||||
- **[OAuth over SSH](/docs/guides/oauth-over-ssh)** — Login from remote hosts or browser-only environments
|
||||
- **[Profiles](/docs/user-guide/profiles)** — Multiple Hermes configurations sharing one Portal login
|
||||
|
|
@ -54,84 +54,17 @@ In the `model:` config section, you can use either `default:` or `model:` as the
|
|||
|
||||
### Nous Portal
|
||||
|
||||
[Nous Portal](https://portal.nousresearch.com) is Nous Research's unified subscription gateway and **the recommended way to use Hermes Agent**. One OAuth login replaces the juggling act of separate accounts, API keys, and billing relationships across every model lab, search API, image generator, and browser provider you'd otherwise need to wire up by hand.
|
||||
|
||||
#### What you get
|
||||
|
||||
**300+ frontier models, one bill.** The portal proxies a curated catalog of agentic models from across the ecosystem — Anthropic Claude (Opus, Sonnet, Haiku), OpenAI (GPT-5.4, o-series), Google Gemini (2.5 Pro, Flash), DeepSeek, Qwen, Kimi, GLM, MiniMax, xAI Grok, and the rest of the agentic frontier. Routing happens through OpenRouter under the hood, so you get the same model availability and failover behavior, but billed against your Nous subscription instead of one credit balance per lab. Switch between Claude Sonnet 4.6 for code and Gemini 2.5 Pro for long context with `/model` mid-session — no new credentials, no top-ups, no surprise zero-balance errors.
|
||||
|
||||
**The Nous Tool Gateway.** The same subscription unlocks the [Tool Gateway](/docs/user-guide/features/tool-gateway), which routes Hermes Agent's tool calls through Nous-managed infrastructure:
|
||||
|
||||
- **Web search and extraction** — agent-grade search and full-page extraction (Firecrawl-backed). No Firecrawl API key, no rate limits to manage.
|
||||
- **Image generation** — nine models under one endpoint: FLUX 2 Klein 9B, FLUX 2 Pro, Z-Image Turbo, Nano Banana Pro (Gemini 3 Pro Image), GPT Image 1.5, GPT Image 2, Ideogram V3, Recraft V4 Pro, Qwen Image.
|
||||
- **Text-to-speech** — OpenAI TTS without a separate OpenAI key. Enables [voice mode](/docs/user-guide/features/voice-mode).
|
||||
- **Cloud browser automation** — headless Chromium sessions via Browser Use. All the agent-driving primitives (`browser_navigate`, `browser_click`, `browser_type`, `browser_vision`) without a Browserbase account.
|
||||
- **Modal sandbox** (optional add-on) — serverless terminal sandboxes for code execution, available through the same subscription via `hermes setup terminal`.
|
||||
|
||||
Without the gateway, hooking each of those up means a Firecrawl account, a FAL account, a Browser Use account, an OpenAI key — four separate signups, four separate dashboards, four separate top-up flows. With the gateway, all of it routes through one subscription. See the [Tool Gateway docs](/docs/user-guide/features/tool-gateway) for the full breakdown and per-tool configuration.
|
||||
|
||||
**Nous Chat.** Your portal account also covers [chat.nousresearch.com](https://chat.nousresearch.com) — Nous Research's web chat interface with the same model catalog, useful when you're away from your terminal.
|
||||
|
||||
**Cross-platform parity.** [Native Windows](/docs/user-guide/windows-native) is still early beta and per-tool API key setup is its rough edge. A portal subscription smooths that out: one OAuth covers the model and every gateway tool, so Windows users get the same experience as macOS/Linux without manually configuring four backends.
|
||||
|
||||
**No credentials in your dotfiles.** Because everything routes through one OAuth-authenticated portal session, you don't accumulate a `.env` file with a dozen long-lived API keys. The refresh token at `~/.hermes/auth.json` is the only credential on disk, and Hermes mints short-lived JWTs from it per request (see [Token handling](#token-handling) below).
|
||||
|
||||
#### A note on Hermes 4
|
||||
|
||||
Nous Research's own **Hermes 4** family (Hermes-4-70B, Hermes-4-405B) is available through the portal at heavily discounted rates. These are **frontier hybrid-reasoning chat models** — strong at math, science, instruction following, schema adherence, roleplay, and long-form writing.
|
||||
|
||||
They are **not recommended for use inside Hermes Agent**, however. Hermes 4 is tuned for chat and reasoning, not the rapid-fire tool-calling loop the agent relies on. Use them for [Nous Chat](https://chat.nousresearch.com), for research workflows, or via the [subscription proxy](/docs/user-guide/features/subscription-proxy) from other tooling — but for agent work, pick a frontier agentic model from the catalog instead:
|
||||
|
||||
```
|
||||
/model anthropic/claude-sonnet-4.6 # best general-purpose agentic model
|
||||
/model openai/gpt-5.4 # strong reasoning + tool calling
|
||||
/model google/gemini-2.5-pro # huge context window
|
||||
/model deepseek/deepseek-v3.2 # cost-effective coder
|
||||
```
|
||||
|
||||
The portal's own [model info page](https://portal.nousresearch.com/info) carries the same warning, so this isn't a Hermes-side opinion — it's the official guidance from Nous Research.
|
||||
|
||||
#### Setup
|
||||
|
||||
Two paths, both interactive, both browser-based:
|
||||
|
||||
**Fresh install** — one command does everything:
|
||||
[Nous Portal](https://portal.nousresearch.com) is Nous Research's unified subscription gateway and **the recommended way to run Hermes Agent**. One OAuth login covers 300+ frontier agentic models (Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, MiniMax, Grok, ...) plus the [Tool Gateway](/docs/user-guide/features/tool-gateway) (web search, image generation, TTS, browser automation) plus [Nous Chat](https://chat.nousresearch.com) — billed against your Nous subscription instead of separate per-provider accounts.
|
||||
|
||||
```bash
|
||||
hermes setup --portal
|
||||
hermes setup --portal # fresh install — OAuth + provider + gateway in one command
|
||||
hermes model # existing install — pick "Nous Portal" from the list
|
||||
hermes portal status # inspect login + routing at any time
|
||||
```
|
||||
|
||||
Opens your browser to portal.nousresearch.com, runs the OAuth flow, sets Nous as your inference provider in `config.yaml`, and turns on the Tool Gateway in the same step. After this you're ready to `hermes chat`. If you don't have a subscription yet, grab one at [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription) before running the command.
|
||||
Don't have a subscription yet? Get one at [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription).
|
||||
|
||||
**Existing install** — add the portal alongside whatever else you have configured:
|
||||
|
||||
```bash
|
||||
hermes model
|
||||
# pick "Nous Portal" from the provider list
|
||||
# browser opens, sign in, done
|
||||
```
|
||||
|
||||
This adds Nous Portal as a provider you can switch to with `/model` or `hermes model` at any time. Your existing providers (OpenRouter, Anthropic, OpenAI, etc.) stay configured — you can switch back whenever you want. To enable just specific gateway tools (e.g. web search but not image generation), use `hermes tools` and pick **Nous Subscription** per backend.
|
||||
|
||||
Either path stores a long-lived refresh token at `~/.hermes/auth.json`. The token is also written into a shared token store, so signing in on one Hermes [profile](/docs/user-guide/profiles) carries over to all of them automatically — no need to repeat the OAuth flow per profile.
|
||||
|
||||
Manage your plan, view usage, or upgrade/cancel at any time from [portal.nousresearch.com/manage-subscription](https://portal.nousresearch.com/manage-subscription).
|
||||
|
||||
#### Inspecting and managing the connection
|
||||
|
||||
```bash
|
||||
hermes portal status # login status, subscription info, gateway routing summary
|
||||
hermes model # switch the active model within the portal catalog
|
||||
hermes auth add nous # re-authenticate after a token revocation
|
||||
```
|
||||
|
||||
`/model` inside an active session works the same way — open the picker, select any model from the catalog, conversation continues uninterrupted.
|
||||
|
||||
#### Token handling
|
||||
|
||||
Hermes mints a short-lived JWT from your stored Nous refresh token on each inference call rather than reusing a long-lived API key. The token lifecycle is fully automatic — refresh, mint, retry on transient 401 — and you never see it.
|
||||
|
||||
If the portal invalidates the refresh token (password change, manual revoke, session expiry), the invalid refresh token is quarantined locally so Hermes stops replaying it and you don't see a stream of identical 401s. The next call surfaces a clear "re-authentication required" message. Run `hermes auth add nous` to log in again; the quarantine clears on the next successful login.
|
||||
**For full details:** see the dedicated [Nous Portal integration page](/docs/integrations/nous-portal) (what's in the subscription, model catalog, troubleshooting) and the step-by-step [Run Hermes Agent with Nous Portal guide](/docs/guides/run-hermes-with-nous-portal).
|
||||
|
||||
|
||||
:::info Codex Note
|
||||
|
|
|
|||
|
|
@ -647,6 +647,7 @@ const sidebars: SidebarsConfig = {
|
|||
collapsed: true,
|
||||
items: [
|
||||
'integrations/index',
|
||||
'integrations/nous-portal',
|
||||
'integrations/providers',
|
||||
'user-guide/features/mcp',
|
||||
'user-guide/features/acp',
|
||||
|
|
@ -662,6 +663,7 @@ const sidebars: SidebarsConfig = {
|
|||
label: 'Guides & Tutorials',
|
||||
collapsed: true,
|
||||
items: [
|
||||
'guides/run-hermes-with-nous-portal',
|
||||
'guides/tips',
|
||||
'guides/local-llm-on-mac',
|
||||
'guides/daily-briefing-bot',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue