Hermes API
Start with hermes.mdx for shared setup and an overview of all four invocation paths.
NVIDIA NeMo Fabric can host Hermes’s native HTTP API as a managed hermes gateway run process. Requests execute through native agents, independently of the embedded SDK and TUI backend. The HTTP service uses aiohttp; it is separate from the FastAPI dashboard service.
Installation
Complete the shared installation first. The API path additionally requires aiohttp in the Hermes adapter environment. For Hermes v0.22.5, the pinned version is 3.14.5.
If you used just install-hermes-agent, this dependency is already installed. For a separately prepared Hermes environment, install it with ADAPTER_PYTHON set to that environment’s interpreter:
Verify the dependency in the same environment:
The API path requires a POSIX host. It needs no browser assets, terminal frontend, or Node runtime.
Configuration
Combine the normalized model/workspace configuration from the SDK guide with these harness settings:
This disables embedded SDK execution explicitly. Omit sdk to also start the embedded Hermes AIAgent alongside the native API process. The API is off unless selected; selecting it does not start a dashboard or terminal backend. Model, instructions, tools, and Relay remain in normalized configuration fields.
Authentication
The API server binds to 127.0.0.1 at its configured port. After every enabled interface passes readiness, the adapter writes a per-start bearer token with mode 0600 to:
Before starting Hermes, the adapter removes any API token left by an earlier runtime.
Clients calling the native API must read the generated token file and include Authorization: Bearer <token> in each HTTP request. Only the API gateway child receives it in its environment. Processes running as the runtime’s user, including agent tools, can read the token file.
This token authenticates access to the API gateway. It is distinct from the model-provider API key and the TUI backend credential used by dashboard and terminal clients. API clients share the per-start token; it does not provide per-user isolation.
Requests, Clients, and Conversations
The pinned native service includes OpenAI-compatible chat completions and responses, native run/session endpoints, and health diagnostics. The managed chat-completions path has end-to-end evidence; other native routes need separate qualification before relying on equivalent behavior.
Multiple clients can connect. Use native session/conversation mechanisms for separate histories; clients share the runtime’s workspace, tools, home, and per-start bearer credential. Concurrent workload qualification is separate from accepting multiple connections.
Native requests do not pass through Runtime.invoke() and do not return NeMo Fabric RunResult objects. Shared configuration does not attach them to the embedded SDK conversation.
Relay Trajectories
With Relay enabled, managed API turns finalize and flush a segment when native execution returns. ATIF is available per turn without deleting native history; subsequent turns can continue the conversation and produce new segments. Check actual ATOF events and ATIF tool steps, since export failures are logged and do not replace the response.
Health, Testing, and Limitations
- Native health endpoint:
/healthbelongs to Hermes’s API server. Calling it directly checks that native service; it does not return a normalized NeMo Fabric health report or check the embedded SDK agent and TUI backend. - Startup readiness: The adapter polls the API server’s
/healthendpoint and waits for HTTP 200 before declaring that interface ready. Startup fails if the process exits or readiness is not established within the startup budget. - Normalized health with the SDK enabled:
Fabric.check()observes the embedded SDK agent and preserves itsidle/busyactivity. A failed API child does not fail that SDK health check. Probe the API/healthendpoint or inspect its interface log separately to diagnose the API service. - Normalized health with the SDK disabled:
Fabric.check()observes the enabled native backends. For the API backend,livechecks the owned process;activeandreadyalso probe/health. An enabled TUI backend is checked too. Activity isunknownbecause native turns are not fully aggregated.
Neither the native endpoint nor the normalized checks execute a model/tool turn. Hermes also exposes authenticated /health/detailed, run status, and persisted sessions for native diagnostics; these do not provide a unified inventory of live agents in NeMo Fabric.
See the API example for requests and trajectory inspection, and the shared limitations for lifecycle and artifact boundaries.