Crush + JoinGonka Gateway: agente Charm sui modelli della rete Gonka

Passo 1: installare Crush. I metodi ufficiali dal README del progetto:

# Homebrew
brew install charmbracelet/tap/crush

# npm
npm install -g @charmland/crush

# Arch Linux
yay -S crush-bin

# Windows
winget install charmbracelet.crush

# Go
go install github.com/charmbracelet/crush@latest

Nello stesso README sono descritti i repository dei pacchetti per Debian, Ubuntu, Fedora e RHEL, Nix e Scoop, mentre nella pagina delle release si trovano i binari già pronti. Per verificare: crush --version, che risponderà con una stringa del tipo crush version v0.96.1.

Passo 2: ottenere una chiave. Registrati su gate.joingonka.ai/register, conferma l'indirizzo e crea una chiave con il prefisso jg- nella sezione «Chiavi API». Una sola chiave e un solo saldo valgono per tutti i modelli della rete.

Passo 3: avviare l'installer.

npx @joingonka/setup --tool crush

L'installer chiederà la chiave — non va passata come argomento della riga di comando, per non lasciarla nella cronologia della shell — e farà quattro cose:

• scriverà il provider joingonka in ~/.config/crush/crush.json: tipo openai-compat, indirizzo del gateway, chiave in chiaro e tre modelli della rete con finestre di contesto, limiti di risposta e prezzi per milione di token, che al momento dell'installazione preleva live dal gateway — su questi Crush calcola il costo della sessione. Il file riceverà i permessi 600;
• assegnerà i modelli: nello slot large DeepSeek V4 Flash, nello small MiniMax M2.7, mentre GLM-5.3 Flash resterà nella lista per la selezione manuale. Lo fa solo se lo slot large è vuoto o punta a un nostro modello uscito dalla rete; una scelta diversa viene rispettata, con un suggerimento nell'output su come cambiare;
• verificherà che la scelta abbia effetto: il modello selezionato dall'interfaccia di Crush viene conservato in un file di stato che ha la precedenza sulla configurazione — è l'argomento della sezione su large e small;
• creerà un backup, lascerà invariati gli altri provider e le altre impostazioni e terminerà con una richiesta live al gateway, per verificare subito chiave, indirizzo e modello.

Un altro modello si specifica con il flag --model e le abbreviazioni deepseek, glm o minimax; il modello indicato esplicitamente viene sempre scritto. Le directory non standard sono gestite dall'installer come fa Crush stesso: CRUSH_GLOBAL_CONFIG per la configurazione, CRUSH_GLOBAL_DATA per il file di stato, oltre a XDG_CONFIG_HOME e XDG_DATA_HOME. Per server e script c'è la modalità senza domande, in cui la chiave viene presa da una variabile d'ambiente:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool crush --model glm --non-interactive

Il formato principale di Crush è ormai crushrc, ma l'installer scrive crush.json: tutte le versioni lo comprendono. Se hai già un crushrc, Crush unirà i due file, in caso di chiavi in conflitto vincerà crushrc, che l'installer non tocca.

Tutto ciò che fa l'installer si può scrivere a mano. Ecco un ~/.config/crush/crush.json funzionante — questo file l'abbiamo fatto passare attraverso il gateway:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "joingonka": {
      "name": "JoinGonka (Gonka)",
      "type": "openai-compat",
      "base_url": "https://gate.joingonka.ai/v1",
      "api_key": "jg-your-key",
      "models": [
        { "id": "deepseek-ai/DeepSeek-V4-Flash-0731", "name": "DeepSeek V4 Flash (Gonka)",
          "context_window": 380000, "default_max_tokens": 32768,
          "can_reason": true, "supports_attachments": false },
        { "id": "MiniMaxAI/MiniMax-M2.7", "name": "MiniMax M2.7 (Gonka)",
          "context_window": 200000, "default_max_tokens": 8192,
          "can_reason": false, "supports_attachments": false },
        { "id": "zai-org/GLM-5.3-Flash", "name": "GLM-5.3 Flash (Gonka)",
          "context_window": 390000, "default_max_tokens": 8192,
          "can_reason": true, "supports_attachments": false }
      ]
    }
  },
  "models": {
    "large": { "provider": "joingonka", "model": "deepseek-ai/DeepSeek-V4-Flash-0731" },
    "small": { "provider": "joingonka", "model": "MiniMaxAI/MiniMax-M2.7" }
  }
}

Crush accetta solo JSON rigoroso: un commento o una virgola pendente — e non parte. I campi di prezzo (cost_per_1m_in, cost_per_1m_out e i due campi per la cache) servono solo al contatore dei costi: l'installer vi inserisce il prezzo live del gateway, ma anche senza di essi Crush funziona e mostra zero — solo l'editor con lo schema da $schema li segnalerà come obbligatori.

Lo stesso provider nel formato crushrc — è normale Bash con i comandi integrati di Crush. Il file ~/.config/crush/crushrc:

provider add joingonka \
  --name "JoinGonka (Gonka)" \
  --type openai-compat \
  --base-url "https://gate.joingonka.ai/v1" \
  --api-key "${JOINGONKA_API_KEY:?set JOINGONKA_API_KEY}"

model add joingonka/deepseek-ai/DeepSeek-V4-Flash-0731 \
  --name "DeepSeek V4 Flash (Gonka)" \
  --context-window 380000 --default-max-tokens 32768 --can-reason true

model add joingonka/MiniMaxAI/MiniMax-M2.7 \
  --name "MiniMax M2.7 (Gonka)" \
  --context-window 200000 --default-max-tokens 8192

model add joingonka/zai-org/GLM-5.3-Flash \
  --name "GLM-5.3 Flash (Gonka)" \
  --context-window 390000 --default-max-tokens 8192 --can-reason true

model large joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
model small joingonka/MiniMaxAI/MiniMax-M2.7

Qui il modello si indica nella forma provider/model-id: prima della prima barra c'è il nome del provider, dopo c'è l'identificatore della rete così com'è. La forma ${JOINGONKA_API_KEY:?…} tiene la chiave fuori dal file, ma senza la variabile esportata Crush non parte — meglio un errore all'avvio che richieste con la chiave vuota.

In Crush, il modello non viene selezionato come unico per tutto, ma per due slot:

Il terzo modello di rete, il modello di ragionamento GLM-5.3 Flash, viene scelto per logiche complesse, ricordando che il limite di risposta è 8192 e una parte di esso viene dedicata al ragionamento — i dettagli sono disponibili nella panoramica del modello. Per ogni esecuzione, il modello viene specificato con il nome completo: crush run -m joingonka/zai-org/GLM-5.3-Flash "…". Tutti i nomi disponibili vengono elencati con crush models joingonka.

File di stato. Il modello scelto nell'interfaccia tramite ctrl+l non viene salvato da Crush in crush.json, ma in un file di stato della macchina: ~/.local/share/crush/crush.json, su Windows — %LOCALAPPDATA%\crush\crush.json. Questo file ha la priorità sia sulla configurazione utente che su crushrc: Crush li legge nell'ordine /etc/crush/crush.json → ~/.config/crush/crush.json → ~/.config/crush/crushrc → file di stato, e ogni file successivo sovrascrive il precedente. Sopra di essi ci sono solo le impostazioni del progetto — crush.json o crushrc nella relativa cartella. Dove si trovano i file sulla tua macchina viene mostrato da crush dirs.

Nel nostro test abbiamo aperto la selezione dei modelli — il provider «JoinGonka (Gonka)» è presente con l'etichetta «✓ Configured» — e abbiamo scelto MiniMax M2.7. Crush ha risposto «Large model changed to MiniMax M2.7 (Gonka)» e ha scritto nel file di stato:

{"models":{"large":{"model":"MiniMaxAI/MiniMax-M2.7","provider":"joingonka","max_tokens":8192}}, …}

Ora questo modello ha la precedenza su quanto scritto in crush.json. L'installer riconosce questa situazione e si comporta in modo diverso:

• senza --model non tocca il file di stato — è la tua scelta di lavoro — ma avverte chiaramente con quale modello Crush verrà effettivamente avviato: Heads-up: Crush will still start with joingonka/MiniMaxAI/MiniMax-M2.7, not joingonka/deepseek-ai/DeepSeek-V4-Flash-0731. Farà lo stesso se nell'interfaccia è selezionato GLM-5.3 Flash o un modello di un altro provider;
• con --model esplicito modifica nel file di stato esattamente una voce — models.large — dopo aver salvato una copia, indicando cosa è cambiato. Altrimenti il flag non avrebbe avuto effetto. Dopo tale esecuzione, nel nostro test, Crush si è aperto con il modello specificato nel flag.

Per prima cosa, verifica che Crush veda il provider:

crush models joingonka

La risposta sono tre righe:

joingonka/MiniMaxAI/MiniMax-M2.7
joingonka/deepseek-ai/DeepSeek-V4-Flash-0731
joingonka/zai-org/GLM-5.3-Flash

Poi fai un'esecuzione singola senza interfaccia. Metti nella directory del progetto un file con un bug evidente e chiedi di trovarlo:

crush run -q "Read calc.py and tell me in one sentence whether it has a bug."

L'agente deve chiamare da solo lo strumento di lettura del file e rispondere nel merito, indicando il numero di riga. Nella nostra prova, tutti e tre i modelli della rete hanno trovato il bug; il task ha richiesto 20-40 secondi. Il flag -q nasconde l'indicatore di attesa. In modalità crush run tutte le chiamate agli strumenti vengono approvate automaticamente, quindi avvialo nel tuo progetto. Nell'interfaccia normale (comando crush) il modello attivo è visibile nella barra di stato: ◇ DeepSeek V4 Flash (Gonka) via JoinGonka (Gonka). Crush conserva sessioni e log nella directory .crush del progetto, esclusa da git tramite un proprio .gitignore; i log si stampano con crush logs. Lato gateway, la richiesta è visibile nella dashboard: sezione «Utilizzo», ripartizione «Per modelli» e «Per chiavi».

Se qualcosa è andato storto, la diagnosi di solito si legge direttamente dal messaggio:

Un agente consuma token diversamente da una chat: ad ogni tua frase Crush aggiunge il prompt di sistema e le descrizioni dei suoi strumenti, e un task richiede solitamente più passaggi. Nel nostro test, ogni richiesta al modello contava circa 11,5 mila token in entrata, e il task "leggere un file e trovare l'errore" ha richiesto due o tre richieste e 23-35 mila token, quasi tutti in entrata. Per questo motivo, il prezzo per token è determinante.

Tramite il JoinGonka Gateway, i token costano $0.0069 per milione in entrata e $0.021 per milione in uscita; il prezzo è uguale per tutti i modelli della rete e viene inserito in questa pagina da una fonte live.

Le stime nella colonna di destra sono basate sui prezzi di settembre 2026. Per confronto, ecco come è possibile pagare i modelli in Crush:

Il contatore dei costi nell'interfaccia Crush calcola in base ai campi prezzo della configurazione. Lì viene inserito il prezzo del gateway al momento dell'installazione, mentre il prezzo in dollari nella rete fluttua insieme al corso di GNK, quindi il contatore è solo indicativo. Il consumo esatto e il saldo residuo si trovano nell'area riservata, nelle sezioni "Utilizzo" e "Billing". Il motivo per cui nello slot large viene impostato di default DeepSeek V4 Flash è spiegato in dettaglio nella panoramica del modello.

Permessi. Nell'interfaccia Crush chiede di default il permesso prima di richiamare uno strumento. Il flag --yolo disattiva tutte le domande in una volta, mentre gli strumenti considerati affidabili in modo mirato vengono elencati nel config:

# crushrc
permissions allow view ls grep

# crush.json
"permissions": { "allowed_tools": ["view", "ls", "grep"] }

Ricordiamo che crush run approva tutto da solo. È una proprietà di Crush, non dipende dal provider del modello.

Timeout della richiesta. Crush interrompe la richiesta se dal modello non arriva nessun frammento di risposta per molto tempo: nella versione 0.96.1 sono due minuti di silenzio (la documentazione indica 60 secondi, ma nel codice e nella nostra verifica sono due minuti). I ping di servizio con cui il gateway mantiene la connessione non azzerano questo contatore — l'abbiamo verificato su uno stand locale. Il gateway, nelle ore di carico, attende il primo token dalla rete fino a 150 secondi, quindi conviene aumentare il margine:

# crushrc
option request-timeout 300

# crush.json
"options": { "request_timeout": 300 }

Firme nei commit. I commit e le pull request creati da Crush ricevono di default la riga Assisted-by: Crush:<model> e l'aggiunta «Generated with Crush». Se non serve:

# crushrc
option attribution-trailer-style none
option attribution-generated-with false

# crush.json
"options": { "attribution": { "trailer_style": "none", "generated_with": false } }

Metriche. Crush invia agli sviluppatori statistiche d'uso pseudonimizzate — solo metadati, senza prompt e risposte. Si disattiva con la variabile CRUSH_DISABLE_METRICS=1 o DO_NOT_TRACK=1. Il gateway, da parte sua, non conserva il contenuto dei prompt e delle risposte — nelle statistiche restano solo gli aggregati di consumo.

Il config è codice. Sia crushrc che crush.json vengono eseguiti da Crush con i permessi della vostra shell: $(…) nel campo della chiave verrà eseguito al caricamento, e il crushrc di progetto si attiverà non appena aprirete Crush in quella directory. Non avviate l'agente in un repository altrui senza averne letto i config.