The Gateway: Programmatic Access to Hermes

Beyond the Terminal: Hermes as a Service

The CLI and the batch runner are powerful, but they share a constraint: they are terminal-based workflows. You run a command, wait for it to finish, and read the output. For many use cases, this is exactly right. But for others, you need something different: a persistent, running Hermes agent that your other tools and scripts can talk to over a network connection.

The Hermes gateway -- launched via hermes serve -- provides this. It starts Hermes as a background server that exposes a JSON-RPC/WebSocket API. Other programs can connect to this API, send prompts, receive streaming responses, and manage sessions programmatically. The agent is always running, always responsive, and accessible from any program that can make a network request.

This is the same backend that the Hermes Desktop app uses internally. When you open the Desktop app, it starts a headless hermes serve process and connects to it. Understanding the gateway means understanding the foundation of every Hermes interface.

Starting the Gateway

The basic command is straightforward:

hermes serve

By default, this starts the server on 127.0.0.1:9119 -- accessible only from the local machine. For local scripting and tool integration, this default is secure and appropriate.

Options that are worth knowing:

• --port 9120 changes the port if 9119 is in use
• --host 0.0.0.0 binds to all interfaces, making the server accessible from other machines on the network (requires authentication setup)
• --no-open prevents the command from trying to open a browser window
• --isolated runs a dedicated per-profile server, useful when you have multiple Hermes profiles

The server runs in the foreground and prints logs to stdout. For persistent deployment, use hermes gateway install to register it as a system service that starts automatically and logs to the system journal.

What the API Exposes

The gateway exposes a JSON-RPC interface over WebSocket. This is the same protocol the Desktop app uses, which means the full Hermes agent capability is available programmatically: starting sessions, sending prompts, receiving streaming token responses, calling tools, managing context, and reading session history.

The WebSocket connection makes streaming responses straightforward. Rather than waiting for a complete response, your client receives tokens as they are generated -- the same behavior you see in the terminal or the Desktop app, but available to any WebSocket-capable client.

For web applications and services that need to display Hermes responses in real time, this streaming capability is essential. A polling-based approach (send a request, wait, get the complete response) produces a poor user experience for long responses. Streaming via the gateway produces the progressive typing effect users expect from AI interfaces.

Dependencies for the Gateway

The gateway requires the web extras package to be installed:

cd ~/.hermes/hermes-agent && uv pip install -e ".[web]"

For embedded chat support (which enables the full chat experience through the gateway rather than just API access), also install the PTY extra:

uv pip install -e ".[web,pty]"

The PTY dependency is required on POSIX systems (macOS, Linux) for the full chat socket to function. On Windows, behavior differs and some features may not be available. Check the platform support documentation if you are deploying on Windows.

Gateway vs. Batch Processing: Choosing the Right Tool

Both the gateway and the batch runner let you interact with Hermes programmatically, but they serve different purposes:

A web application that wants to embed an AI assistant uses the gateway. A team that wants to generate 10,000 training examples uses batch_runner.py. Some workloads use both: a gateway for interactive use during business hours, batch_runner.py for overnight data generation jobs.

Authentication for Remote Access

When you run hermes serve on a remote server or bind to 0.0.0.0 on a local machine, you need authentication to prevent unauthorized access. Two mechanisms are available:

OAuth via Nous Portal. For public-facing deployments, this is the recommended approach. Nous Portal handles authentication and issues tokens that clients use to connect. This is the same mechanism the Desktop app uses for remote backend connections.

Username/password (basic auth). For trusted networks -- a local LAN, a VPN, a team server where you control who has access -- basic authentication is simpler. Set the HERMES_DASHBOARD_BASIC_AUTH_SECRET environment variable on the server to enable it:

HERMES_DASHBOARD_BASIC_AUTH_SECRET=your-secret-token hermes serve --host 0.0.0.0

Clients authenticate by including the secret token in their connection request. Keep this value secret and rotate it if it is compromised. Without authentication, anyone who can reach your server's port can access your Hermes agent and use your API credits.

Practical Use Cases for the Gateway

The gateway enables use cases that are not possible with the CLI or batch runner alone. A few common ones:

Integration with existing tools. If you have a CI/CD pipeline, a monitoring system, or a data processing workflow that needs AI capability, the gateway is how you add Hermes to it. Your existing scripts make WebSocket calls to the gateway rather than spawning a subprocess.

Building internal tools. A small web interface that lets non-technical team members send tasks to Hermes -- document review, email drafting, data analysis -- is a straightforward build on top of the gateway API. The gateway handles the agent; you just need to build the frontend.

Persistent automation. A gateway running as a system service can receive webhook triggers, process incoming messages, respond to scheduled events, and maintain state across all of these interactions in a single persistent session. This is the foundation for ambient automation use cases where Hermes does work continuously in the background rather than on explicit request.