mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-06-08 08:11:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

docs: dedicated Nous Portal integration page and setup guide (#31296)

Browse source 
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 2026-05-23 21:07:58 -07:00 • committed by GitHub
parent 2b10024ee8
commit 2666009ccc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 549 additions and 73 deletions
Download patch file Download diff file Expand all files Collapse all files

79
website/docs/integrations/providers.md
View file

@ -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