Subscription Proxy — Shared Gateway

Think of it like a gym membership: you wouldn’t hand your friend your actual card and risk losing it. Instead, you’d get them a guest pass. Subscription Proxy is exactly that guest pass for your AI subscriptions.

The Problem It Solves

Many AI apps — like OpenViking or Open WebUI — speak the OpenAI API format. You could give them your Nous Portal subscription key directly, but that’s risky (they could leak it) and annoying (keys expire). The proxy fixes this by running a tiny local server. Every request from your app goes through it, and the proxy automatically attaches your real credentials. Your apps can use any fake key — the proxy swaps in the real one behind the scenes.

How It Differs from the API Server

	API Server	Subscription Proxy
What it provides	Full Hermes agents (tools, memory, skills)	Pure model inference
Best for	“Use Hermes as a chat backend”	“Share your Portal subscription with other apps”
Auth	Needs your API_SERVER_KEY	Any bearer token (proxy replaces it)
Tool calling	Supported	Not supported (pure pass-through)

In one sentence: Use the API server when you want an agent; use the proxy when you just want the model.

Three Steps to Get Started

1. Log In Once

hermes portal

A browser opens with the Nous Portal authorization page. After you log in, Hermes stores the refresh token in ~/.hermes/auth.json.

2. Start the Proxy

hermes proxy start

You’ll see output like:

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.

Want it running in the background? Use tmux, nohup, or a systemd service.

3. Configure Your App

Any OpenAI-compatible app just needs three settings:

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 whatever key you type and replaces it with your real Portal credential — and auto-refreshes it before it expires.

Check Status

hermes proxy status

You want to see ready. If it says not logged in, run hermes portal again. If it says credentials need attention, your refresh token was revoked (usually because you logged out on the Portal website) — just re-login.

Supported Endpoints

The proxy only forwards paths the upstream actually supports; everything else returns a 404 with a clear message:

Path	Purpose
/v1/chat/completions	Chat completions (streaming supported)
/v1/completions	Legacy text completions
/v1/embeddings	Embedding vectors
/v1/models	List available models

Who Can Reach It (Security Defaults)

By default the proxy binds 127.0.0.1 (localhost only). It also refuses requests whose Host header is not its own address (localhost, 127.0.0.1, [::1], or the bound IP), and it blocks any browser request coming from another site (an Origin other than its own, or a Sec-Fetch-Site of cross-site/same-site). The practical effect: a web page open in your browser cannot use the proxy. Clients like SDKs and curl send neither header, so they are unaffected.

If you bind to a wildcard address to let other machines on your network use it, the Host check is skipped (any name may reach it), so instead it refuses every request a web page makes (any Origin, or a Sec-Fetch-Site other than none). In other words, browsers cannot use a wildcard-bound proxy at all. Note also that the proxy has no auth of its own — it accepts any bearer token.

Summary & Practical Tips

The subscription proxy is a safe adapter: it lets other apps share your subscription without ever exposing your real key, and it handles expiration for you. Currently it supports Nous Portal and xAI (Grok), with more providers on the way.

One practical tip: If you use multiple apps, give each one a different fake key (like sk-app1, sk-app2). That way, the proxy logs show exactly which app is making which requests — making debugging much easier. Also, the proxy listens only on 127.0.0.1 by default. Don’t change it to 0.0.0.0, or any device on your network could use your subscription too — and remember the proxy itself has no authentication, so anyone who can reach it can use it.