Configurare Hermes Agent con BYOK: guida passo a passo

Cosa significa davvero BYOK in Hermes Agent

Hermes Agent è BYOK by design. Lo punti a qualsiasi provider di cui hai già le credenziali e ogni chiamata di inferenza viene fatturata sul tuo account del provider, non su uno strato intermedio che ci mette un ricarico sui token. Non è un trucco per aggirare un paywall, è la postura predefinita dell'agente: agnostico rispetto al modello, agnostico rispetto al provider, e sbilanciato verso il backend a cui tu ti fidi di dare i tuoi dati.

Due cose confondono all'inizio. Primo, il BYOK di Hermes copre vere chiavi API di LLM (OpenAI, Anthropic, OpenRouter, Kimi, MiniMax e molte altre) e anche endpoint compatibili con OpenAI, il che significa che un vLLM o un Ollama self-hosted contano. Secondo, il BYOK è per singolo backend, non tutto-o-niente. Puoi usare Anthropic per il reasoning e Ollama per riassunti in background a basso costo sullo stesso agente, se configuri entrambi.

Il resto della guida ti porta attraverso la scelta del provider, l'archiviazione sicura della chiave e il cambio in seguito senza rifare tutto il setup.

Perché il BYOK conta più dei "crediti API gratuiti"

Ogni SaaS di IA prima o poi ti chiede di fidarti della sua chiave condivisa opaca. Il BYOK rompe questo schema. Le tue credenziali, la tua fattura, la tua policy di retention, il tuo log di audit. Se la piattaforma sparisce domani, il tuo account provider continua a funzionare.

I vantaggi concreti, ordinati per quanto pesano nei deployment reali di Hermes:

Controllo dei dati. Log lato provider, regole di retention e clausole Zero Data Retention sono governate dal tuo accordo con il provider del modello, non dai default negoziati dal fornitore dell'agente.
Trasparenza sui costi. Nessun ricarico nascosto tra te e il modello. Con OpenRouter vedi lo stesso costo per token che vedresti con una curl diretta.
Nessun lock-in. Cambiare provider è una modifica di due righe nella config, non un progetto di migrazione. Il comando hermes model ti fa passare tra Claude, GPT, Gemini o Llama senza toccare skill né memoria.
Interruttore dalla tua parte. Se una chiave trapela o la fattura schizza, la ruoti dalla dashboard del provider. L'agente si ferma in pochi secondi e nessun altro deve approvare la rotazione.

Per il piano Starter di Hermify, il BYOK è il senso stesso del prodotto. Il piano è pensato attorno a "tu porti la chiave, noi facciamo girare il container". Per questo vale la pena imparare il setup qui sotto anche se pensi di passare all'hosting gestito più avanti.

Passo a passo: configura il tuo primo provider BYOK

Hermes ha bisogno di almeno un provider configurato per partire. Il percorso con meno frizione è OpenRouter (una chiave, centinaia di modelli), ma la meccanica è la stessa per OpenAI, Anthropic e qualsiasi altro backend supportato.

1. Ottieni una chiave dal provider

Scegline uno e genera una chiave dalla dashboard del provider:

OpenRouter su openrouter.ai. La chiave inizia con sk-or-. La migliore scelta di default per il BYOK.
OpenAI su platform.openai.com. La chiave inizia con sk-.
Anthropic su console.anthropic.com. La chiave inizia con sk-ant-.
Kimi, MiniMax, GLM, Nous Portal e altri seguono lo stesso pattern: ti registri, generi una chiave, la copi una volta.
Ollama o vLLM in esecuzione sulla tua macchina. Non serve una chiave, solo l'URL dell'endpoint compatibile OpenAI.

Aggiungi credito (o un metodo di pagamento) sul provider. Se l'account è a zero, Hermes fallirà alla prima chiamata di inferenza con un errore chiaro.

2. Avvia il setup interattivo

Da terminale, sulla macchina dove vive Hermes:

hermes setup

Scegli il provider dalla lista, incolla la chiave e seleziona un modello. Hermes scrive la configurazione al posto tuo.

Se preferisci scriptare, la stessa cosa senza prompt:

hermes config set OPENROUTER_API_KEY sk-or-la-tua-chiave-qui
hermes config set MODEL "anthropic/claude-sonnet-latest"

Il prefisso ~ in un identificativo di modello (~anthropic/claude-sonnet-latest) significa "ultima versione di questa famiglia", così non devi rincorrere le nuove snapshot a mano.

3. Sappi dove vive la chiave

Hermes tiene segreti e configurazione in file separati, di proposito:

I segreti finiscono in ~/.hermes/.env (permessi 600, così solo l'utente può leggerlo).
Nome del provider, modello e feature flag finiscono in ~/.hermes/config.yaml e sono al sicuro da versionare.

Questa divisione conta. Puoi versionare config.yaml in un repo privato o nei tuoi dotfile e riprodurre un'installazione Hermes su un'altra macchina, e aggiungere la chiave lì a partire da una variabile d'ambiente o da un secret manager senza scriverla mai in chiaro sul disco.

Se versioni la config, aggiungi ~/.hermes/.env al tuo .gitignore. Se usi un secret manager (1Password CLI, doppler, sops, Bitwarden), puoi generare il .env al boot invece di lasciare la chiave su disco in modo permanente.

4. Verifica che funzioni

Manda uno smoke test attraverso Hermes:

hermes chat "di' ciao e dimmi che modello sei"

Se la chiave è sbagliata, l'account è senza credito o l'endpoint è irraggiungibile, l'errore ti dice quale. Correggi e rilancia. Non passare a skill, cron o tuning della memoria finché il provider non risponde pulito.

Scegliere il provider giusto per il tuo setup

Non sei incastrato nella prima scelta. Ma la prima conta, perché fissa il tetto del lavoro di memoria, tool calling e contesto lungo che Hermes proverà a fare.

Vuoi zero frizione, "che funzioni e basta": OpenRouter con ~anthropic/claude-sonnet-latest. Una chiave, una fattura, cambi di modello facili.
Hai già un account OpenAI o Anthropic: usa il provider diretto. Costo per token leggermente più basso rispetto al passaggio via OpenRouter, ma senza fallback tra provider.
Vuoi restare sull'infrastruttura Nous Research: Nous Portal è il percorso ufficialmente benedetto e si sposa in modo naturale con i system prompt di Hermes.
Vuoi girare in locale: Ollama o vLLM come endpoint compatibile OpenAI. Costo per token zero, richiede una macchina con GPU e ha bisogno di un modello con vero supporto ai tool call per essere utile all'agente.
Vuoi isolamento stretto dei dati: Anthropic diretto (Zero Data Retention su richiesta) o un endpoint self-hosted. Non passare per aggregatori se questa è la tua priorità.

Hermes ha bisogno di un modello con almeno 64K token di contesto, perché i file di memoria persistente (MEMORY.md, USER.md, skill) vengono iniettati a ogni chiamata. I modelli con contesto piccolo tagliano il contesto in silenzio, e questo rompe il loop di memoria che rende Hermes diverso da un chatbot senza stato.

Se vuoi un approfondimento su come scegliere il modello vero e proprio, guarda come configurare Hermes Agent con OpenRouter.

Errori di configurazione da evitare

Alcuni pattern bruciano chi fa il primo setup BYOK:

Commitare il file .env. L'errore più comune. Nemmeno un repository "privato" su GitHub è un posto sicuro per chiavi sk-. Aggiungi .env al .gitignore dal giorno zero.
Scegliere un modello senza supporto ai tool call. Alcuni modelli economici su OpenRouter non sanno chiamare tool. Hermes ne ha bisogno per scrittura file, fetch web, task pianificati e MCP. Se le skill smettono di funzionare in silenzio, controlla le capability flag del modello.
Sotto-finanziare l'account provider. I provider mettono in pausa le richieste quando il credito scende sotto una soglia. Imposta una ricarica automatica su OpenRouter o un alert di saldo basso su OpenAI, così un cron lungo di Hermes non muore alle 3 di notte.
Salvare la chiave nella history della shell. hermes config set OPENROUTER_API_KEY sk-or-... viene scritto in .bash_history di default. Preferisci hermes setup (interattivo, senza history) oppure metti uno spazio davanti al comando se la tua shell è configurata per saltare quelle righe.
Pensare che una chiave copra tutto. I tool MCP che hanno bisogno di credenziali proprie (un token GitHub, una chiave Notion) sono slot BYOK separati. La chiave del LLM non li sblocca.
Non ruotare. Metti un promemoria in calendario ogni 90 giorni per ruotare la chiave del provider. hermes config set sovrascrive il vecchio valore in modo pulito.

Se ti blocchi, il troubleshooting di Hermes Agent su Telegram copre i modi di fallimento comuni da capo a fondo.

Cosa cambia con l'hosting gestito

Tutto quello che precede è come si presenta un'installazione self-hosted di Hermes. Se fai il deploy tramite Hermify, il modello BYOK è identico (la tua chiave, la tua fattura, i tuoi dati), ma la meccanica si sposta in una dashboard:

Incolli la chiave OpenRouter, OpenAI o Anthropic una volta nell'onboarding.
Hermify la cifra a riposo e la inietta nel tuo container al boot. Non compare mai nei log, non viene mostrata di nuovo dopo il salvataggio e si ruota in modo pulito su richiesta.
Cambi modello dalla dashboard senza fare SSH da nessuna parte. Il cambio ha effetto al prossimo restart dell'agente, che è a un clic di distanza.
Il piano Starter è BYOK-only per design. Pro e Dedicated includono una chiave gestita se preferisci saltare la registrazione sul provider, ma puoi comunque portare la tua se ti va.

Il punto è che il BYOK non è una caratteristica esclusiva del self-hosting. È una postura: le tue credenziali, i tuoi dati, il tuo interruttore. L'hosting gestito la conserva, si occupa solo dell'operatività attorno.

Comincia

Se sei in self-hosted, esegui hermes setup, incolla la chiave e sei a posto. Se vuoi lo stesso modello BYOK senza la manutenzione del container, inizia con Hermify e sei online su Telegram in circa un minuto.

In ogni caso, tieni la chiave dal tuo lato della recinzione. Ecco a cosa serve il BYOK.