Choose a Programmatic Hermes Integration Protocol

Choose between ACP, the TUI gateway, and the OpenAI-compatible API server when embedding Hermes in an IDE, custom host, or web client. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

Hermes exposes three integration protocols over the same agent core. ACP is JSON-RPC over stdio for IDE clients; the TUI gateway is JSON-RPC over stdio or WebSocket for fine-grained custom hosts; the API server is HTTP plus Server-Sent Events for OpenAI-compatible and language-agnostic clients.

ACP already models sessions, prompts, streaming messages, tool events, permission requests, cancellation, forks, and authentication in a format IDEs understand.

The TUI gateway exposes detailed session control, slash-command dispatch, approvals, clarification and secret prompts, delegation state, process control, terminal resizing, and streamed lifecycle events.

The API server exposes chat/responses compatibility plus explicit run, event-stream, approval, stop, capability, model, and health endpoints. Session identifiers and keys belong in headers, not URLs or logs.

Practical checklist

Pick the protocol from the consumer and transport, not from feature-name familiarity.
Model approval, clarification, secret, and cancellation states explicitly in the host UI.
Correlate expiry and response events by request identifier.
Keep session credentials out of browser history, telemetry, and screenshots.
Test interruption and reconnect behavior, not only the happy path.

Common pitfalls

Inventing a --mode rpc flag instead of using a supported protocol.
Using process-local active-session methods as a substitute for saved transcript discovery.
Ignoring streamed approval or secret requests and leaving a run stalled.
Treating OpenAI compatibility as proof that every Hermes lifecycle feature is represented by a basic chat endpoint.

Verification steps

Start the selected server and wait for its ready or health signal.
Create a session, submit a prompt, observe streaming, and capture a tool event.
Resolve one approval in a safe test flow and interrupt another run.
Reconnect or resume according to the protocol, then confirm session state remains coherent.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/programmatic-integration