Setup note · 2 September 2026

One command. Then stop collecting API keys.

hermes setup --portal is the official fast path: Portal OAuth, pick a model, set Nous as the inference provider, turn on the Tool Gateway. Hermes Agent itself stays free MIT. Portal is the paid convenience layer.

Canonical docs (read these if anything here drifts): hermes-agent.nousresearch.com/docs/integrations/nous-portal. Software: github.com/NousResearch/hermes-agent · site: hermes-agent.nousresearch.com.

Install Hermes first

Hermes publishes an install script and desktop builds. From the project site:

Official install (Linux / macOS / WSL — from hermes-agent.nousresearch.com)

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Native desktop exists for macOS 12+, Windows 10/11, and Linux. This note assumes you can run the hermes CLI afterwards. If you already have Hermes, skip to the Portal command — do not reinstall for sport.

Fresh machine: the actual command

This is the whole trick

hermes setup --portal

Per the official integration doc, that single command:

1. Opens a browser to portal.nousresearch.com

   OAuth login. You need a Portal account. If you don’t have a subscription yet, the docs point you at portal.nousresearch.com/manage-subscription first, then you come back and re-run the command. A Plus CTA is at the bottom of this page, disclosed.

2. Stores a refresh token, not a pile of lab keys

   Token lands at ~/.hermes/auth.json. Hermes mints short-lived JWTs per request. The point of Portal is that you do not accumulate a .env of long-lived vendor keys for the gateway tools.

3. Lets you pick a model

   Nous as inference provider gets written into ~/.hermes/config.yaml when you pick one. You can skip and keep a current model if this is not a greenfield install.

4. Turns on the Tool Gateway

   Web, image, TTS, browser routing through Nous. Cloud terminal (Modal) stays optional. This is the part that replaces Firecrawl + FAL + browser + TTS accounts. See Plus vs OpenRouter.

5. Drops you at hermes chat

   If it doesn’t, run hermes portal info before you start editing YAML by hand.

What config should look like after

Official shape (from the same docs). Don’t cargo-cult a model slug you didn’t pick:

model:
  provider: nous
  default: anthropic/claude-sonnet-4.6   # or whatever you picked
  base_url: https://inference-api.nousresearch.com/v1

web:
  backend: nous
image_gen:
  provider: nous
tts:
  provider: nous
browser:
  cloud_provider: nous

Credentials stay in ~/.hermes/auth.json, not in config.yaml. If a category is set to nous, leftover direct keys in .env are ignored for that category — by design, so you don’t silently double-bill.

You already run OpenRouter

Do not blow away the working provider. Add Portal beside it:

hermes model
# pick "Nous Portal" from the provider list
# browser opens, sign in, done

Switch mid-session with /model. Portal becomes one provider, not a religion. Hermes is provider-agnostic on purpose: persistent memory, self-written skills, and the messaging gateway do not care which inference bill you pay.

Day-two commands worth memorizing

Headless / SSH

OAuth wants a browser; the loopback callback runs on the machine where Hermes is running. For a remote host, the official docs tell you to use the same ssh -L patterns as any other OAuth provider. Don’t paste refresh tokens around as a shortcut.

A note on Hermes 4 (the model, not the agent)

Portal lists Hermes-4-70B / 405B at discounted rates. Official guidance: they are chat/reasoning models, not recommended inside Hermes Agent’s tool-calling loop. For agent work, pick a frontier agentic model from the catalog (the docs’ examples include Sonnet 4.6, GPT-5.5 Pro, Gemini 3 Pro, DeepSeek V4 Pro). That warning is Nous’s, not ours.

If bills hit the wrong account

hermes portal info will tell you if the local config drifted back to OpenRouter. Run hermes model, pick Nous Portal, send the next request. Mixing providers is fine; being confused about which one just ran is not.