DeepSeek Harness: il tuo provider tramite JoinGonka Gateway

L'harness è tutto ciò che circonda il modello nel lavoro agentico: il ciclo «richiesta → chiamata allo strumento → risultato → passo successivo», gli strumenti per file e terminale, i permessi e le conferme, il log della sessione, la compressione del contesto. DeepSeek Harness lo compone dai plugin: l'architettura «everything is a plugin» è costruita sul framework Cordis, e qualsiasi nodo — dallo strumento all'adattatore del modello — si sostituisce senza toccare il core. Il codice è aperto con licenza MIT.

Non serve installare nulla: basta Node.js (la serie 22 dalla 22.19 in poi oppure la 24 e successive):

npx @deepseek-ai/dsh web

Il comando avvia la Web UI su http://127.0.0.1:3080 e la apre nel browser; se lanciato via SSH, l'indirizzo viene solo stampato nel terminale. Il flag --no-open avvia il server senza browser, --port cambia la porta. La directory da cui viene lanciato dsh diventa quella di lavoro predefinita, ma l'interfaccia avvierà una sessione solo dopo la scelta esplicita del workspace.

Il layer dei modelli è composto da due adattatori. Quello diretto va all'API ufficiale del vendor. Quello multi-provider — dsh-llm-pi-ai — è costruito sulla libreria pi-ai, la stessa che sta alla base dell'agente da terminale Pi; tramite esso si collegano sia i provider integrati nel catalogo sia qualsiasi endpoint proprio. Per questo i nomi dei campi nelle impostazioni — api, contextWindow, maxTokens — coincidono con quelli familiari da Pi.

Sulla maturità. Il README del progetto si apre con un avviso: developer preview, iterazioni rapide, breaking changes. Un documento separato, SAFETY.md, precisa che non è stato effettuato alcun audit di sicurezza e che l'agente esegue comandi generati dal modello. La conclusione pratica è semplice: lanciate dsh in un container, in una macchina virtuale o sotto un account separato, e tenete backup di tutto ciò che può raggiungere.

Passo 1: la chiave. Registrati su gate.joingonka.ai/register: dopo la verifica dell'indirizzo sul conto arriveranno 3M token gratuiti. Nella dashboard apri la sezione «Chiavi API» e crea una chiave con il prefisso jg-. Conviene creare una chiave dedicata per l'harness: così il suo traffico sarà visibile nelle statistiche su una riga separata.

Passo 2: la prima schermata. Dopo la notifica sullo stato di test (pulsante Continue), dsh ti chiederà di inserire la chiave dell'API ufficiale («Add an API key to get started»). Non è obbligatoria: premi Configure later.

Passo 3: il provider. Apri Settings → Models e scegli Add a custom provider. I campi del modulo:

Passo 4: i modelli. Nel blocco Models premi Fetch available models: dsh chiederà al gateway l'elenco e aprirà la finestra «Choose models to add». Nella nostra prova conteneva tutti e tre i modelli della rete — MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 e zai-org/GLM-5.3-Flash — e dopo Add selected l'harness ha assegnato automaticamente a ciascuno la finestra di contesto e il limite di risposta, in base ai dati del gateway. Non resta che premere Create provider.

Passo 5: la scelta del modello. Chiudi le impostazioni, premi Choose workspace e aggiungi la cartella del progetto. I modelli del nuovo provider compariranno nel selettore; quello scelto diventa il modello predefinito per le nuove sessioni.

dsh conserva la chiave separatamente dalle impostazioni: nel file ~/.dsh/.credentials.yaml con permessi di accesso riservati al proprietario. In settings.yaml resta solo il nome del riferimento ad essa — nella nostra prova JOINGONKA_API_KEY, in base all'identificatore del provider.

Quale protocollo scegliere. Il gateway parla tutti e tre; cambiano l'indirizzo di base e i vantaggi collaterali:

In dsh un provider parla un solo protocollo, quindi il secondo protocollo richiede un secondo provider con un Provider ID diverso. Per l'uso quotidiano basta la prima opzione; nella nostra prova il ciclo agentico con chiamata degli strumenti ha funzionato su tutti e tre.

Il modulo Models scrive in un normale documento YAML — $DSH_HOME/settings.yaml, per impostazione predefinita ~/.dsh/settings.yaml. Puoi modificarlo direttamente: il pulsante Open configuration file in cima alle impostazioni apre il file, e gli adattatori lo rileggono alla richiesta successiva — non serve riavviare. Ecco la versione completa per la rete Gonka:

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

Ecco cosa conta davvero:

• apiKeyEnv non è la chiave, ma il nome del riferimento ad essa. dsh cerca il valore in quest'ordine: la variabile d'ambiente al momento dell'avvio, poi .credentials.yaml (dove scrive il modulo), poi .env nella directory di avvio, infine ~/.dsh/.env. Se configuri l'harness senza browser, ti basta una riga JOINGONKA_API_KEY=jg-your-key in ~/.dsh/.env con permessi 600. Una variabile esportata dopo l'avvio non sarà visibile al processo già in esecuzione.
• Specifica sempre contextWindow e maxTokens. Per un modello che dsh non conosce, vengono assegnati 262.144 e 32.768 token — valori che non corrispondono ai limiti reali. Il maxTokens impostato diventa anche il limite di risposta predefinito per ogni richiesta.
• reasoningEfforts sono i livelli di ragionamento per il menu Effort. Un modello inserito manualmente non ha livelli, e il menu non compare. Per GLM-5.3 Flash l'interruttore è binario: il valore low disattiva il ragionamento, qualsiasi altro lo mantiene completo. Per questo al livello off è associato low, mentre high passa così com'è. Nel nostro test con off non c'erano affatto blocchi di ragionamento, con high sono tornati.
• agent-default-model è il modello per i nuovi agenti, inclusa la modalità headless. Lo stesso effetto si ottiene scegliendo il modello nell'interfaccia; qui puoi anche aggiungere reasoningEffort.

Gli interruttori compat che la documentazione di dsh consiglia per i gateway rigidi (supportsDeveloperRole: false, maxTokensField: max_tokens) qui non servono: JoinGonka Gateway accetta sia il ruolo developer sia il campo max_completion_tokens.

L'installer npx @joingonka/setup non configura questo harness: tutta la connessione si riduce al modulo della sezione precedente o al frammento YAML qui sopra.

Il modo più rapido per verificare l'integrazione è una singola esecuzione dalla directory con il codice. Metti accanto un piccolo file con un errore evidente e chiedi di trovarlo:

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

La risposta finale viene stampata su stdout, il ragionamento su stderr con il tag dsh: reasoning:. L'agente deve invocare da sé lo strumento di lettura del file e rispondere nel merito: nella nostra esecuzione ciascuno dei tre modelli della rete ha indicato la riga errata. Significa che il ciclo completo «richiesta → invocazione strumento → risultato → risposta» attraverso il gateway si compone correttamente.

La seconda metà della verifica è lato gateway. Nella dashboard apri «Utilizzo»: lì si vedono le richieste per ore e giorni, la ripartizione per modello e per chiave. È comparsa una riga con la chiave dell'harness e un timestamp recente dell'ultima richiesta — il traffico passa davvero attraverso il gateway.

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

Il prezzo per tutti i modelli della rete è uguale, quindi la scelta riguarda il comportamento e non il budget. Di seguito sono riportati i limiti e il modo in cui i modelli si sono comportati nel nostro test dsh sullo stesso compito: leggere un file e trovarne l'errore.

Il consiglio predefinito è DeepSeek V4 Flash: il lavoro degli agenti raggiunge rapidamente i limiti di contesto e la lunghezza della correzione, e qui c'è margine su entrambi i parametri. Quando il compito richiede di pensare a una logica complessa, passare a GLM-5.3 Flash e mantenere il livello di ragionamento high; per modifiche rapide lo stesso provider lo fornisce con il livello off. MiniMax M2.7 è un'opzione stabile per compiti brevi, quando il processo di ragionamento visibile non disturba. Il modello si cambia nel selettore dell'interfaccia o tramite la stringa model nel blocco agent-default-model.

La composizione della rete è determinata dal voto dei partecipanti e cambia nel tempo; l'elenco aggiornato con i limiti è sempre disponibile tramite GET https://gate.joingonka.ai/v1/models — lo stesso utilizzato dal pulsante Fetch available models.

Gli strumenti agenti consumano token in modo diverso rispetto a una chat: a ogni tua frase l'harness aggiunge un prompt di sistema e le descrizioni di tutti gli strumenti, quindi conduce un dialogo a più passaggi con il modello. Nella nostra esecuzione, il compito "leggi il file e trova l'errore" ha richiesto da due a tre passaggi e tra 14 e 22 mila token, con quasi tutto questo in input: circa settemila token vengono utilizzati a ogni passaggio prima ancora della tua domanda. È il prezzo normale per l'autonomia, ed è proprio per questo che il prezzo per token è determinante.

Tramite JoinGonka Gateway, i token costano $0.0069 per milione in input e $0.021 per milione in output: il prezzo è uguale per tutti i modelli della rete e viene inserito in questa pagina da una fonte in tempo reale. Ordine di grandezza dei prezzi a settembre 2026:

Il pagamento avviene in base al consumo effettivo, senza abbonamenti e senza quote sul numero di richieste; il saldo e il consumo giornaliero sono visibili nell'area riservata.

Versione. Finché il progetto è in stato di developer preview, dopo ogni aggiornamento verifica che il provider sia presente e, per la riproducibilità, fissa la versione direttamente nel comando: npx @deepseek-ai/[email protected] web.

Permessi. Le nuove sessioni funzionano per impostazione predefinita in modalità Workspace Write — scrittura all'interno della directory di lavoro; per le operazioni che superano la policy, l'interfaccia richiede una conferma. La modalità può essere modificata in Settings → General.

Riprova. In caso di singolo errore di rete, dsh ripete la richiesta autonomamente — fino a cinque volte, secondo la documentazione — quindi un breve picco di carico sulla rete solitamente passa inosservato.

Privacy. Il gateway non memorizza il contenuto dei prompt e delle risposte: nelle statistiche rimangono solo i dati aggregati del consumo. L'agente legge i file del progetto localmente, sulla tua macchina.

Se hai bisogno di lavorare con immagini — uno screenshot dell'interfaccia, uno schema in foto — configura accanto un secondo provider con un modello dotato di visione: dsh gestisce più provider simultaneamente, mentre i modelli della rete Gonka sono testuali.

DeepSeek Harness non è l'unico agente rilasciato dal laboratorio sviluppatore dei modelli: Z.ai, autori di GLM, ha l'ambiente ZCode, mentre MiniMax ha il terminale MiniMax Code. Entrambi si collegano allo stesso gateway con la stessa chiave.