Nous Portal for Hermes Agent: Unified Login for Models and Tool Gateway
Connect Nous Portal to Hermes Agent for unified model and tool access via OAuth.
The Nous Portal integration for Hermes Agent connects Nous Research's unified subscription gateway to the Hermes agent runtime, allowing a single OAuth login to replace separate accounts, API keys, and billing relationships across multiple model labs, search APIs, image generators, and browser providers. Once wired up, an agent can access over 300 frontier models from providers like Anthropic, OpenAI, Google, DeepSeek, and others through one bill, and route tool calls for web search, image generation, text-to-speech, and browser automation through Nous-managed infrastructure without managing individual backend credentials.
What It Does
- Provides a single OAuth-based login that replaces separate accounts for every model lab, search API, image generator, and browser provider.
- Routes inference calls through a curated catalog of 300+ frontier models billed against one Nous subscription instead of per-lab credit balances.
- Unlocks the Nous Tool Gateway, which routes Hermes Agent's tool calls through Nous-managed infrastructure for five backends: web search and extract (Firecrawl), image generation (FAL), text-to-speech (OpenAI TTS), cloud browser automation (Browser Use), and cloud terminal sandbox (Modal).
- Eliminates the need to store multiple long-lived API keys in
.envfiles by using a single OAuth refresh token stored at~/.hermes/auth.json. - Provides cross-platform parity, especially smoothing the setup experience on Windows where configuring per-tool API keys is the highest-friction part.
- Allows mixing the Tool Gateway with existing user-managed backends on a per-tool basis.
- Supports model switching mid-session via the
/modelcommand without new credentials or top-ups. - Shares the Portal refresh token automatically across all Hermes profiles via a shared token store.
According to the official documentation, 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. The model families include Anthropic (Claude Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5), OpenAI (GPT-5.5, GPT-5.5 Pro, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.3 Codex), Google (Gemini 3 Pro Preview, Gemini 3 Flash Preview, Gemini 3.1 Pro Preview, Gemini 3.1 Flash Lite Preview), DeepSeek (DeepSeek V4 Pro), Qwen (Qwen3.7-Max, Qwen3.6-35B-A3B), Kimi/Moonshot (Kimi K2.6), GLM/Zhipu (GLM-5.1), MiniMax (MiniMax M2.7), xAI (Grok 4.3), NVIDIA (Nemotron-3 Super 120B-A12B), Tencent (Hunyuan 3 Preview), Xiaomi (MiMo V2.5 Pro), StepFun (Step 3.5 Flash), and Hermes (Hermes-4-70B, Hermes-4-405B for chat), plus 280+ additional models described as the full agentic frontier. Routing happens through OpenRouter under the hood, so model availability and failover behavior matches what you would get with an OpenRouter key, but billed against your Nous subscription instead.
The Tool Gateway provides five backends under one login. Web search and extract uses Firecracker for agent-grade search and full-page extraction without needing a Firecracker API key or rate limit babysitting. Image generation uses FAL with 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, and Qwen Image. Text-to-speech uses OpenAI TTS for high-quality TTS without a separate OpenAI key, enabling voice mode across messaging platforms. Cloud browser automation uses Browser Use for headless Chromium sessions supporting browser_navigate, browser_click, browser_type, and browser_vision without needing a Browserbase account. Cloud terminal sandbox uses Modal for serverless terminal sandboxes for code execution as an optional add-on.
Without the gateway, hooking each of those up would require a Firecracker 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. The documentation notes that you can also enable just specific gateway tools, for example web search but not image generation, by mixing the gateway with your own backends.
Because everything routes through one OAuth-authenticated Portal session, you do not 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. The documentation highlights that native Windows makes per-tool API key setup its rough edge installing a Firecracker 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.
Setup
Fresh Install One Command
The fastest path to get started is a single command:
hermes setup --portal
This command runs the full setup in one shot. It opens your browser to portal.nousresearch.com for OAuth login. It stores the refresh token at ~/.hermes/auth.json. It lets you pick a Nous model from the curated list or skip to keep your current one. It sets Nous as your inference provider in ~/.hermes/config.yaml when you pick a model. It turns on the Tool Gateway for web, image, TTS, and browser routing. It returns you to your terminal ready to hermes chat.
If you do not have a subscription yet, sign up at portal.nousresearch.com/manage-subscription first, then come back and run the command above.
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, use the model picker:
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, the documentation references OAuth over SSH / Remote Hosts and states that the same patterns work for the Portal as for any other OAuth-based provider, specifically ssh -L port forwarding.
Profile Setup
If you use Hermes 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 with no need to repeat the OAuth flow per profile.
Configuration Reference
After hermes setup --portal, ~/.hermes/config.yaml will look like:
model:
provider: nous
default: anthropic/claude-sonnet-4.6 # or whatever model you picked
base_url: https://inference-api.nousresearch.com/v1
The Tool Gateway settings live under their respective tool sections:
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.
CLI Commands for Day-to-Day Use
The documentation provides several CLI commands for inspecting and managing the Portal:
hermes portallogs in to Nous Portal and sets it up as a one-shot onboarding command. It is the human-readable alias forhermes auth add nous --type oauth. It logs you in, lets you pick a Nous model, sets Nous as your inference provider, and offers the Tool Gateway opt-in. It is identical tohermes setup --portaland the same Nous flow as the first-time quick setup.hermes portal infoshows login status, subscription info, model and gateway routing. The documentation provides an example output:
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
hermes portal statusis an alias forportal info.hermes portal toolsshows the detailed Tool Gateway catalog with per-tool routing.hermes portal openopens the subscription management page in your default browser.
Switching Models
Inside a session, use the /model command with a specific model slug:
/model anthropic/claude-sonnet-4.6
/model openai/gpt-5.5-pro
/model google/gemini-3-pro-preview
Or open the interactive picker:
/model
# arrow keys, enter to select
Outside a session, use the full setup wizard:
hermes model
Mixing the Gateway with Your Own Backends
If you already have a Browserbase account and want to keep using it while routing web search and image generation through Nous, use hermes tools to pick backends per tool:
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. The managed backends show up in hermes tools whether or not you are logged into Nous Portal. If you pick "Nous Subscription" before authenticating, Hermes runs the Portal login inline. It will not change your inference provider or touch your other tools.
Subscription Management
Manage your plan, view usage, or upgrade/cancel at any time via the web at portal.nousresearch.com/manage-subscription or via the CLI shortcut hermes portal open, which opens the same page in your default browser.
How It Works
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 due to a password change, manual revoke, or session expiry, the invalid refresh token is quarantined locally so Hermes stops replaying it and you do not 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.
Routing
Routing happens through OpenRouter under the hood. Model availability and failover behavior matches what you would get with an OpenRouter key, but billed against your Nous subscription instead. The documentation states that you can switch between Claude Sonnet 4.6 for code and Gemini 3 Pro for long context with /model mid-session with no new credentials, no top-ups, and no surprise zero-balance errors.
Requirements and Limitations
Hermes 4 Models Not Recommended for Agent Work
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. However, the official documentation explicitly states they are not recommended for use inside Hermes Agent. Hermes 4 is tuned for chat and reasoning, not the rapid-fire tool-calling loop the agent relies on. The documentation advises using them for research workflows or via the subscription proxy from other tooling, but for agent work, picking a frontier agentic model from the catalog instead. The recommended models are:
/model anthropic/claude-sonnet-4.6 # best general-purpose agentic model
/model openai/gpt-5.5-pro # strong reasoning + tool calling
/model google/gemini-3-pro-preview # huge context window
/model deepseek/deepseek-v4-pro # cost-effective coder
The documentation notes that the Portal's own model info page carries the same warning, so this is not a Hermes-side opinion but official guidance from Nous Research.
Model Availability
The Portal proxies through OpenRouter, so any model that OpenRouter supports is generally available. If a specific model is not appearing in /model, the documentation suggests trying the OpenRouter-style slug directly:
/model anthropic/claude-opus-4.6
If a model is genuinely missing, the documentation advises opening an issue, stating that gaps usually mean a routing config that can be updated.
OAuth Browser Requirement
OAuth needs a browser, but the loopback callback runs on the machine where Hermes is running. For remote hosts, SSH port forwarding (ssh -L) is required.
Cloud Terminal as Optional Add-On
The cloud terminal sandbox via Modal is listed as an optional add-on, not automatically enabled.
Troubleshooting
hermes portal info shows "not logged in"
You have not completed the OAuth flow, or your refresh token was wiped. Run:
hermes portal
or use hermes model and re-select Nous Portal.
Got a "re-authentication required" message mid-session
Your Portal refresh token was invalidated due to a 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 does not expose
The Portal proxies through OpenRouter, so any model that OpenRouter supports is generally available. If a specific model is not appearing in /model, try the OpenRouter-style slug directly:
/model anthropic/claude-opus-4.6
If a model is genuinely missing, open an issue. The documentation states that the Portal's catalog is surfaced to Hermes and gaps usually mean a routing config that can be updated.
Bills not appearing on my Portal account
Check hermes portal info first. If it shows you are using a different provider, for example 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
The documentation references several related resources: Tool Gateway for full details on every gateway tool, per-tool config, and pricing; Subscription proxy for using your Portal subscription from non-Hermes tools such as other agents, scripts, or third-party clients; Voice mode for voice conversations using the Portal's OpenAI TTS; AI Providers for the full provider catalog to compare alternatives; OAuth over SSH for login from remote hosts or browser-only environments; and Profiles for multiple Hermes configurations sharing one Portal login.
Sources & References
This page was researched from 1 independent source, combined and verified for completeness.
- 1.Nous PortalOfficial documentation · primary source
The #1 AI Newsletter
The most important ai updates, guides, and fixes — one weekly email.
No spam, unsubscribe anytime. Privacy policy