Install, setup, and verify a chat
> Desktop installer or one-liner CLI — then hermes setup --portal and a real response.
Canonical: https://www.brainyxai.co.za/education/hermes/install-and-setup
Markdown: https://www.brainyxai.co.za/md/education/hermes/install-and-setup.md
Course: Hermes Agent Operator Track
Lesson: 2 of 9
Minutes: 18
Author: Brainyx AI
What you will be able to do
- Choose Desktop vs CLI install for your OS
- Run setup so a model provider is configured
- Verify the agent responds before customizing anything else
Two install lanes
macOS / Windows (recommended for most people)
Download the Hermes Desktop installer from the [Hermes site](https://hermes-agent.nousresearch.com/) and run it. You get CLI + desktop UI without hand-rolling paths.
CLI-only (Linux / macOS / WSL2 / Termux)
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
Windows native (PowerShell)
```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```
Platform matrix, Termux, Nix/NixOS, and update/uninstall paths are covered in the official [Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation) and [Platform Support](https://hermes-agent.nousresearch.com/docs/getting-started/platform-support) pages — use those if you hit an OS edge case.
The fastest path after install
Official quickstart wisdom, restated for operators:
| Goal | Do this first | Then |
| --- | --- | --- |
| Just make it work | `hermes setup` (or `hermes setup --portal`) | Run a real chat and confirm a reply |
| You already know your provider | `hermes model` | Save config, then chat |
| Bot / always-on | Finish a local chat first | Then configure the messaging gateway |
Why `hermes setup --portal`
One OAuth via Nous Portal can cover a model plus Tool Gateway tools (web search, image generation, TTS, browser). That collapses the “installed but nothing works” failure mode: model yes, tools no.
If you use OpenRouter, OpenAI, Anthropic, Google, or another OpenAI-compatible endpoint instead, follow [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models) after base setup.
Verify before you customize
A working install means:
1. The `hermes` binary is on your PATH (or Desktop launches cleanly)
2. A provider/model is selected and authenticated
3. You send a trivial prompt and get a non-error response
Only then add MCP servers, Discord bots, or custom YAML.
Troubleshooting mindset
The docs’ quickstart exists because “it installed, but it still does nothing” is common. Treat failures as a checklist:
- Provider key / OAuth expired?
- Model name wrong for that provider?
- Network / proxy blocking API?
- Looking at the wrong profile or config directory?
Deep dive: [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart).
Install lab
1. Install via Desktop or the curl/PowerShell one-liner for your OS.
2. Run hermes setup --portal (or hermes setup) until a model is configured.
3. Start a chat and ask Hermes to list the current directory with a tool — confirm tool use, not only text.
Checkpoints
- I have a verified chat response
- I know whether I’m on Portal Tool Gateway or another provider path
Verify before you customise
The most common way to lose an afternoon is to install, immediately open the config file, change six settings, and then discover nothing responds — with no idea which change caused it.
Climb the ladder instead, confirming each rung before the next:
1. The binary runs and reports its version.
2. Setup completes and a model provider is configured.
3. A trivial prompt returns a real response.
4. A prompt requiring a tool call completes.
5. Only now, change configuration — one setting at a time.
If a rung fails, you know exactly what changed since the last working state. That discipline is worth more than any configuration knowledge.
Provider credentials without regret
Setup will ask for provider credentials. Two habits prevent later pain: create a key dedicated to this agent rather than reusing one from another project, and set a spend limit on it at the provider before first use.
A dedicated key means you can revoke it without breaking anything else, and provider-side usage attribution actually tells you what this agent costs. A spend limit means a misconfigured loop costs you an alert rather than a bill.
Never paste credentials into a chat with the agent itself. They belong in the configuration or environment, and nowhere in conversation history.
Connectivity realities in South Africa
Two things bite locally. Load-shedding interrupts long-running sessions, so avoid unattended multi-step tasks without a way to resume, and keep your configuration backed up somewhere that is not only on the affected machine.
Latency to overseas model endpoints is noticeable. Slow first responses are usually network round-trip rather than a broken install — check with a simple prompt before you start debugging configuration.
Mini-FAQ
A: Desktop if you want the shortest path to a working agent. CLI if you live in a terminal, script things, or will run it on a server.
A: Only with a locally-hosted model backend. With hosted providers, it needs connectivity for every model call.
A: In order — provider credential present and valid, network reachable, and the configured model name actually available on your account.
Next lesson
Continue to [your configuration home](https://www.brainyxai.co.za/education/hermes/configuration-home).
Official reference: https://hermes-agent.nousresearch.com/docs/getting-started/installation
Course hub: https://www.brainyxai.co.za/education/hermes · Previous: https://www.brainyxai.co.za/education/hermes/what-is-hermes · Next: https://www.brainyxai.co.za/education/hermes/configuration-home
Return to the course hub, or explore Brainyx AI services to put the skill into a live system. Markdown: /md/education/hermes/install-and-setup.md
Book a consultation · joshua@brainyxai.co.za · Markdown mirrors