Install Hermes Agent and Run Your First Task

The shortest useful Hermes Agent setup ends with a real model response, not merely a successful installer.

Use the macOS or Windows installer when you want the Desktop app; use the shell installer for a CLI-only setup.
Choose a provider and model with hermes setup or hermes model.
The diagnostic example checks the CLI, configuration presence, and secret-file permissions without reading credential values.
hermes -z returns only the final response for scripted first-run checks.

1. Choose an installation path

The official Desktop installer is the simplest option when you want both the desktop and command-line applications on macOS or Windows. The CLI installer is enough for terminal-only use on Linux, macOS, or WSL2. It manages runtime dependencies such as uv, Python, and Node.js, so you do not need to prepare a separate Python environment first.

Run this on Linux, macOS, or WSL2:

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

Use native PowerShell on Windows:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Open a new shell or reload its configuration after installation. If the shell cannot find hermes, check that ~/.local/bin is on PATH.

2. Select a provider and model

Start with the guided setup on a fresh installation:

hermes setup

If you already know which provider to use, or only need to change the model, open the model picker instead:

hermes model

Ordinary settings and secrets have different homes. Keep normal settings in config.yaml; keep API keys, tokens, and passwords in .env or a supported Hermes credential store. Do not print either file just to check that setup worked.

3. Check the installation without exposing values

The diagnostic example uses only the Python standard library. Run it from the repository root:

bash examples/chapter-01-install-first-run/hermes-preflight.sh

Add --doctor to include hermes doctor. The wrapper suppresses the doctor’s raw output and reports only its exit code.

bash examples/chapter-01-install-first-run/hermes-preflight.sh --doctor

A healthy installation produces this shape of output. The version will vary as Hermes is updated.

Hermes preflight: PASS
version: 0.21.1
required commands: chat, doctor, model, setup
config present: yes
secret file present: yes
secret file permissions: private
doctor exit code: 0

secret file present: no is not necessarily an error because an OAuth-only setup may not need .env. A missing config, an unavailable required command, or a nonzero doctor result fails the check.

4. Understand the diagnostic boundary

The report contains only:

the semantic version;
availability of chat, doctor, model, and setup;
whether the config and secret files exist;
whether group or other users can read the secret file;
the optional doctor exit code.

It does not print file paths, configuration values, environment variables, API keys, OAuth tokens, or auth.json. It also avoids hermes doctor --fix, so the check does not change the installation.

Add --json when another program needs to consume the result:

bash examples/chapter-01-install-first-run/hermes-preflight.sh --doctor --json

That output is enough for CI to inspect status and exit codes. It is not a substitute for a credential audit.

5. Run the first task

After setup, use a short prompt with an unambiguous expected response:

hermes -z "Reply with exactly: Hermes is ready"

The -z option is the scripted one-shot mode. It prints the final response as plain text without a banner, spinner, tool previews, or a session line.

Hermes is ready

This command calls a real model. It needs working provider authentication and an available model, and it may incur provider charges. Start hermes without arguments when you want an interactive session:

hermes

6. Test the example

The tests replace the real CLI with temporary fakes, so they do not need provider credentials. They cover secret and path leakage, fail-closed behavior when required commands are missing, and summarized doctor failures.

python3 -m unittest discover -s examples/chapter-01-install-first-run/tests -v
bash tests/test_preflight.sh

Neither command contacts a model provider.

7. Fix common first-run failures

If the shell cannot find hermes, open a new shell and inspect PATH. If the CLI starts but chat fails, reopen hermes model and check the provider, model, and authentication method. When doctor reports a problem, read its diagnostic locally. Before pasting it into an issue or chat, remove keys and local paths.

Get one clean chat working before adding Gateway, Cron, Skills, or other layers. That keeps the failure surface small. The next chapter separates the roles of CLI, TUI, and Desktop and explains how to resume sessions.

[Hermes Agent Series 01] Install Hermes Agent and Run Your First Task