Skip to navigation

Use the Hermes Agent Adapter

View as MarkdownOpen in Claude

You can use Hermes Agent through the NVIDIA NeMo Fabric adapter in four ways:

  • SDK: Invoke the embedded agent programmatically and receive normalized NeMo Fabric results.
  • HTTP API: Send requests to Hermes’s native API and receive native HTTP responses.
  • Dashboard/browser TUI: Chat with Hermes through its dashboard in a browser.
  • Terminal TUI: Chat with Hermes from a terminal attached to the managed TUI backend.

SDK execution is enabled by default; native interfaces are explicit options. All four paths use the normalized FabricConfig, which the adapter translates into Hermes’s native configuration and agent settings.

Four client invocation paths share three Hermes execution backends within one NeMo Fabric runtime: embedded SDK, API gateway, and a TUI service shared by browser and terminal clients.

PathExecution backendGuide
SDKEmbedded AIAgent in the adapter hostHermes SDK
Native HTTP APIManaged API gateway process using aiohttpHermes API
Dashboard/browser TUIManaged FastAPI/Uvicorn TUI service with browser assets and a PTY bridgeHermes Dashboard and Browser TUI
Terminal TUITerminal renderer attaches over WebSocket to the same TUI service; headless serve when dashboard is offHermes Terminal TUI
  • Agent execution: All four paths use the same Hermes agent loop, with separate live agents and conversations.
  • Runtime ownership: One NeMo Fabric runtime owns up to three backend processes: the adapter host, API gateway, and TUI service.
  • TUI clients: Browser and terminal clients share the TUI service and use separate conversations. Neither requires the API gateway.

Install the Adapter

Use Hermes Agent v0.22.7 with Python 3.14. The adapter package supports Python 3.11 through 3.14, but Hermes Agent must be installed separately from source; versions 0.20 and later are not available from PyPI. Follow the Hermes Agent installation guide and select v0.22.7.

Install the runtime and adapter in the environment that runs Hermes:

python -m pip install "nemo-fabric[hermes-agent]"

If the application runs NeMo Fabric in a separate environment, install nemo-fabric-adapters-hermes in the Hermes environment and set ADAPTER_PYTHON in the application’s environment to that interpreter. Use matching runtime and adapter release versions unless a different pairing has been validated.

For Relay, install the adapter’s relay extra in the Hermes environment. It accepts nemo-relay>=0.10,<0.12; select the Relay line required by the installed Hermes release:

Hermes AgentNeMo Relay Python Package
v0.22.7>=0.11,<0.12
v0.22.5>=0.10,<0.11

Startup requires a stable Relay 0.10 or 0.11 release and Hermes’s callable agent.relay_runtime.resolve_plugin_sources hook. Keep environments using the legacy pairing separate from applications requiring Relay 0.11.

For repository development, the following recipe checks out v0.22.7 at b200f5bc60e31588ba2cb60e288029c4a54ba5fa and prepares an isolated Python 3.14 environment with Relay support:

just install-hermes-agent
export ADAPTER_PYTHON="$PWD/.venv-hermes/bin/python"

The installer preserves local checkout changes and stops rather than overwriting them. Set HERMES_AGENT_CHECKOUT to a separate clean checkout or a new directory to install without changing external/hermes-agent; the target environment remains .venv-hermes.

Hermes reports its Python package version as 0.0.0, so use its Git tag and commit to identify the installed release. The pinned release includes dependency security fixes absent from v2026.9.24.

Select Execution Paths

Use normalized FabricConfig fields for model credentials/routing, instructions, tools, MCP, skills, workspace, turn limits, and telemetry. The SDK guide shows a complete model configuration. Use harness.settings to select Hermes execution paths:

settings = {
"sdk": {"enabled": False},
"interfaces": {
"api": {"port": 8642},
"dashboard": {"port": 9119},
"terminal": {"port": 9119},
},
"startup_timeout_seconds": 60,
}

This example enables three native client paths without an embedded SDK agent. Omit sdk to preserve the default SDK agent. Omit an interface to turn it off; a present interface is on unless enabled is false. Current closed schemas require a port even for a disabled interface. Native interfaces require POSIX. Reject a configuration with no enabled execution path.

  • Ports: Dashboard and terminal must use the same port when both are enabled because they share one TUI service. The API requires a separate port.
  • Startup: Terminal-only mode starts hermes serve; dashboard mode starts hermes dashboard --isolated --skip-build. Build the required frontends before runtime startup; terminal-only mode needs no browser assets.
  • Startup timeout: Defaults to 60 seconds and must be greater than zero and no more than 75 seconds.

What NeMo Fabric Normalizes

SurfaceSDKNative API, Browser, and Terminal
ConfigurationNormalized fields mapped to the embedded agentSame explicit behavioral mapping and generated native configuration in adapter-owned processes
LifecycleRuntime startup and owned shutdown when enabledManaged child startup/readiness and shutdown; terminal detach does not stop the runtime
ResultsNormalized RunResultNative protocol/UI responses; no normalized invocation result
Relay evidenceStandard ATOF/ATIF, finalized/flushed per invocationStandard native-session evidence, finalized/flushed per completed agent turn; verify export contents
Session artifactsSDK invocation artifact collectionComplete session-scoped transcript/generated-file collection remains planned work

Shared Configuration and Ownership

Configuration Translation

Use a single FabricConfig to define supported settings for all four Hermes paths through NeMo Fabric’s common configuration schema:

  • Model: provider, model, endpoint, credential references, and sampling settings.
  • System instructions: the replacement system prompt.
  • Tool filters: enabled and blocked Hermes toolsets.
  • MCP: server definitions and supported authentication settings.
  • Skills: skill folders, bundled-skill selection, and duplicate handling. Refer to Skills.
  • Plugins: bundled plugins and external plugin folders. Refer to Plugins.
  • Workspace: the agent’s working directory.
  • Execution limits: maximum agent turns and response tokens.
  • NeMo Relay: telemetry and export configuration, when enabled.

NeMo Fabric resolves FabricConfig into AgentConfig. The adapter translates it into Hermes’s native configuration and agent settings, applying the same explicit instructions and behavioral settings to agents in managed native processes.

The adapter writes native config.yaml under the Hermes home. When NeMo Relay is enabled, the adapter creates a relay-config directory beside the file specified by FABRIC_RELAY_CONFIG_PATH and writes plugins.toml there. This location follows FABRIC_RELAY_CONFIG_PATH even with runtime.keep_state enabled. When native interfaces are enabled, it also writes an owner-only interfaces/agent-config.json snapshot for the managed processes.

Model credentials are supplied through child process environments, not public attachment metadata. For an OpenAI-compatible custom endpoint, native configuration binds the endpoint to its declared credential environment variable, including gateway placeholder keys, so unrelated provider credentials in the host environment do not override that route. Hermes’s API server, dashboard, and terminal UI send an anthropic model’s requests to its base_url whatever the path, such as https://MODEL_HOST/v1, through Anthropic’s Messages API with the key in x-api-key; Hermes’s own anthropic provider would use only an Anthropic, Claude, or Azure host, or a path ending in /anthropic or /anthropic/v1. For OpenAI without an explicit base URL, the adapter removes inherited OPENAI_BASE_URL from managed children so it cannot redirect the configured credential.

Setting Precedence

  • Configured instructions, turn/token limits, sampling, and reasoning settings override Hermes’s native defaults.
  • Explicit enabled tools, including an empty list, override native tool selection. A nonempty blocked list overrides native exclusions.
  • Unspecified native tool policies can differ from SDK defaults. Set explicit policies when comparing behavior across paths.

Native Harness Controls

The following optional harness.settings fields use Hermes’s native config.yaml structure:

harness:
adapter_id: nvidia.fabric.hermes
settings:
auxiliary:
title_generation:
enabled: false
background_review:
enabled: false
tools:
tool_search:
enabled: "off"
SettingValuesBehavior
auxiliary.title_generation.enabledbooleanfalse turns off automatic session-title generation.
auxiliary.background_review.enabledbooleanfalse turns off automatic background memory and skill reviews after turns. Explicit native /refine remains available.
tools.tool_search.enabledauto, on, off, true, or falseoff presents the selected tool schemas directly instead of behind tool search. true and false are native aliases for on and off. auto follows the installed Hermes release.

The adapter writes only the fields you set into config.yaml before the SDK agent or any native interface starts, so the SDK, API, dashboard, and terminal paths all read the same values. Omitting a field preserves the current behavior. The closed descriptor schema rejects unknown fields and invalid values, such as tool_search.enabled: maybe.

  • Title generation and Relay: An explicit title_generation.enabled value always wins. When it is omitted, a Relay-enabled runtime disables title generation, as before, and other runtimes use Hermes’s default.
  • Tool selection: harness.settings.tools is Hermes’s native tools section. It is separate from NeMo Fabric’s normalized top-level tools.enabled and tools.blocked selectors, which still choose the Hermes toolsets.
  • Scope: These controls reduce automatic background model calls; they do not stop context compaction calls. They configure every conversation in the runtime the same way and do not correlate concurrent sessions, so a consumer that tracks only the latest model request must use one session at a time.

Skills

Configure Skills describes the skills fields, the common setups, the start checks, and the run report. Its Harness Differences table compares Hermes Agent with OpenClaw. This section covers the rest of Hermes’s behavior.

The adapter writes skills.paths or skills.directories to Hermes’s skills.external_dirs in config.yaml, so the SDK, API, dashboard, and terminal paths load the same skills.

  • Names: The adapter reads each skill with Hermes’s own front-matter parser and skill catalog rules, so the name under loaded is the name Hermes reads. Hermes reads front matter only when a line break follows its closing ---. A name written as a list loads as its string form.
  • Skipped skills: The report lists a skill that Hermes doesn’t load under skipped, with one of these reasons:
    • excluded_path: The skill’s path contains a folder name that Hermes skips, such as node_modules or site-packages.
    • unreadable: The SKILL.md can’t be read.
    • not_loaded_by_hermes: Hermes’s catalog drops the skill, for example because its name or description is null or a number.
    • no_name: The name is an empty string. Hermes lists the skill but can’t load it.
    • native_conditions: Hermes hides the skill on the current platform or environment.
    • ambiguous: The skill’s name is another skill’s folder name, so Hermes refuses it.
  • Overlapping entries: When an entry lies inside another entry’s folder, such as a skill entry inside a folder entry, the adapter passes only the outer folder, because Hermes refuses a skill it reaches through two folders. An entry under a folder Hermes skips, such as node_modules or a skill’s scripts folder, is still passed.
  • Agent-written skills: Hermes’s skill_manage tool writes new skills to the Hermes home’s skills folder, because the adapter doesn’t set Hermes’s skills.create_dir. That folder persists only with runtime.keep_state, which makes the agent’s state folder the Hermes home, so the next runtime for the same agent loads the skills it wrote. Hermes edits an existing skill from skills.directories in its configured folder. On a read-only mount, the edit fails, the file stays as it was, and the tool returns the permission error to the agent.

Bundled Skills

Hermes copies its bundled skills into the skills folder of its home. The embedded SDK agent doesn’t copy them, so with skills.bundled omitted, an SDK-only runtime with a new home has no bundled skills. A runtime with the API, dashboard, or terminal interface gets Hermes’s own copy, because those processes copy the bundled skills at start. When such a runtime has a skill report, the adapter makes the same copy before it starts the interfaces, so the report lists those bundled skills and the interfaces’ own copy finds nothing left to do. As in the interfaces, a failure of that copy is logged and doesn’t stop startup when skills.bundled is omitted. Whenever skills.bundled is set, the adapter copies the selected bundled skills into the home at startup, as Hermes does. The copy always includes hermes-agent, and it removes an earlier copy of a bundled skill that an external skill now provides.

Hermes always loads hermes-agent, so NeMo Fabric rejects a selection that leaves it out rather than load a skill you didn’t select. Hermes supports skills.bundled: {} (every bundled skill) and an exclude list. To load the fewest bundled skills, exclude every bundled skill except hermes-agent.

  • The descriptor advertises supports_include: false and supports_disable: false, so planning rejects any include list, including include: [] and include: [hermes-agent], and enabled: false before the runtime starts. Hermes would still load hermes-agent, so neither can mean what it says. A runtime started without planning fails startup with hermes_skill_invalid, the reason essential_bundled_skill, the field skills.bundled.include or skills.bundled.enabled, and the name hermes-agent.
  • An exclude list that names hermes-agent fails startup the same way, with the field skills.bundled.exclude.

When the selection leaves skills out, the adapter stages the selected bundled skills in a temporary folder, laid out as in the Hermes installation, and points HERMES_BUNDLED_SKILLS at it. Hermes copies bundled skills from that folder, both at the adapter’s startup copy and in the API, dashboard, and terminal processes, which inherit the variable. Stop removes the folder. The adapter doesn’t use Hermes’s skills.disabled, so a skill that shares a left-out skill’s name loads normally:

  • External skills: When a selected bundled skill has the same name, or folder name, as an external skill, Hermes doesn’t copy the bundled skill and loads the external one.
  • The agent’s own skills: A skill in the Hermes home that Hermes didn’t copy from its bundled skills, such as one the agent wrote in a kept state folder, loads wherever it is in the home. When the selection keeps a bundled skill whose name the agent’s own skill holds, the agent’s skill loads, and the report lists the bundled skill under bundled.unavailable with the reason provided_by_local_skill.
  • Earlier copies in a kept home: A kept state folder can hold Hermes’s copy of a bundled skill from an earlier runtime that selected it. Hermes records each bundled skill it copies, with a hash of the copy, in the home’s skills/.bundled_manifest file. When a left-out skill’s copy still matches that hash, or the installed skill, the adapter removes the copy and its manifest entry before Hermes copies the bundled skills, so a later runtime that selects the skill gets a fresh copy. A selected bundled skill nested in the removed folder loses its copy too, so its entry also goes and Hermes copies it again in the same start. The adapter first records the entries to drop, with the files each copy holds, in skills/.nemo_fabric_pending_manifest, which Hermes doesn’t read as a skill, and removes the record when it is done. If a start fails part way, the next start completes the record before Hermes copies the bundled skills: it removes what is left of a copy when every remaining file is one it recorded, unchanged. Like Hermes’s own copy check, the record and the comparison skip runtime cache files, such as __pycache__ folders and a .pyc file beside its .py source, which running a skill’s scripts writes. When a file in a partly removed copy was changed or added since, the adapter keeps the copy and startup fails with the same error as for a changed copy below; move or delete the copy. When the copy at the place Hermes put it was changed, the adapter doesn’t remove it. Startup fails with hermes_skill_invalid, the reason excluded_bundled_skill_modified, the field skills.bundled.exclude, the skill name, and the copy’s path. Select the skill, or move or delete the copy.

Skill Report

The run report has the shape that Configure Skills describes, with these Hermes details:

  • When it appears: Whenever skills.directories, even [], or skills.bundled is set.
  • loaded: Lists every skill Hermes’s catalog loads, that is, every skill Hermes resolves its name to and shows on this platform. The configured skills come first, in entry order, with origin: external. Every other skill follows, by name, with its path: Hermes’s copy of a bundled skill in the Hermes home as bundled, and the agent’s own skills in the home, project skills, skills from skills.paths, and any other skill Hermes reads as local. A skill the agent created in a kept state folder appears as local from the next runtime on. An empty list means Hermes loads no skill. When Hermes’s catalog can’t be read, the report lists only the configured skills.
  • duplicates: Lists each name that more than one skill folder provides among the skills Hermes sees, including a bundled copy and the agent’s own skill in the Hermes home with no external copy. The outcome is selected when a configured copy loads, or, with no configured copy, when Hermes loads one copy. It is shadowed when a copy in the Hermes home wins over the configured copies, and ambiguous when Hermes refuses the name.
  • bundled: Adds essential, the skills Hermes always loads. selected also lists them.

Plugins

harness.settings.plugins names each plugin by where it comes from. The adapter writes it to Hermes’s native plugins section in config.yaml:

harness:
adapter_id: nvidia.fabric.hermes
settings:
plugins:
bundled:
entries:
security-guidance: {enabled: true}
browser/firecrawl: {enabled: false}
external:
paths: [/sandbox/plugins/my-plugin]
entries:
my-plugin: {enabled: true, config: {greeting: hi}}
load_timeout_seconds: 20
  • bundled.entries: Plugins that ship with Hermes, keyed by registry key or manifest name. enabled: false turns off a plugin Hermes loads by default.
  • external: Plugin folders that something else provides, such as a mounted volume. The adapter links each folder into $HERMES_HOME/plugins at start and removes the link at stop. A folder’s Python dependencies must already be importable. A path alone doesn’t turn a plugin on.
  • Entries: Each takes enabled, config (written to plugins.entries.<id>.settings), and capabilities (written to plugins.entries.<id>.granted_capabilities). A plugin id may appear in only one section.
  • Hermes controls: load_timeout_seconds, hook_callback_timeout, clone_timeout_seconds, auto_update_check_hours, auto_apply, isolation, and host.launcher are written as they are.

After Hermes discovers its plugins, startup fails unless every entry with enabled: true loaded. Each error names the setting in metadata.field:

ErrorWhen
hermes_plugin_not_foundHermes has no such plugin, an external folder doesn’t exist, or no folder provides an external.entries name.
hermes_plugin_unavailableThe plugin didn’t load or its entry also turns it off. The message carries Hermes’s reason.
hermes_plugin_invalidAn external path isn’t a folder or has no readable plugin.yaml.
hermes_plugin_duplicateTwo external folders share a name, or the Hermes home already holds a plugin of that name.
hermes_invalid_configA plugin id is in both sections, or a bundled entry doesn’t ship with Hermes.
hermes_plugin_agent_installed_unsupportedThe kept Hermes home holds a plugin environment (installs/<key>/environments) from an agent plugin install.

NeMo Fabric doesn’t support plugins the agent installs itself. Hermes builds a Python environment for each install, and importing Hermes later switches the whole adapter process to it, which removes NeMo Fabric’s packages. With runtime.keep_state, startup fails before Hermes is imported; delete the folder and provide the plugin through external instead.

Shared Runtime Home

The default Hermes home is <artifact root>/.fabric/hermes/runtimes/<runtime-id>. With runtime.keep_state, the Hermes home is <artifact root>/.fabric/state/nvidia.fabric.hermes/<agent name>, so runtimes of the agent share the session database, memory, skills, and logs. The SDK starts a new conversation for each runtime, and earlier sessions remain in the database. The adapter rewrites config.yaml at each start.

Startup removes stale interfaces/api.token, interfaces/tui.json, interfaces/tui.token, and interfaces/agent-config.json files from the Hermes home. A removal failure stops startup with hermes_interface_cleanup_failed before Hermes setup.

Process Ownership

Managed native processes run through the adapter’s launcher without modifying the installed Hermes source. Independently started processes do not automatically receive the adapter’s configuration mapping.

The managed API gateway disables ambient messaging platforms and profile multiplexing. Inherited settings such as TELEGRAM_BOT_TOKEN do not start chat-channel dependency installers in this runtime.

Health and Shutdown

Startup checks every enabled interface: API /health and TUI /api/status; TUI startup also verifies an authenticated RPC without creating a conversation. An enabled interface that fails startup still fails runtime startup.

When the SDK agent is enabled, runtime health and idle/busy activity describe that SDK agent. A separate API or TUI process failure does not fail SDK runtime health. Observe native endpoints and interface logs separately; a normalized interface health target is planned under #566.

With sdk.enabled: false, runtime checks inspect the enabled native children and endpoints. Native activity remains unknown because native turns are not fully aggregated. There is no unified live-agent inventory.

Stop removes API/TUI credentials and attachment descriptors, sends SIGTERM to owned interface process groups, and escalates to SIGKILL after five seconds. API gateway drain is three seconds. The configuration snapshot is removed and owned SDK resources are closed. Cleanup errors are logged; failed private-file removal is retried on a later stop.

Limitations and Planned Work

  • Native response normalization, complete native usage accounting, and session-scoped artifact collection remain separate work.
  • Child crash recovery, listener process-ownership checks, and stronger descendant cleanup when process-group signals are denied remain planned. HTTP/RPC readiness is not a live model or tool execution check.
  • Browser chat is restricted to the managed runtime profile. Named-profile switching, gateway restart/migrate controls, and other dashboard operations can escape the supported ownership/configuration model. Do not use those controls to replace managed processes.
  • Dashboard pages have no separate NeMo Fabric sign-in on loopback. Terminal credentials do not add a browser sign-in gate. Clients share filesystem/tools; separate conversations do not provide user isolation.
  • TUI approvals and client detach/cancellation behavior need their own qualification; the adapter currently inherits HERMES_YOLO_MODE (defaulting to enabled). Detaching is not an explicit stop/cancel operation.
  • Relay export errors are logged without replacing the execution outcome. Verify completed artifacts. Standard formatting does not establish complete telemetry coverage for every native control or background operation.
  • Runtime-wide native activity discovery, same-conversation multi-client policy, cold resume, and SDK/native conversation handoff remain planned work.

Try the Interfaces

See the interfaces examples for manual startup, real input, output checks, and Relay trajectory inspection. Coverage and remaining qualification limits are described there.