- **`version`** — integer schema version. Future schemas bump this; Hermes refuses manifests with versions it doesn't understand and falls back to the hardcoded snapshot.
- **`metadata`** — free-form dict at the manifest, provider, and model level. Any keys. Hermes ignores unknown fields, so you can annotate entries (`"tier": "paid"`, `"tags": [...]`, etc.) without coordinating a schema change.
- **`description`** — OpenRouter-only. Drives picker badge text (`"recommended"`, `"free"`, `"default"`, or empty). Nous Portal doesn't use this — free-tier gating is determined live from the Portal's pricing endpoint.
- **`description`** — OpenRouter-only. Drives picker badge text (`"recommended"`, `"free"`, `"default"`, or empty). Nous Portal doesn't use this.
- **`default`** — exactly one entry per provider may carry `"default": true`. That model is the **silent default**: what Hermes lands on when the user never selected a model (GUI onboarding confirm card, `provider` configured with no `model`, empty `model.default`). Read cache-only at runtime (`get_default_model_from_cache`) so hot resolution paths never hit the network; when no cached manifest exists, Hermes falls back to the in-repo `PREFERRED_SILENT_DEFAULT_MODEL` constant, which must match the labeled entry. This lets maintainers rotate the silent default without shipping a release. It is deliberately a capable low-cost model, never the priciest flagship.
- **Pricing and context length** are NOT in the manifest. Those come from live provider APIs (`/v1/models` endpoints, models.dev) at fetch time.
@@ -133,7 +133,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
| `/usage` | Show token usage, cost breakdown, session duration, and — when available from the active provider — an **Account limits** section with remaining quota / credits / plan usage pulled live from the provider's API. |
| `/topup` | Show your Nous balance and manage billing on the portal (replaces the old `/credits` and `/billing` commands). |
| `/subscription` (alias: `/upgrade`) | **CLI only.** View your Nous plan and change it in the browser. |
| `/login` | Sign in with a Nous account. Runs off-turn: the consent link and code arrive in the session, and the sign-in settles when you approve it in the browser. See [Nous free tier](/user-guide/free-tier). |
| `/login` | Sign in with a Nous account. Runs off-turn: the consent link and code arrive in the session, and the sign-in settles when you approve it in the browser. |
| `/insights` | Show usage insights and analytics (last 30 days) |
| `/update` | Update Hermes Agent to the latest version. |
| `/platforms` (alias: `/gateway`) | Show gateway/messaging platform status (CLI-only summary view). |
@@ -258,7 +258,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
| `/sessions [all] [search <query>]` | List previous sessions for this chat; the active session appears with a `(current)` marker. `/sessions search <query>` filters by title/id match (most recently active first); `/sessions all` lists across origins (admin only — non-admins get a notice and the chat-scoped list). |
| `/usage` | Show token usage, estimated cost breakdown (input/output), context window state, session duration, and — when available from the active provider — an **Account limits** section with remaining quota / credits pulled live from the provider's API. |
| `/topup` | Show your Nous balance and manage billing on the portal. |
| `/login` | Sign in with a Nous account. **Paired direct messages only** — in a group, channel, or broadcast-shaped platform Hermes refuses. On Slack use `/hermes login`. See [Nous free tier](/user-guide/free-tier). |
| `/login` | Sign in with a Nous account. **Paired direct messages only** — in a group, channel, or broadcast-shaped platform Hermes refuses. On Slack use `/hermes login`. |
| `/whoami` | Show your slash command access level (admin / user). |
| `/insights [days]` | Show usage analytics. |
| `/reasoning [level\|show\|hide\|full\|clamp] [--global]` | Change reasoning effort (levels up to `max` / `ultra`) or toggle reasoning display (`full` / `clamp` included). `--global` persists to config. |
@@ -80,7 +80,7 @@ Tools marked "active via Nous subscription" are going through the gateway. Anyth
## Eligibility
The Tool Gateway is a **paid-subscription** feature. Free-tier Nous accounts can use Portal for inference but don't include managed tools — [upgrade your plan](https://portal.nousresearch.com/manage-subscription) to unlock the gateway.
The Tool Gateway is a **paid-subscription** feature. [Upgrade your plan](https://portal.nousresearch.com/manage-subscription) to unlock the gateway.
Some accounts are also entitled to a **free tool pool** — a small managed-tool allowance that covers gateway tool calls without a paid subscription. When a free pool is available, the gateway surfaces it and shows a setup prompt on first use, so you can opt in and start using managed tools right away.
description: "What Hermes gives you before you add a key or sign in, how the free tier coexists with your own API key, how to sign in, and how to turn it off."
---
# Free tier and signing in
:::note 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 |
| Paid tools through the [Tool Gateway](/user-guide/features/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:
```text
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:
| 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:
```text
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`.
:::warning 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](/reference/slash-commands)) so only an operator
can run it.
:::
### From a terminal
```bash
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.
:::note 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
```bash
hermes config set nous.guest false
```
`nous.guest` is a normal `config.yaml` setting (default `true`), not an environment variable.
| 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.
"note":"Free-tier gating is determined live via Portal pricing (partition_nous_models_by_tier), not this manifest. The entry labeled \"default\": true is the model Hermes silently lands on when the user never picked one."
"note":"The entry labeled \"default\": true is the model Hermes silently lands on when the user never picked one."
},
"models":[
{
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Siddharth Balyan
GitHub