Proxy di Abbonamento — Gateway Condiviso

Immaginalo come un abbonamento in palestra: non daresti la tua tessera a un amico rischiando di perderla. Piuttosto, gli faresti un ingresso giornaliero. Il Subscription Proxy è esattamente questo: un lasciapassare per i tuoi abbonamenti AI.

Il Problema che Risolve

Molte app AI — come OpenViking o Open WebUI — parlano il formato API di OpenAI. Potresti anche dare loro direttamente la chiave del tuo abbonamento a Nous Portal, ma è rischioso (potrebbero farla trapelare) e fastidioso (le chiavi scadono). Il proxy risolve tutto questo facendo girare un piccolo server locale. Ogni richiesta dalla tua app passa attraverso di esso, e il proxy aggiunge automaticamente le tue credenziali reali. Le tue app possono usare qualsiasi chiave finta — il proxy sostituisce quella vera dietro le quinte.

Differenze con l’API Server

	API Server	Subscription Proxy
Cosa offre	Agenti Hermes completi (strumenti, memoria, abilità)	Inferenza del modello pura
Ideale per	“Usare Hermes come backend per chat”	“Condividere il tuo abbonamento Portal con altre app”
Autenticazione	Richiede la tua API_SERVER_KEY	Qualsiasi bearer token (il proxy lo sostituisce)
Chiamate strumento	Supportate	Non supportate (solo pass-through)

In una frase: Usa l’API server quando vuoi un agente; usa il proxy quando vuoi solo il modello.

Tre Passi per Iniziare

1. Accedi una Volta

hermes portal

Si apre un browser con la pagina di autorizzazione di Nous Portal. Dopo l’accesso, Hermes salva il refresh token in ~/.hermes/auth.json.

2. Avvia il Proxy

hermes proxy start

Vedrai un output simile a questo:

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.

Vuoi che giri in background? Usa tmux, nohup o un servizio systemd.

3. Configura la Tua App

Qualsiasi app compatibile con OpenAI ha bisogno solo di tre impostazioni:

Base URL:   http://127.0.0.1:8645/v1
API key:    qualsiasi cosa (es. "sk-unused")
Model:      Hermes-4-70B    # oppure Hermes-4.3-36B, Hermes-4-405B

Il proxy ignora qualsiasi chiave tu inserisca e la sostituisce con la tua vera credenziale Portal — e la aggiorna automaticamente prima che scada.

Controlla lo Stato

hermes proxy status

Dovresti vedere ready. Se dice not logged in, esegui di nuovo hermes portal. Se dice credentials need attention, il tuo refresh token è stato revocato (di solito perché hai effettuato il logout sul sito di Portal) — basta rifare l’accesso.

Endpoint Supportati

Il proxy inoltra solo i percorsi che il server upstream supporta effettivamente; tutto il resto restituisce un 404 con un messaggio chiaro:

Percorso	Scopo
/v1/chat/completions	Completamenti chat (streaming supportato)
/v1/completions	Completamenti di testo legacy
/v1/embeddings	Vettori di embedding
/v1/models	Elenca i modelli disponibili

Riepilogo e Consigli Pratici

Il subscription proxy è un adattatore sicuro: permette ad altre app di condividere il tuo abbonamento senza mai esporre la tua chiave reale, e gestisce la scadenza per te. Attualmente supporta Nous Portal e xAI (Grok), con altri provider in arrivo.

Un consiglio pratico: Se usi più app, dai a ciascuna una chiave finta diversa (es. sk-app1, sk-app2). In questo modo, i log del proxy mostrano esattamente quale app sta facendo quale richiesta — rendendo il debug molto più facile. Inoltre, il proxy ascolta solo su 127.0.0.1 di default. Non cambiarlo in 0.0.0.0, altrimenti qualsiasi dispositivo sulla tua rete potrebbe usare il tuo abbonamento.

---