Come installare DeepSeek Harness in 10 minuti (e puntarlo a qualsiasi modello tu voglia)

Installare DeepSeek Harness richiede un unico comando. Trenta secondi dopo ti trovi davanti a un'interfaccia bella e completamente vuota su http://127.0.0.1:3080, e nessuno ti ha detto cosa fare dopo.

Il README è notoriamente scarno. Il paper su Cordis a cui collega parla di composabilità spazio-temporale. Tu volevi solo che la cosa leggesse il tuo codice.

Questa guida parte da quella schermata vuota. Riceverai il comando di installazione, sì, ma la parte che ti costa un pomeriggio è collegare un provider di modello, e ci sono tre valori predefiniti in quel passaggio che silenziosamente rompono i modelli DeepSeek e buttano via il 75% della finestra di contesto. Quasi nessuno li documenta.

Punti chiave

• npx @deepseek-ai/dsh web è l'intera installazione. Node.js ^22.19.0 o >=24.0.0 è l'unico prerequisito.
• DeepSeek Harness è un'infrastruttura, non un modello. Viene fornito con zero credenziali, quindi non fa nulla finché non colleghi un provider.
• Qualsiasi endpoint compatibile con OpenAI funziona, inclusa l'API di DeepSeek stessa, un gateway o un server Ollama locale.
• Quando aggiungi un provider personalizzato, l'infrastruttura deduce il dialetto di pensiero dal tuo URL di base. Se sbaglia, reasoning_content si rompe.
• I modelli dichiarati manualmente impostano per impostazione predefinita una finestra di contesto di 262.144, quindi la finestra completa di V4 da 1.048.576 rimane disattivata finché non la specifichi diversamente.

Terminale che mostra test verdi superati accanto a un'infrastruttura modulare luminosa, che illustra come installare DeepSeek Harness

La versione in 60 secondi di ciò che stai costruendo

Ecco il risultato prima di qualsiasi teoria. Tre file in una cartella vuota, un prompt incollato, e l'agente legge il codice, esegue pytest, osserva due test fallire, cambia un singolo carattere e riesegue fino a quando la suite è tutta verde.

DeepSeek Harness legge fizzbuzz.py, esegue pytest, corregge l'errore off-by-one e riesegue fino a 3 superati

Il ciclo completo: leggi, esegui, diagnostica, correggi, riesegui. Ogni passaggio finisce in un log di sessione append-only che puoi riprodurre in seguito.

Questa è la demo che costruiremo insieme nel Passaggio 6. È volutamente abbastanza piccola da poter essere riprodotta in una directory di prova, e non dipende da alcun repository esterno che potrebbe cambiare la prossima settimana.

Perché la maggior parte dei tentativi di installare DeepSeek Harness si blocca al secondo passaggio

L'installazione è davvero banale. L'impasse arriva subito dopo, ed è una scelta progettuale piuttosto che un bug: DeepSeek Harness non include chiavi, nessun provider predefinito e nessun modello in bundle.

DeepSeek ha reso open source il progetto il 13 agosto 2026 con licenza MIT, e ha avuto un'impennata. Al 17 agosto 2026 il repository conta 144.361 stelle e 14.689 fork (GitHub, agosto 2026), il che significa molte persone che arrivano alla stessa schermata vuota nella stessa settimana.

Il thread di Hacker News della settimana di lancio cattura la reazione divisa. Alla gente piace la trasparenza: tutto ciò che il modello vede viene registrato in un log di sessione append-only, e un commentatore ha notato che "i modelli USA non ti permettono di vedere quello." Le lamentele sono altrettanto coerenti. "Il README è piuttosto scarno oltre alle istruzioni di installazione," ha scritto uno sviluppatore, e il paper di Cordis ha ricevuto il verdetto che sembra "insalata di parole" (Hacker News, agosto 2026).

Quindi le quattro cose che effettivamente bloccano le persone sono tutte successive all'installazione:

• Node è troppo vecchio, quindi npx fallisce prima che inizi qualsiasi cosa.
• La porta 3080 è già occupata da un altro server di sviluppo.
• Il provider personalizzato restituisce 401, o l'elenco dei modelli torna vuoto.
• Il modello si connette ma l'output del ragionamento arriva danneggiato, o file lunghi esauriscono la finestra di contesto prematuramente.

I passaggi da 1 a 5 di seguito sono mirati direttamente a questi quattro punti.

Prima di installare DeepSeek Harness: scegli un modello e una chiave

Rispondi prima: l'infrastruttura stessa è gratuita e locale, ma non farà nulla di utile finché non le fornisci un URL di base compatibile con OpenAI, una chiave e almeno un ID modello. Decidi questo prima di installare e l'intera configurazione richiede dieci minuti.

Tutto avviene in una scheda del browser su 127.0.0.1:3080. Puoi scegliere tra tre percorsi, e tutti e tre funzionano.

Tabella B: opzioni di accesso al modello che funzionano con DeepSeek Harness oggi

Due cose da sapere prima di scegliere. L'API first-party di DeepSeek è passata a fatturazione con picco e fuori picco, dove le ore di picco sono 01:00-04:00 e 06:00-10:00 UTC, e fuori picco è esattamente la metà del picco (Documentazione API DeepSeek, agosto 2026). Il prezzo per input con cache hit è estremamente basso, quindi un carico di lavoro che rilegge ripetutamente lo stesso contesto può essere molto economico con il first-party.

Un gateway scambia questo per prevedibilità. Atlas Cloud serve gli stessi modelli DeepSeek a tariffa fissa senza sovrapprezzo di picco e senza abbonamento, che è l'esempio che userò nella configurazione qui sotto perché non richiede un metodo di pagamento regionale. Sostituisci con il percorso che corrisponde alla tua situazione; la forma di configurazione è identica per tutti.

Come installare DeepSeek Harness, passo dopo passo

Ci sono tre modi per iniziare. Scegli una riga, poi segui i passaggi.

Tabella A: metodi di installazione a confronto

Passaggio 1: verifica i prerequisiti prima di installare DeepSeek Harness

Il singolo fallimento più comune è una versione di Node che sembra abbastanza recente ma non lo è. Il repository richiede ^22.19.0 || >=24.0.0. Nulla sulla linea 23.x è qualificato a qualsiasi livello di patch.

bashCopy
1node -v      # deve essere >= 22.19.0 sulla 22.x, o >= 24.0.0
2npm -v
3

Se node -v stampa 22.14 o 20.x, aggiorna prima di procedere. Hai bisogno di pnpm solo se intendi compilare da sorgente o creare plugin:

bashCopy
1npm install -g pnpm
2

Passaggio 2: installa DeepSeek Harness con un solo comando

Questa è l'intera installazione. Scarica e avvia il profilo web in un colpo solo.

bashCopy
1npx @deepseek-ai/dsh web
2

Apri http://127.0.0.1:3080. Se quella porta è già occupata, il launcher passa tutti i flag che non riconosce direttamente al profilo, quindi puoi spostarla:

bashCopy
1npx @deepseek-ai/dsh web --port 8080
2

Quello che ottieni è una shell vuota. Nessun provider, nessun modello, nessuna chiave. È previsto, ed è qui che la maggior parte delle guide si ferma.

L'interfaccia web di DeepSeek Harness su 127.0.0.1:3080 subito dopo l'installazione, senza provider o modello configurato

Installazione completata, e completamente inerte. Da qui in poi è solo cablaggio.

Passaggio 3: ottieni una chiave API per DeepSeek Harness

Qualunque percorso tu abbia scelto dalla Tabella B, hai bisogno di una chiave e un URL di base. Per il percorso first-party, registrati su platform.deepseek.com e crea una chiave lì. Le opzioni di fatturazione variano in base alla regione, quindi controlla che il tuo metodo di pagamento sia supportato prima di impegnarti.

Per il percorso gateway usato in questo walkthrough, crea una chiave nella dashboard di Atlas Cloud sotto API Keys, quindi esportala in modo che l'infrastruttura possa leggerla senza memorizzarla in un file di impostazioni:

bashCopy
1export ATLASCLOUD_API_KEY="sk-your-key-here"
2

La pagina delle chiavi API della dashboard di Atlas Cloud con una chiave appena creata, parzialmente mascherata

Copia la chiave una volta. Non verrà più mostrata dopo aver lasciato la pagina.

Passaggio 4: aggiungi il tuo provider di modello a DeepSeek Harness

Nell'interfaccia, vai su Impostazioni, poi Modelli, quindi Aggiungi un provider personalizzato. Il modulo richiede un ID provider, un nome visualizzato, un URL di base, un protocollo API, una credenziale e almeno un modello.

Un avvertimento che i documenti hanno ragione a ripetere: l'ID provider è permanente. Viene scritto nelle richieste, nelle sessioni salvate, nei valori predefiniti del modello e nei riferimenti alle credenziali. Se in seguito non ti piace, la tua unica opzione è creare un nuovo provider ed eliminare quello vecchio.

Se il recupero dei modelli restituisce 401, la chiave è sbagliata. Se restituisce un elenco vuoto, l'endpoint semplicemente non espone un indice dei modelli, il che è innocuo: digita manualmente l'ID del modello e vai avanti.

Il modulo "Aggiungi un provider personalizzato" compilato, con l'URL di base, il protocollo API e il controllo "Recupera modelli" evidenziati

I tre campi che decidono se il passaggio successivo funziona: URL di base, protocollo e l'elenco dei modelli.

Passaggio 5: I tre valori predefiniti di DeepSeek Harness che rompono silenziosamente i modelli DeepSeek

Questa è la parte che nessun'altra guida all'installazione copre, ed è il motivo per cui la tua configurazione potrebbe sembrare connessa ma comportarsi in modo strano.

Il livello LLM dell'infrastruttura deduce quale dialetto di pensiero parlare dall'URL del tuo endpoint. I documenti interni sono brutali sulla conseguenza: "pi-ai indovina dall'URL dell'endpoint; l'URL di un gateway privato non dice nulla, quindi a un gateway di dialetto DeepSeek si parlerebbe nel dialetto OpenAI senza possibilità di correggerlo." In parole povere, qualsiasi URL di base che non sia chiaramente DeepSeek viene trattato come OpenAI, e la gestione di reasoning_content di DeepSeek va storta.

La seconda e terza trappola sono la capacità. Un modello dichiarato manualmente ricade su defaultContextWindow di 262.144 e defaultMaxTokens di 32.768. V4 supporta 1.048.576 token di contesto, quindi accettare il valore predefinito butta via tre quarti di esso.

Scrivi questi nel tuo file di impostazioni:

yamlCopy
1# $DSH_HOME/settings.yaml   (default: ~/.dsh/settings.yaml)
2llm-pi-ai:
3  providers:
4    atlas:
5      displayName: Atlas Cloud
6      api: openai-completions
7      baseURL: https://api.atlascloud.ai/v1
8      apiKeyEnv: ATLASCLOUD_API_KEY
9      compat:
10        thinkingFormat: deepseek   # 1. ferma l'ipotesi basata sull'URL
11      defaultContextWindow: 1048576  # 2. il default è solo 262144
12      defaultMaxTokens: 32768        # 3. aumenta per lavori con output lunghi
13      models:
14        - id: deepseek-ai/deepseek-v4-flash
15          contextWindow: 1048576
16        - id: deepseek-ai/deepseek-v4-pro
17          contextWindow: 1048576
18

Tre cose da tenere a mente. Le impostazioni risolvono prima il modello, poi il percorso, poi la voce del catalogo installato, poi l'ipotesi derivata dall'URL, quindi un valore per modello vince sempre. Entrambi gli switch compat, thinkingFormat e supportsReasoningEffort, esistono solo sotto openai-completions; mettili su un altro protocollo e la risoluzione fallisce. E questo adattatore deliberatamente non copre Bedrock, Vertex, Azure o Codex, i cui flussi di autenticazione necessitano di più di una chiave, un endpoint e intestazioni.

Passaggio 6: esegui il tuo primo vero compito in DeepSeek Harness

Ora la demo dall'inizio di questo articolo. Crea una cartella vuota e aggiungi tre file.

fizzbuzz.py, contenente un errore off-by-one:

pythonCopy
1def fizzbuzz(n):
2    out = []
3    for i in range(1, n):
4        if i % 15 == 0:
5            out.append("FizzBuzz")
6        elif i % 3 == 0:
7            out.append("Fizz")
8        elif i % 5 == 0:
9            out.append("Buzz")
10        else:
11            out.append(str(i))
12    return out
13

test_fizzbuzz.py, dove due dei tre test falliscono:

pythonCopy
1from fizzbuzz import fizzbuzz
2
3def test_starts_correctly():
4    assert fizzbuzz(5)[:3] == ["1", "2", "Fizz"]
5
6def test_covers_every_number():
7    assert len(fizzbuzz(15)) == 15
8
9def test_fifteen_is_fizzbuzz():
10    assert fizzbuzz(15)[-1] == "FizzBuzz"
11

E requirements.txt:

textCopy
1pytest>=8.0
2

Eseguire la suite manualmente prima vale la pena, così sai cosa l'agente si troverà davanti:

textCopy
1.FF                                                                      [100%]
2=================================== FALLIMENTI ===================================
3___________________________ test_covers_every_number ___________________________
4E       AssertionError: assert 14 == 15
5___________________________ test_fifteen_is_fizzbuzz ___________________________
6E       AssertionError: assert '14' == 'FizzBuzz'
7=========================== breve riepilogo test ============================
82 falliti, 1 superato in 0.01s
9

Imposta la modalità agente su Standard e il modello su deepseek-ai/deepseek-v4-flash, quindi incolla esattamente questo prompt:

Esegui pytest in questo workspace. Due test falliscono. Trova la causa principale in fizzbuzz.py, correggila con la modifica più piccola possibile, quindi riesegui pytest e mostrami l'output finale. Non modificare il file di test.

La correzione corretta è un carattere: range(1, n) diventa range(1, n + 1), e la suite riporta 3 passed.

Ora la parte che rende un'infrastruttura diversa da una finestra di chat. Ogni esecuzione viene registrata in un log di sessione append-only, e puoi biforcarti. Torna al punto in cui l'agente ha letto per la prima volta fizzbuzz.py e dirama un secondo tentativo:

Biforca questa sessione dal passaggio in cui hai letto per la prima volta fizzbuzz.py. Questa volta riscrivilo come una ricerca basata su dizionario invece di correggere il ramo if, quindi esegui di nuovo pytest.

Biforcazione di un log di sessione di DeepSeek Harness per produrre una seconda implementazione basata su dizionario dallo stesso punto di partenza

Un punto di partenza, due rami. Questa è la funzionalità a cui la folla della settimana di lancio teneva davvero.

Passaggio 7: passa a headless per script e CI

Due profili si inizializzano al primo utilizzo: web e headless. Hai usato web, e dsh web è solo un alias per dsh --profile web.

Headless esegue una sessione fresca persistente, stampa la risposta finale ed esce, che è esattamente la forma che un lavoro CI desidera:

bashCopy
1dsh --profile headless "Esegui i test e correggi eventuali fallimenti. Mostra il diff."
2

Qualsiasi altro profilo deve essere creato tramite dsh plugin. I profili risiedono in $DSH_HOME/profiles/<nome>, che per impostazione predefinita è ~/.dsh/profiles/<nome>.

Output del terminale da un'esecuzione headless di DeepSeek Harness che stampa la risposta finale ed esce

Modalità headless: una sessione, una risposta, codice di uscita su cui puoi ramificare.

Altri modi per installare DeepSeek Harness

Il percorso npx copre la maggior parte delle persone. Questi tre meritano di essere conosciuti.

Installa DeepSeek Harness dalla sorgente con pnpm

Se vuoi leggere il codice, correggerlo o scrivere plugin:

bashCopy
1git clone https://github.com/deepseek-ai/deepseek-harness
2cd deepseek-harness
3pnpm install
4pnpm run build
5pnpm dsh web
6

Il build desktop da 5 MB

Un progetto della community, hairyf/deepseek-harness-desktop, racchiude l'infrastruttura in Tauri e fornisce un installer di circa 5 MB per Windows, macOS e Linux senza alcuna configurazione di Node. Non è una release ufficiale di DeepSeek, quindi trattalo di conseguenza: al momento della scrittura ha circa 400 stelle ed è stato creato un giorno dopo l'infrastruttura stessa.

Esegui DeepSeek Harness completamente in locale con Ollama

Ollama include un'integrazione first-party. La versione breve è un comando:

bashCopy
1ollama launch dsh
2

Questo installa ed esegue l'infrastruttura con Ollama integrato, mantenendo le sue impostazioni in ~/.ollama/launch/dsh/settings.yaml (Documentazione Ollama, agosto 2026). Un avvertimento che vale la pena leggere prima di presumere che tutto sia offline: la ricerca web integrata è abilitata automaticamente e necessita dell'accesso cloud di Ollama più un modello che supporti strumenti. Un modello veramente locale ti dà zero costo di token, al prezzo di velocità e, di solito, capacità di chiamata degli strumenti più debole.

DeepSeek Harness connesso a un server Ollama locale che esegue lo stesso compito di test fallito

Stesso compito, nessun viaggio di rete, nessuna fattura per token.

DeepSeek Harness è gratuito? Cosa costa effettivamente eseguirlo

Risposta breve: il software è gratuito e con licenza MIT, incluso per uso commerciale. I token non sono gratuiti, a meno che tu non esegua modelli localmente. Nulla dell'infrastruttura stessa è misurato, limitato o legato a un account DeepSeek.

Tabella C: cosa è effettivamente gratuito e cosa no

Un esempio concreto, usando numeri tondi piuttosto che un'esecuzione specifica. Supponiamo che una sessione di debug come il Passaggio 6 consumi 200.000 token di input e 20.000 token di output, il che è realistico una volta che l'agente ha letto alcuni file e iterato. Alla tariffa fissa del gateway di $0,14 in entrata e $0,28 in uscita, quella sessione costa circa 3,4 centesimi. Sull'API first-party con tariffe cache-miss fuori picco costa circa 5,7 centesimi, e durante le ore di picco circa 11 centesimi. Se la maggior parte del tuo input è cache hit, il first-party diventa drasticamente più economico sul lato input, perché l'input cache hit parte da $0,007 per 1M di token.

Le leve pratiche, in ordine di impatto: mantieni le sessioni brevi in modo che il contesto non cresca a dismisura, esegui il lavoro di routine su Flash e riserva Pro per i compiti veramente difficili, e usa la modalità Minimal per esecuzioni di tipo benchmark poiché fornisce al modello esattamente due strumenti e nessuna compattazione del contesto.

Prima di distribuire: licenza di DeepSeek Harness e rischi di anteprima

Tre cose brevi, e poi le FAQ.

La licenza è MIT, quindi l'uso commerciale va bene. Ma il progetto si etichetta come anteprima per sviluppatori e dichiara, in maiuscolo, che ci saranno modifiche che rompono la compatibilità. Blocca una versione e non integrarlo ancora in una pipeline di rilascio di produzione.

Le tue credenziali risiedono in testo semplice sulla tua macchina, in $DSH_HOME/.credentials.yaml con le impostazioni accanto in $DSH_HOME/settings.yaml, entrambi con default in ~/.dsh. Se la tua home dell'infrastruttura dovesse mai finire all'interno di un repository, aggiungila a .gitignore:

textCopy
1.dsh/
2

E quella ovvia che è facile dimenticare: il tuo codice va a qualsiasi endpoint tu abbia configurato nel Passaggio 4. Leggi i termini sui dati di quel provider prima di puntare un agente a un codebase privato.

Domande frequenti

DeepSeek Harness è gratuito?

L'infrastruttura è gratuita e con licenza MIT, senza bisogno di account o abbonamento, e puoi usarla commercialmente. I token del modello vengono fatturati separatamente dal provider che colleghi. Puntarlo a un modello Ollama locale ti dà una configurazione veramente a costo zero di token, pagata in hardware e velocità.

Ho bisogno di una chiave API DeepSeek per installare DeepSeek Harness?

No. Installazione e chiave DeepSeek non sono correlate. npx @deepseek-ai/dsh web viene eseguito senza alcuna credenziale. Hai bisogno di una chiave solo quando vuoi che l'agente chiami effettivamente un modello, e può essere una chiave per qualsiasi endpoint compatibile con OpenAI, incluso un server locale.

DeepSeek Harness può eseguire modelli diversi da DeepSeek?

Sì. I provider personalizzati accettano openai-completions, e l'adattatore copre i protocolli che possono essere descritti con una chiave, un endpoint e intestazioni. Aggiungi un secondo provider aggiungendo un altro blocco sotto providers: in settings.yaml con il proprio ID, URL di base e modelli. Bedrock, Vertex, Azure e Codex sono deliberatamente esclusi perché la loro autenticazione richiede più di questo.

Perché il mio provider personalizzato restituisce 401 o "modello sconosciuto"?

Un 401 significa quasi sempre che la chiave è sbagliata o non viene letta dalla variabile d'ambiente nominata in apiKeyEnv. Un modello sconosciuto di solito significa che l'endpoint non espone un indice dei modelli, quindi non è stato recuperato nulla: digita manualmente l'ID del modello. Controlla anche l'ortografia dell'ID provider, poiché non può essere rinominato, solo sostituito.

Dove memorizza DeepSeek Harness la mia chiave API e le impostazioni?

Le chiavi vanno in $DSH_HOME/.credentials.yaml e le impostazioni del modello scritte a mano in $DSH_HOME/settings.yaml, entrambi sotto ~/.dsh a meno che tu non sovrascriva DSH_HOME. Le sessioni vivono in $DSH_HOME/storages e i profili in $DSH_HOME/profiles/<nome>. Tieni l'intera directory fuori dal controllo di versione.

DeepSeek Harness è pronto per la produzione?

Ancora no, per sua stessa ammissione. Il progetto viene distribuito come anteprima per sviluppatori e avverte esplicitamente di modifiche che rompono la compatibilità, il che è una descrizione corretta di un software che ha pochi giorni. Usalo per lo sviluppo locale e l'assistenza CI, blocca la versione che hai testato e rileggi il documento dei provider dopo gli aggiornamenti.

---

Verificato rispetto all'anteprima per sviluppatori di DeepSeek Harness il 17 agosto 2026. Questo progetto include modifiche incompatibili per progettazione, quindi se un nome di campo nella tua build appare diverso dallo YAML sopra, controlla la documentazione ufficiale dei provider prima di presumere che la configurazione sia sbagliata.