Free tier and signing in

Not on yet

The free tier is being rolled out. Until it is on for everyone, nothing on this page happens unless the process was started with HERMES_GUEST_ONBOARDING=1 in its environment; without it a fresh install behaves exactly as before (the provider picker on first run). This note goes away when the rollout completes.

A fresh Hermes install works before you paste an API key or sign in anywhere. When Hermes starts it sets up the Nous free tier (a few seconds, shown as "Setting up free inference…") and answers on the nous/welcome model. Nothing to configure, no wizard to click through. hermes setup is still there when you want it; it is never forced.

What you get out of the box

	Free tier	After signing in
Inference	nous/welcome (one model)	Full Nous Portal catalog
Connectors (Gmail, Linear, Notion, ...)	Yes	Yes
Paid tools through the Tool Gateway (web search, image generation, TTS, cloud browser)	No	Yes, billed to your subscription
Credits or a balance	None	Yes

"Connectors" are the third-party accounts you link on the Nous portal so the agent can act in them. They work on the free tier without any sign-in.

Background work (conversation compaction, chat titles, image understanding, and similar) runs on nous/welcome too.

While the free tier carries inference, the banner and hermes auth status read Nous · free tier · nous/welcome, and hermes model lists a Nous · free tier row with that single model. Asking for another model on the free tier prints a pointer instead of switching silently:

gpt-5 needs a Nous account or an API key. Use /login to sign in, or /model to pick another provider.

Calling a paid tool says This needs a Nous account. Use /login to sign in. inside a chat (and names hermes auth upgrade in the terminal); the turn continues without it.

If model.default in config.yaml names something other than nous/welcome while the free tier is doing inference, Hermes uses nous/welcome anyway and says so in one line. The free tier serves exactly one model.

Using your own API key alongside it

The free tier is the last resort, never a preference. Any provider you configure wins:

You have	Inference runs on	Connectors
Nothing	Nous free tier (nous/welcome)	Free tier
An API key in .env (OpenRouter, OpenAI, Anthropic, ...)	Your key	Free tier
model.provider set in config.yaml	That provider	Free tier
A Nous Portal sign-in	Nous Portal	Your account

On an install that already has a provider, Hermes still sets the free tier up once at start so connectors have something to authenticate with; your provider keeps doing inference. A one-time notice says so:

Free Nous inference and connectors are now available. /model to try them, /login to sign in.

You can pick the free tier explicitly from hermes model (or /model) like any other provider.

Signing in from a chat or terminal

From a chat

Run /login in a Hermes DM on Telegram, Discord, or another supported messaging platform (on Slack use /hermes login), or in a CLI chat session. It must be a paired direct message: elsewhere Hermes replies Sign in from a direct message with Hermes. Broadcast-shaped platforms such as ntfy are refused for the same reason.

The DM gets an acknowledgement, followed by three messages: the consent link, the sign-in code on its own line, then Do not share this code. Waiting for sign-in, up to N minutes. You can keep chatting while Hermes waits, and the result is pushed into the same DM. Running /login again replaces the first code. Live sessions still on nous/welcome move to the settled model on their next message. In the Ink TUI the code appears but the confirmation does not; check /status.

One account per install

/login binds this whole Hermes install to the account that approves the code: its inference, its connectors, every chat it serves. On a gateway several people can DM, set allow_admin_from for the platform (see the slash-command access guide) so only an operator can run it.

From a terminal

hermes auth upgrade

1. Hermes prints a URL and a short code, and opens the browser unless you pass --no-browser or you are in an SSH session. Never share the code.
2. Sign in to Nous Portal in the browser and confirm.
3. Back in the terminal: Signed in as you@example.com. If your default model was nous/welcome, a second line names the model your account now uses, for example Default model is now upstage/solar-pro4:free.

Inference moves to your account's model catalog, paid tools unlock, and hermes auth status shows your account instead of the free-tier line. nous/welcome stays with the free tier: an account that was using it lands on the recommended model for its plan (the same one a fresh hermes model pick would suggest), and a default model you chose yourself is left alone. If no recommendation is available at that moment, no default is set and Hermes tells you to run hermes model.

/login in a chat, or hermes auth upgrade in a terminal, is offered wherever the free tier is present, including installs that run inference on their own API key. Signing in still unlocks paid tools for those installs.

Plain login starts fresh

hermes auth add nous --type oauth also signs you in, but it replaces the free tier outright and does not carry your connectors over. Use /login, or hermes auth upgrade in a terminal, when you have connectors you want to keep.

On Hermes Desktop

The desktop app runs on the same free tier as the CLI and shows it in four places:

Where	What you see
First launch	A ready screen: "Hermes is ready." with the default model nous/welcome, a Free tier badge, and Begin. "Sign in with a Nous account instead" and "Other providers" sit under it. The screen shows once.
First launch with your own API key already present	A one-time strip above the composer: "Free Nous inference and connectors are now available." with Open model picker, Sign in and Dismiss.
Status bar	A chip "Nous · free tier · nous/welcome" with a Sign in badge while the free tier carries inference. You can hide it from the bar's right-click menu.
Settings › Billing	"You're on the Nous free tier" with one Sign in button; the summary reads Plan "Free tier", Model nous/welcome, Connectors "Included". There is no balance and nothing to pay, so no payment or usage sections appear.

Signing in from any of those places opens one dialog. It shows a code and a link; open the link (or the browser the app opened), confirm in the portal, and the dialog ends with "Signed in as you@example.com." and the default model your account now uses. A sign-in you reject in the browser, a code that timed out, or a code replaced by a newer one each show their own message and leave you on the free tier. The model picker lists the free tier as one row, "Nous · free tier", with the single model nous/welcome; there is no sign-in action inside the picker.

The desktop reads all of this from the same local state the CLI writes. The ready screen and the strip are keyed on the same one-time flag the CLI notice uses, so seeing one on the CLI means you will not see it again on the desktop for that free-tier identity, and the other way round.

Turning the free tier off

hermes config set nous.guest false

nous.guest is a normal config.yaml setting (default true), not an environment variable. With it off:

	nous.guest: true (default)	nous.guest: false
Free inference on nous/welcome	Available	Off
Connectors without sign-in	Available	Off
Free-tier row in hermes model	Shown	Hidden
Fresh install with nothing configured	Chats immediately	Offered hermes setup
Signing in with a Nous account	Works	Works

Nothing else changes. A signed-in Nous account, your own API keys, and every other provider work exactly as before. Set it back to true and the free tier returns on the next command that needs it.

What hermes logout does

Situation	Result
Only the free tier is present	Nothing is cleared. Hermes prints: You're not signed in. Free inference and connectors are always on. Run hermes auth to sign in with a Nous account.
Signed in with a Nous account	The sign-in is removed from this profile and from the shared store, so no other profile on this machine picks it back up. With nous.guest: true the install returns to the free tier at its next start.
Another provider is active	Unchanged behaviour: that provider's stored credential is cleared.

There is no command to reset or recreate the free tier. It is created once and looks after itself.

Troubleshooting

Symptom	What it means	What to do
First command prints It looks like Hermes isn't configured yet and offers hermes setup	The free tier could not be set up within a few seconds: you are offline, or the free tier is not open on the portal Hermes is pointed at, or it is rate limited.	Come back online and run the command again, or run hermes setup and add a provider of your own. Nothing is left half-configured.
Nous free tier is not open on this portal.	The portal Hermes is pointed at is not offering the free tier right now. If you set HERMES_PORTAL_BASE_URL, that portal may not have it at all.	Sign in with an account, unset a portal override you no longer need, or add your own key with hermes setup.
Nous free tier is rate limited; try again shortly.	The portal is throttling new free-tier setups at the moment.	Wait a few minutes and retry, or add your own key with hermes setup.
This needs a Nous account.	You called a paid Tool Gateway tool on the free tier.	/login in a chat, hermes auth upgrade in a terminal, or configure that tool with your own key in hermes tools.
Model picker shows only nous/welcome under Nous	Expected on the free tier.	Sign in for the full catalog, or add an API key for another provider.
The free tier stopped working after two weeks away	The free-tier identity expired (see below) and is replaced at the next start, or the next time a turn or connector finds it retired.	Nothing; start Hermes again. Connectors linked before the gap need to be linked again unless you had signed in.

Privacy

To make the free tier work, Hermes creates an identity on the Nous portal the first time it needs one and stores the credential in your Hermes directory, shared across the profiles under that directory. That identity holds no email address, no name, and no other personal data; it exists so inference and connector calls can be authenticated and rate limited. It expires after 14 days without use, at which point Hermes transparently creates a new one the next time you run a command. Signing in (/login, or hermes auth upgrade in a terminal) moves what that identity holds (your linked connectors) into your account. Turning the free tier off with nous.guest: false means no identity is created or used at all.