Hermes Agent getting started

Fastest path to a useful Hermes Agent result

Prerequisites and success criterion

Before the first run, confirm all five:

• A supported platform: macOS on Apple Silicon, Windows 10 or 11, Linux, WSL2, or a container host.
• Git available on PATH. The installer provisions Python 3.11, Node.js, ripgrep, and ffmpeg itself.
• A model provider you can authenticate today, with a model of at least 64,000 tokens of context.
• A working directory you are willing to let an agent read and modify.
• A written success criterion — one sentence describing the artifact that proves this worked.

A usable success criterion is concrete: "a SUMMARY.md in this repo listing every exported function in src/ with its file and line." An unusable one is "see if it's any good."

Choose how you will run Hermes Agent

You are choosing an interface, not committing to it. All of them share one configuration directory, so switching later costs nothing.

If the desktop application is your starting point, Hermes Desktop covers its installation and how it connects to a local or remote runtime.

Complete installation

Install, then confirm the command resolves before going further. If hermes is not found after installation, that is almost always an unreloaded shell rather than a failed install.

Method choice, exact commands per platform, and the verification step live on the installation guide. This page deliberately does not duplicate them because installation changes with releases, and keeping the procedure in one focused guide makes it easier to keep current.

Choose and connect a model provider

Run the interactive picker and choose exactly one provider:

Two things decide this choice: whether you can authenticate today, and whether sending prompt data to that provider is acceptable. Both, plus the setup for each provider category, are covered in model and provider setup.

Apply safe defaults

Do this before the first real task, not after the first surprise.

• Approval mode. The default is smart: an auxiliary model triages risky commands, auto-approving low risk and escalating uncertain cases. manual prompts every time. off disables the checks entirely and is the same as --yolo.
• Terminal backend. local runs on your machine. docker runs inside a container, which is treated as the security boundary.
• Toolsets. Start with what your first task needs. Browser and messaging can wait.

Full precedence rules and where each of these is stored are in the configuration guide; the threat each default is protecting you from is in the security baseline.

Run a first bounded task

Start a session:

Then give it one task with a checkable artifact. Good first tasks share three traits: a defined input, a single output file or message, and a result you can verify in under a minute. For example: summarise the repository in the current directory into five bullets and name the main entry point.

Verify output and tool behavior

Run all four checks:

• The artifact exists. Open the file or message the task was supposed to produce.
• The content is right. Spot-check two claims against the source directly.
• The tool calls happened. The interface shows tool activity; an answer with no tool call means the model answered from memory, not from your data.
• The session persists. Reopening with hermes --continue should resume the conversation.

If all four pass, you have a verified first result and a baseline to change one variable at a time from.

Choose the next interface or workflow

Once one task works, extend in exactly one direction:

• A better surface: move to Hermes Desktop if the terminal is the friction.
• More reach: add tools, integrations, or an MCP server.
• Less babysitting: schedule a task, or connect a messaging channel — both change the approval question, because nobody is watching.

Recover from setup failure

When the first run fails, resist reinstalling. Capture the exact error, then follow the troubleshooting flow, which isolates the failing component before changing anything. The built-in diagnostic is the right first move: