Neura Market Logo

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.

Access & Credentialsintermediate11 min read
Hermes Agent Documentation
Nous Portal for Hermes Agent: Unified Login for Models and Tool Gateway

Nous Portal Reference

Nous Portal is Nous Research's unified subscription gateway for Hermes Agent. It provides a single OAuth login that replaces separate accounts, API keys, and billing for multiple model labs and tool providers. This document covers every capability, procedure, parameter, constraint, and failure mode.

When to Use Nous Portal

Use Nous Portal in these situations:

  • You want to avoid managing separate accounts, API keys, and billing for multiple model labs and tool providers.
  • You are setting up Hermes Agent for the first time and want the fastest path to a working agent.
  • You are running Hermes Agent on Windows, where per-tool API key setup is high-friction.
  • You want a single bill for 300+ frontier models and five tool backends.
  • You need to switch models mid-session without new credentials or top-ups.
  • You want to mix gateway tools with your own backends on a per-tool basis.
  • You need cross-platform parity between Windows, macOS, and Linux without manual backend configuration.

Capabilities

Single OAuth Login

A single OAuth login replaces separate accounts for these model labs: Anthropic, OpenAI, Google, DeepSeek, Qwen, Kimi, GLM, MiniMax, xAI, NVIDIA, Tencent, Xiaomi, StepFun, and Hermes. It also replaces accounts for these tool backends: Firecrawl, FAL, OpenAI TTS, Browser Use, and Modal.

Automatic Backend Routing

Nous Portal routes each model to the best backend automatically. The backend may be OpenRouter, a proprietary provider, or a secondary provider. Billing always goes through your Nous subscription. Routing is per-model and not always through OpenRouter. OpenRouter-specific request extensions, such as provider routing preferences, session_id sticky routing, and top-level cache_control, may be ignored depending on the backend.

Mid-Session Model Switching

You can switch models mid-session with the /model command without needing new credentials or top-ups. The command accepts a model slug directly, for example /model anthropic/claude-sonnet-4.6, or opens a picker with arrow keys if no slug is provided.

Tool Gateway

The Tool Gateway routes tool calls through Nous-managed infrastructure:

  • Web search and extract: Firecrawl
  • Image generation: FAL (9 models)
  • Text-to-speech: OpenAI TTS
  • Cloud browser automation: Browser Use
  • Cloud terminal sandbox: Modal (optional add-on)

Per-Tool Opt-In

You can mix gateway tools with your own backends on a per-tool basis. For each tool, you select either "Nous Subscription" for the gateway or your own backend (for example, "Browserbase"). If "Nous Subscription" is selected before authentication, Hermes runs Portal login inline without changing the inference provider or other tools.

No Long-Lived API Keys

No long-lived API keys are stored in dotfiles. Only a refresh token is stored at ~/.hermes/auth.json. Short-lived JWTs are minted per request. The refresh token is shared across all Hermes profiles automatically via the shared token store.

Cross-Platform Parity

Windows users get the same experience as macOS and Linux users without manual backend configuration.

Hermes 4 Models

Hermes 4 models (Hermes-4-70B, Hermes-4-405B) are available at discounted rates for chat and reasoning, but they are not recommended for agent tool-calling loops. Use them for research workflows or via the subscription proxy from other tooling.

Subscription Management

Subscription management is available via the web at portal.nousresearch.com/manage-subscription or the CLI shortcut hermes portal open.

Token Lifecycle

The token lifecycle is fully automatic: refresh, mint, and retry on transient 401 errors. Invalid refresh tokens are quarantined locally with a clear re-authentication message. The quarantine clears automatically when new credentials are obtained.

Shared Refresh Token

The Portal refresh token is shared across all Hermes profiles automatically via the shared token store. Sign in once on any profile and the token is available to all profiles.

Prerequisites

Before using Nous Portal, you must have:

  • An active subscription at portal.nousresearch.com/manage-subscription
  • Hermes Agent installed
  • For remote or headless setup: the ability to forward ports via SSH

Procedures

Fresh Install Setup

  1. Ensure you have a subscription at portal.nousresearch.com/manage-subscription. Sign up if you do not have one.
  2. Run this command: 
    hermes setup --portal
  3. Your browser opens to portal.nousresearch.com for OAuth login.
  4. The refresh token is stored at ~/.hermes/auth.json.
  5. Pick a Nous model from the curated list, or skip to keep your current model.
  6. If you pick a model, Nous is set as the inference provider in ~/.hermes/config.yaml.
  7. The Tool Gateway is turned on for web, image, TTS, and browser routing.
  8. The terminal is ready for hermes chat.

Add Portal Alongside Existing Providers

  1. Run this command: 
    hermes model
  2. Select "Nous Portal" from the provider list.
  3. Your browser opens for OAuth sign-in.
  4. Existing providers remain configured. Switch with /model mid-session or hermes model between sessions.

Headless, SSH, or Remote Setup

Use OAuth over SSH patterns, such as ssh -L port forwarding, as you would for any OAuth-based provider. OAuth requires a browser, so port forwarding is necessary for remote hosts.

Profile Setup

Sign in once on any profile. The refresh token is shared automatically across all profiles via the shared token store.

Inspecting Portal Status

  • Run hermes portal (alias for hermes auth add nous --type oauth). This logs in, picks a model, sets the provider, and offers Tool Gateway opt-in.
  • Run hermes portal info or hermes portal status. This shows login status, subscription info, and model and gateway routing.
  • Run hermes portal tools. This shows a detailed Tool Gateway catalog with per-tool routing.
  • Run hermes portal open. This opens the subscription management page in your browser.

Switching Models

  • Inside a session: use /model <slug>, for example /model anthropic/claude-sonnet-4.6, or /model to open a picker with arrow keys.
  • Outside a session: use hermes model (full setup wizard).

Mixing Gateway with Own Backends

  1. Run this command: 
    hermes tools
  2. For each tool, select the backend: "Nous Subscription" for the gateway, or your own backend (for example, "Browserbase").
  3. If "Nous Subscription" is selected before authentication, Hermes runs Portal login inline without changing the inference provider or other tools.

Subscription Management

  • Web: portal.nousresearch.com/manage-subscription
  • CLI shortcut: hermes portal open

Re-authentication After Token Invalidation

  1. Run this command: 
    hermes auth add nous
  2. The next request uses new credentials. The quarantine on the old token clears automatically.

Parameters

--portal

  • Meaning: Flag for hermes setup to run full Portal OAuth setup.
  • Required: Yes for the fresh install setup command.

model provider

  • Meaning: Inference provider set in config.yaml (nous after Portal setup).
  • Required: Yes for routing through Portal.

model default

  • Meaning: Default model slug in config.yaml (for example, anthropic/claude-sonnet-4.6).
  • Required: Optional. Set during setup or via /model.

base_url

  • Meaning: Inference API base URL (https://inference-api.nousresearch.com/v1).
  • Required: Yes for Portal inference.

web backend

  • Meaning: Backend for web search and extract (firecrawl when using gateway).
  • Required: Yes if the web tool is enabled.

web use_gateway

  • Meaning: Boolean flag to route web through the Tool Gateway.
  • Required: Yes if using the gateway for web.

image_gen use_gateway

  • Meaning: Boolean flag to route image generation through the Tool Gateway.
  • Required: Yes if using the gateway for images.

tts provider

  • Meaning: TTS provider (openai when using gateway).
  • Required: Yes if TTS is enabled.

tts use_gateway

  • Meaning: Boolean flag to route TTS through the Tool Gateway.
  • Required: Yes if using the gateway for TTS.

browser cloud_provider

  • Meaning: Cloud browser provider (browser-use when using gateway).
  • Required: Yes if browser automation is enabled.

browser use_gateway

  • Meaning: Boolean flag to route browser automation through the Tool Gateway.
  • Required: Yes if using the gateway for browser.

Constraints and Caveats

  • Routing is per-model and not always through OpenRouter. OpenRouter-specific request extensions, such as provider routing preferences, session_id sticky routing, and top-level cache_control, may be ignored depending on the backend.
  • Hermes 4 models (Hermes-4-70B, Hermes-4-405B) are not recommended for use inside Hermes Agent. Use them for research workflows or via the subscription proxy from other tooling.
  • OAuth requires a browser. For remote hosts, use ssh -L port forwarding.
  • The refresh token is stored at ~/.hermes/auth.json, not in config.yaml.
  • The cloud terminal sandbox (Modal) is an optional add-on.
  • If a model is missing from /model, try the OpenRouter-style slug directly. If it is still missing, open an issue.
  • Bills not appearing on your Portal account may indicate local config drift. Check hermes portal info for the provider.

Failure Modes

hermes portal info Shows "Not Logged In"

The OAuth flow was not completed, or the refresh token was wiped. Run hermes portal or hermes model and re-select Nous Portal.

"Re-authentication Required" Message Mid-Session

The refresh token was invalidated due to a password change, manual revoke, or session expiry. Run hermes auth add nous.

Bills Not Appearing on Portal Account

Local config drifted to a different provider. Run hermes model and pick Nous Portal.

Examples

Fresh Install Setup

hermes setup --portal

Add Portal Alongside Existing Providers

hermes model

Inspect Portal Status

hermes portal info

View Tool Gateway Catalog

hermes portal tools

Open Subscription Management Page

hermes portal open

Switch Model Mid-Session

/model anthropic/claude-sonnet-4.6

Mix Gateway with Own Backends

hermes tools

Re-authenticate After Token Invalidation

hermes auth add nous

Sources & References

This page was researched from 1 independent source, combined and verified for completeness.

Newsletter

The #1 AI Newsletter

The most important ai updates, guides, and fixes — one weekly email.

No spam, unsubscribe anytime. Privacy policy

Other Hermes Agent integrations

Hermes Agent Credential Pools: Rotating and Sharing API KeysRotate and share API keys across providers with Hermes Agent credential pools.Hermes Agent Subscription Proxy: Use Your Portal Subscription with Any OpenAI AppRoute OpenAI-compatible app requests through your Hermes-managed provider subscription.Hermes Blockchain Oracle: On-Chain Solana Data for Hermes AgentConnects Hermes Agent to Solana blockchain for natural language on-chain queries.Hermes Bort: BORT Agent Integration for Hermes AgentConnects Hermes Agent to BORT (BAP-578) agent NFTs on BSC mainnet.Hermes Agent Provider Routing: Choosing Which Model Handles Each RequestControl which AI provider handles each request in Hermes Agent via OpenRouter or Nous Portal.Hermes Agent Browser Automation: Setup, Tools, and ConfigurationConnects Hermes Agent to cloud and local browsers for automated web interaction.