Hermes Agent Quick Start

Install

Install Hermes Agent using the commands for your platform:

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

On Windows, open a new PowerShell terminal after installation if hermes is not found. Hermes Agent uses Git Bash internally for its terminal tool; WSL2 is optional. Refer to the Hermes Agent native Windows guide for installation and tool prerequisites. These instructions run Hermes Agent from the command line in the shell where you select the Relay configuration.

Complete the setup prompts and confirm that hermes can use your model provider before continuing. Check that hermes chat --help lists --oneshot; older builds can lack support for this recipe.

If Hermes Agent does not yet have a working provider and model, configure one with hermes model. For example, select the NVIDIA provider, supply an NVIDIA API key, and choose an available build.nvidia.com model.

export NVIDIA_BASE_URL='https://inference-api.nvidia.com/v1'

hermes chat --oneshot --provider nvidia --model 'nvidia/nvidia/Nemotron-3-Nano-30B-A3B' -q 'Use a file-writing tool to create relay-check.txt in the current working directory containing exactly RELAY_QUICKSTART_TOOL_OK. Then reply with RELAY_QUICKSTART_RESPONSE_OK.'

Configure

Create a disposable working directory and make sure the agent can write files there:

mkdir relay-hermes-quickstart
cd relay-hermes-quickstart

Save the following files and run the remaining commands from this directory.

Save the following configuration as plugins.toml in the directory where you will start Hermes Agent. Use UTF-8 encoding without a byte order mark:

# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
version = 1
[policy]
unknown_component = "error"
unknown_field = "error"
unsupported_value = "error"
[[components]]
kind = "observability"
enabled = true
[components.config]
version = 4
enable_full_payloads = false
[components.config.atof]
enabled = true
[[components.config.atof.sinks]]
type = "file"
output_directory = "logs"
filename = "events.jsonl"
mode = "overwrite"

Select that file and change its file sink to an absolute project logs directory. An absolute configuration path does not anchor a relative output path: Hermes Agent can run its gateway from its own installation directory. These commands adapt the saved template so events stay in this project’s logs directory:

jq -Rsr --arg directory "$(pwd -P)/logs" '
  "output_directory = \"logs\"" as $needle |
  if contains($needle) then
    split($needle) | join("output_directory = " + ($directory | tojson))
  else error("Expected the shared quick-start TOML template") end
' plugins.toml > plugins.toml.tmp &&
mv -- plugins.toml.tmp plugins.toml &&
export HERMES_NEMO_RELAY_PLUGINS_TOML="$PWD/plugins.toml"

If you repeat these configuration commands, save a fresh copy of the template first; they expect its original output_directory = "logs" setting.

Hermes Agent can reuse a gateway that remains alive after a one-shot command. An existing gateway retains its Relay configuration. In a dedicated quick-start installation or context, stop its existing gateway after changing the configuration, so the next run starts a process with the selected file:

hermes gateway stop

Run this command only for a gateway dedicated to this quick start. If your gateway serves other work, use a separate Hermes Agent installation or dedicated gateway for the trial. Do not use hermes gateway stop --all.

Run the diagnostic in that same shell:

hermes doctor

In the NeMo Relay Plugins section, confirm that the selected file is listed, plugins are enabled, and no Relay configuration problems are reported. If the section is missing, update Hermes Agent before continuing. Resolve problems in NeMo Relay Plugins and your selected inference provider. If the diagnostic says NeMo Relay is unavailable on this platform, the installation cannot capture the events required by this quick start; check the supported installation for your operating system and architecture.

Run

From the same directory, run a one-shot turn with the common validation prompt:

rm -f -- relay-check.txt logs/events.jsonl &&
hermes chat --oneshot -q "Use a file-writing tool to create relay-check.txt in the current working directory containing exactly RELAY_QUICKSTART_TOOL_OK. Then reply with RELAY_QUICKSTART_RESPONSE_OK."

Verify

The tool marker proves that the agent created the requested file. The event marker proves that Relay recorded matching start/end records for the required turn or agent, tool, and model work. The response marker is the agent’s reply; it is checked separately from the captured lifecycle.

The verification command prints RELAY_QUICKSTART_TOOL_OK and RELAY_QUICKSTART_EVENTS_OK.

jq -eRs 'gsub("^\\s+|\\s+$"; "") == "RELAY_QUICKSTART_TOOL_OK"' relay-check.txt > /dev/null &&
jq -se '
  . as $events |
  def closed($category):
    any($events[]; . as $end_event |
      .kind == "scope" and .scope_category == "end" and
      .category == $category and
      any($events[]; .kind == "scope" and .scope_category == "start" and
        .uuid == $end_event.uuid and .name == $end_event.name and
        .category == $end_event.category and .parent_uuid == $end_event.parent_uuid));
  length > 0 and
  all(.[]; .atof_version == "0.1" and (.kind == "scope" or .kind == "mark")) and
  closed("agent") and closed("tool") and closed("llm")
' logs/events.jsonl > /dev/null &&
printf 'RELAY_QUICKSTART_TOOL_OK\nRELAY_QUICKSTART_EVENTS_OK\n'

RELAY_QUICKSTART_TOOL_OK
RELAY_QUICKSTART_EVENTS_OK

The agent’s final reply should include RELAY_QUICKSTART_RESPONSE_OK; its surrounding wording can vary.

Inspect the Recorded Activity

Read the completed model calls from the same event file:

jq 'select(.kind == "scope" and .scope_category == "end" and .category == "llm") |
  {name, category, category_profile, uuid, parent_uuid, timestamp, metadata}' logs/events.jsonl

category and name identify the recorded work. The same uuid pairs its start and end records; parent_uuid connects it to its enclosing scope. timestamp records when this event occurred. For model calls, category_profile and metadata can include the model identity and completion status, depending on the integration. These fields let you follow a call through the run without requiring full prompt or response capture.