hermes proxy Command — Complete Reference & Examples

Overview

hermes proxy runs a local HTTP server that forwards OpenAI-compatible requests to an OAuth-authenticated provider. External apps can point at the proxy with any bearer token; the proxy attaches your real Hermes credentials, so any OpenAI-compatible client can use Hermes as a drop-in backend.

hermes proxy <start|status|providers>

Subcommands

start — Run the proxy in the foreground

hermes proxy start
hermes proxy start --provider nous --host 127.0.0.1 --port 8645
hermes proxy start --provider xai --port 9090

status — Show which proxy upstreams are ready

hermes proxy status

Prints the readiness state of configured upstream providers so you know whether the proxy can serve requests before you point a client at it.

providers — List available proxy upstream providers

hermes proxy providers

Shows the providers the proxy can use (currently nous and xai).

Common Scenarios

Use Hermes from another OpenAI-compatible tool

hermes proxy start --port 8080
# In the other tool:
#   API base: http://localhost:8080/v1
#   API key:  any-value (the proxy handles auth)

Expose the proxy on your LAN

hermes proxy start --host 0.0.0.0 --port 8645

Switch upstream provider

hermes proxy providers
hermes proxy start --provider xai

Test the proxy with curl

hermes proxy start --port 8645 &
curl http://localhost:8645/v1/models

Tips

• The proxy is local by default (127.0.0.1) — it does not expose anything to the internet unless you change --host.
• Any bearer token value works in the client; the proxy attaches your real Hermes OAuth credentials.
• The proxy must run in the foreground; start it in a dedicated terminal or under a process manager for long-lived use.
• Use hermes proxy status to verify upstream readiness before connecting a client.