Hermes Agent Subscription Proxy: Use Your Portal Subscription with Any OpenAI App
Route OpenAI-compatible app requests through your Hermes-managed provider subscription.
The Hermes Agent subscription proxy is a local HTTP server that lets external applications such as OpenViking, Karakeep, Open WebUI, or any tool that speaks the OpenAI-compatible chat completions protocol use your Hermes-managed provider subscription as their LLM endpoint. The proxy attaches the correct credentials automatically and refreshes them as needed, so the external app never needs a static API key. Once wired up, an agent or application can send requests to the proxy and receive model responses routed through your subscription, without any direct integration with the provider's authentication system.
What It Does
The subscription proxy provides the following concrete capabilities, as documented in the official Hermes Agent documentation:
- Acts as a local HTTP server that accepts OpenAI-compatible chat completion requests from external apps.
- Automatically attaches the real provider credential (OAuth bearer token) to each upstream request, refreshing it before expiry.
- Forwards the request body verbatim to the upstream provider and streams the response back unchanged, preserving server-sent events (SSE).
- Supports multiple providers via a pluggable adapter system; currently shipped adapters are
nous(Nous Portal) andxai(xAI / Grok). - Only forwards specific paths that the upstream actually serves, returning 404 with a clear error for unsupported paths.
- Does not perform any transformation, logging of request bodies, or agent loop. It is a credential-attaching pass-through.
This is distinct from the Hermes API server. The API server serves your agent with its full toolset, memory, and skills, and requires your API_SERVER_KEY for authentication. The subscription proxy serves only raw model inference, accepts any bearer token from the client, and does not support tool calls. Use the API server when you want the agent as a backend. Use the proxy when you just want the model through your subscription.
Setup
Setting up the subscription proxy involves three steps: logging into your provider, starting the proxy, and pointing your application at it.
1. Log into your provider (one-time)
Run the following command in your terminal:
hermes portal
This opens your browser for the Nous Portal OAuth flow. Hermes stores the refresh token in ~/.hermes/auth.json, the same location where all Hermes provider logins are stored. This is a one-time step; you do not need to repeat it unless your credentials are revoked.
2. Start the proxy
Run the following command:
hermes proxy start
You should see output similar to:
Starting Hermes proxy for Nous Portal
Listening on: http://127.0.0.1:8645/v1
Forwarding to: (resolved per-request from your subscription)
Use any bearer token in the client, the proxy attaches your real credential.
Leave this process running in the foreground. If you want it to survive logout, use tmux, nohup, or a systemd unit.
3. Point your app at it
Any OpenAI-compatible application configuration takes the same three values:
Base URL: http://127.0.0.1:8645/v1
API key: anything (e.g. "sk-unused")
Model: Hermes-4-70B # or Hermes-4.3-36B, Hermes-4-405B
The proxy ignores the Authorization header from your application and attaches your real Portal credential to the upstream request. Token refreshes happen automatically when the bearer approaches expiry.
Configuration Reference
The proxy has a small set of configuration options, all provided as command-line flags to hermes proxy start. The following table documents every option mentioned in the official documentation:
| Option | Description | Default |
|---|---|---|
--host | IP address to bind the proxy to. Use 0.0.0.0 to listen on all interfaces for LAN access. | 127.0.0.1 (localhost only) |
--port | TCP port to listen on. | 8645 |
No other configuration flags are documented. The proxy does not have its own configuration file; all settings are passed via the command line.
How It Works
The proxy is intentionally minimal in its architecture. Per request, the following sequence occurs:
- The proxy receives a
POST /v1/chat/completions(or other allowed path) from your application. - It looks up the adapter's current credential. If the credential is approaching expiry, it refreshes it automatically.
- It forwards the request body verbatim to the upstream provider, attaching an
Authorization: Bearer <token>header with the real credential. - It streams the response back unchanged, preserving server-sent events (SSE) for streaming responses.
No transformation is applied to the request or response. No logging of request bodies occurs. There is no agent loop. The proxy is a credential-attaching pass-through.
Allowed paths
The proxy only forwards paths that the upstream actually serves. For Nous Portal, the allowed paths are:
| Path | Purpose |
|---|---|
/v1/chat/completions | Chat completions (streaming and non-streaming) |
/v1/completions | Legacy text completions |
/v1/embeddings | Embeddings |
/v1/models | Model list |
Other paths, such as /v1/images/generations or /v1/audio/speech, return a 404 status code with a clear error message pointing at the allowed paths. This prevents stray clients from leaking unsupported requests to the upstream.
Available providers
To list the currently available upstream adapters, run:
hermes proxy providers
As of the documentation, the shipped adapters are nous (Nous Portal) and xai (xAI / Grok). More OAuth providers can be added by implementing the UpstreamAdapter interface in hermes_cli/proxy/adapters/.
Checking status
To check the status of the proxy and its upstream adapters, run:
hermes proxy status
Example output:
Hermes proxy upstream adapters
[nous ] Nous Portal, ready (bearer expires 2026-05-15T06:43:21Z)
If you see not logged in, run hermes portal to re-authenticate. If you see credentials need attention, your refresh token was revoked (rare, happens if you signed out from the Portal web UI). In that case, simply re-run hermes portal.
Requirements and Limitations
- The proxy requires a valid Hermes Agent installation and a logged-in provider subscription (Nous Portal or xAI/Grok).
- The proxy binds to
127.0.0.1by default, which means it is only accessible from the local machine. To expose it on a local area network (LAN), use--host 0.0.0.0. - The proxy has no authentication of its own. It accepts any bearer token from the client. If you expose it beyond your trusted network, you must use a firewall, VPN, or reverse proxy with proper authentication.
- Rate limits from your Portal tier (requests per minute, tokens per minute) apply across the whole proxy. The proxy does not fan out or pool requests; it uses a single bearer with your full subscription quota. Monitor usage at portal.nousresearch.com.
- The proxy does not support tool calls. It is a passthrough for raw model inference only.
- Providers that are not OpenAI-compatible at the protocol level (for example, the Anthropic Messages API) would require a transformation layer, which is out of scope for the current shape of the proxy.
Troubleshooting
The official documentation mentions two specific failure modes and their fixes:
"not logged in" status
If hermes proxy status shows not logged in, run hermes portal to initiate the OAuth flow again. This is the standard fix for a missing or expired login session.
"credentials need attention" status
If hermes proxy status shows credentials need attention, your refresh token has been revoked. This is rare and typically happens if you signed out from the Portal web UI. The fix is to re-run hermes portal to obtain a new refresh token.
Proxy not starting or binding to port
If the proxy fails to start because the port is already in use, ensure no other instance of the proxy is running, or specify a different port with --port. The documentation does not provide a specific error message for this scenario, but it is a common issue with local servers.
Application receives 404 errors
If your application sends requests to paths other than the allowed ones (/v1/chat/completions, /v1/completions, /v1/embeddings, /v1/models), the proxy returns a 404 with a clear error message. Check your application's configuration to ensure it is using one of the allowed paths.
Example: Configuring OpenViking
OpenViking is a context database that needs an LLM provider for its VLM (vision/language model used to extract memories) and embedding model. With the proxy, you can point its vlm.api_base at your local proxy.
Edit ~/.openviking/ov.conf:
{
"vlm": {
"provider": "openai",
"model": "Hermes-4-70B",
"api_base": "http://127.0.0.1:8645/v1",
"api_key": "unused-proxy-attaches-real-creds"
}
}
Then start your proxy in one terminal and openviking-server in another:
# Terminal 1
hermes proxy start
# Terminal 2
openviking-server
OpenViking's VLM calls now flow through your Portal subscription. The embedding model side still needs its own provider. Portal does serve /v1/embeddings, but the model selection depends on what your tier supports; check portal.nousresearch.com/models.
Example: Configuring Karakeep
Karakeep is a bookmark/summarizer application that takes an OpenAI-compatible API for bookmark summarization. In its configuration (typically a .env file):
# Karakeep .env
OPENAI_API_BASE_URL = http://127.0.0.1:8645/v1
OPENAI_API_KEY = any-non-empty-string
INFERENCE_TEXT_MODEL = Hermes-4-70B
The same pattern works for Open WebUI, LobeChat, NextChat, or any other OpenAI-compatible client.
Exposing on LAN
By default the proxy binds to 127.0.0.1 (localhost only). To let other machines on your network use it, start the proxy with:
hermes proxy start --host 0.0.0.0 --port 8645
Be aware: anyone on your network can now use your Portal subscription. The proxy has no authentication of its own; it accepts any bearer token. Use a firewall, VPN, or reverse proxy with proper authentication if you expose this beyond your trusted network.
Future: more OAuth providers
The adapter system is pluggable. Adding a new provider (for example, HuggingFace, GitHub Copilot's chat endpoint, or Anthropic via OAuth) requires implementing the UpstreamAdapter interface in hermes_cli/proxy/adapters/ and registering it in adapters/__init__.py. Providers that are not OpenAI-compatible at the protocol level (such as the Anthropic Messages API) would need a transformation layer, which is out of scope for the current shape of the proxy.
Sources & References
This page was researched from 1 independent source, combined and verified for completeness.
- 1.Subscription ProxyOfficial documentation · primary source
The #1 AI Newsletter
The most important ai updates, guides, and fixes — one weekly email.
No spam, unsubscribe anytime. Privacy policy