Subscription Proxy for OpenAI-Compatible Apps

The Hermes subscription proxy is a local OpenAI-compatible endpoint that attaches and refreshes Hermes-managed provider credentials for external applications. It serves raw model inference, not the full Hermes agent.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/features/subscription-proxy

Proxy or API server?

Use the subscription proxy when an application needs chat completions, completions, embeddings, or model discovery through a supported subscription. Use the Hermes API server when the client should talk to the actual agent with tools, memory, and skills.

Start with a loopback listener. The proxy accepts any bearer from the local client because it replaces that value with the real upstream credential. That convenience becomes a serious boundary if the listener is exposed to a LAN: anyone who can reach it may consume the subscription.

Integration checklist

Authenticate the supported provider through Hermes first.
Run hermes proxy status and confirm the adapter is ready.
Keep the listener on 127.0.0.1 by default.
Point the client at the proxy’s /v1 base URL.
Choose a model available to the subscription tier.
Test streaming and non-streaming separately when the client uses both.
Monitor provider quota across every application using the proxy.
Add a firewall, VPN, or authenticated reverse proxy before any network exposure.

Pitfalls

Expecting Hermes tools or memory through the raw inference proxy.
Treating the client’s dummy API key as an access-control mechanism.
Binding to all interfaces on a shared network without protection.
Assuming every OpenAI API path is forwarded.
Forgetting that all clients share the same upstream rate limits and quota.

Verification steps

Run hermes proxy providers and confirm the intended adapter exists.
Run hermes proxy status and resolve any login warning.
Start the proxy on loopback.
Request /v1/models from the local client.
Send one non-streaming and one streaming chat completion.
Confirm an unsupported path returns a clear 404.
Verify the port is not reachable from another host unless that exposure was deliberately secured.