Come Installare DeepSeek Harness (dsh): comando npx in una riga, build da sorgente, modalità headless e plugin

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

Cos'è Deep​Seek Harness — e cosa non è

La formula interna di Deep​Seek, confermata dal ricercatore senior Chen Deli, è Modello + Harness = Agente. Il modello è il cervello; l'harness è tutto ciò che lo trasforma in qualcosa che porta a termine il lavoro: gestione del contesto e della memoria, chiamata di strumenti, pianificazione dei compiti, lettura e scrittura di file, esecuzione in terminale, feedback sugli errori e decisione su quando un compito è completato. Deep​Seek Harness è quel livello, reso open-source con licenza MIT il 13 agosto 2026 — lo stesso giorno in cui la build DeepSeek V4 Pro 0813 è arrivata su Deep​Seek API.

Due fatti definiscono l'esperienza di installazione. Primo, l'architettura è "tutto è un plugin", costruita su Cordis, un contenitore di plugin TypeScript — quindi ciò che installi è un piccolo core più un insieme di plugin che forniscono adattatori di modelli, strumenti, sessioni e interfaccia utente. Secondo, la versione su npm oggi è 0.1.0-rc.6, una release candidate che il progetto stesso segnala come anteprima per sviluppatori: il README avverte, in maiuscolo, che arrivano modifiche che rompono la compatibilità. La popolarità è reale — 50.000 stelle GitHub nelle prime 12 ore, 100.000 in circa 42 ore e oltre 120.000 entro il 16 agosto secondo la stampa tech cinese — ma le stelle misurano l'interesse, non la stabilità. Pianifica l'installazione come pianificheresti un'anteprima: veloce da provare, economica da buttare via.

Prima di iniziare: i reali requisiti di sistema

L'unico requisito indispensabile è Node.js. Il progetto supporta l'intervallo di versioni del motore ^22.19.0 || >=24.0.0 — in parole povere, Node 22.19 o successivo, oppure qualsiasi Node 24.x. Controlla la tua versione con node --version. Se hai una versione precedente di Node, l'installazione via npx fallirà o si comporterà male, non si degraderà in modo elegante.

Tutto il resto è più leggero di quanto supponga la folla del model-first:

• Una chiave API del modello. dsh esegue un modello reale; necessita di una chiave per l'API di DeepSeek o per qualsiasi provider compatibile con OpenAI che configuri. Puoi aggiungerne una nell'interfaccia web dopo il primo avvio.

• pnpm — solo per la build da sorgente. Installalo una volta con npm install -g pnpm.

• ~1 GB di spazio libero su disco per il pacchetto npm, l'area di lavoro e i log delle sessioni, oltre a tutto ciò di cui un modello locale potrebbe aver bisogno (dsh stesso non esegue i pesi).

• OSil percorso npm funziona su Windows, macOS e Linux. Lo SDK Python è più limitato (Linux x64/arm64, macOS 14+ arm64 — nessun Windows nativo), trattato di seguito.

Tu non hai bisogno di una GPU. L'harness orchestra soltanto; il modello gira in remoto tramite un'API.

Metodo 1 — il one-liner con npx (consigliato a quasi tutti)

L'avvio rapido ufficiale è un comando, ed è davvero un comando:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

Il primo avvio prevede esattamente due passaggi di configurazione:

• Aggiungi una chiave del modello. Impostazioni → Modelli → inserisci la tua chiave API. Viene salvata in $DSH_HOME/.credentials.yaml e non viene mostrata in chiaro in seguito. In un'installazione standard DSH_HOME ha come valore predefinito ~/.dsh.

• Scegli un'area di lavoro. Aggiungi la directory del progetto in cui dsh è autorizzato a lavorare. L'input rimane bloccato finché entrambi i passaggi non sono stati completati.

Poi invia un primo compito — un buon smoke test è "Riassumi questo repository e identifica i suoi pacchetti principali." Se il riassunto viene restituito e le chiamate agli strumenti compaiono nella traccia di esecuzione, la tua installazione funziona.

Metodo 2 — compilare dal codice sorgente

Preferisci eseguire dal repository? Il percorso ufficiale è:

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

Ti serve pnpm per questo (i contributor fissano pnpm 11.7.0). Scegli la build sorgente quando vuoi eseguire l'ultimo main piuttosto che la release candidate pubblicata, quando prevedi di leggere o modificare l'harness, o quando vuoi creare un preset personalizzato dalla directory apps/cli/config/agent-presets/ del repository. Per tutti gli altri, la via npx è lo stesso software con meno cerimonie — la build sorgente non sblocca funzionalità che il pacchetto npm non ha.

I tre profili: web, headless e tui

dsh viene fornito con tre profili di esecuzione, e quello che usi dipende da dove avviene il lavoro:

• web (predefinito) — l'interfaccia browser completa sulla porta 3080. Questo è ciò che npx @deepseek-ai/dsh web avvia, ed è il profilo che la maggior parte delle persone installerà per primo.

• headless — un solo compito, poi esce. dsh --profile headless "run the test suite and report failures" avvia una sessione, esegue il compito, scrive i risultati e termina. Il runtime headless è esplicitamente un processo a compito singolo: non puoi iniettare richieste di follow-up durante l’esecuzione, e le correzioni sono una nuova esecuzione sullo stesso workspace. Questo è il profilo da collegare a script e CI.

• tui — un'interfaccia a terminale per sessioni guidate da tastiera: dsh --profile tui.

Tutti e tre condividono la stessa configurazione (~/.dsh/profiles/<name>/) e lo stesso sistema di plugin, quindi spostare un'attività dall'interfaccia web a headless è un cambio di comando, non una reinstallazione.

Aggiunta di plugin

La gestione dei plugin è un comando CLI di prima classe, non una questione di modifica in-place:

npx @deepseek-ai/dsh plugin --profile web add <source>

La sorgente può essere un nome di pacchetto npm, un repository GitHub (github:user/repo), un tarball o una cartella locale. L'installazione iniziale più utile è il market ufficiale dei plugin, che trasforma la scoperta dei plugin in una UI:

npx @deepseek-ai/dsh plugin --profile web add dshmarket

Quindi riavvia il servizio web e apri Impostazioni → Plugin Market per sfogliare e installare con un clic dal catalogo. Due regole che creano confusione: i bundle di plugin vengono montati all'avvio del profilo, quindi un plugin appena aggiunto richiede un riavvio di dsh web; e un semplice npm install non registra un plugin in un profilo — devi usare dsh plugin. L'ecosistema è giovane ma non vuoto: la lista mantenuta dalla comunità awesome-dsh-plugin cataloga già centinaia di plugin in categorie come UI, competenze, strumenti, fornitori e notifiche.

MCP, i quattro preset e la riproduzione della traiettoria.

Tre funzionalità contano una volta superata un'installazione di base:

MCP. dsh usa il Model Context Protocol tramite un plugin integrato @deepseek-ai/dsh-mcp-client. Oggi è configurato nei file, non nell'interfaccia: si modifica ~/.dsh/profiles/web/cordis.patch.yml (o una patch a livello di progetto) e si dichiara il trasporto di ciascun server — stdio per comandi locali come npx @playwright/mcp@latest, streamable-http per URL remoti. Funziona, ma è la parte meno curata dell’anteprima; ci si può aspettare qualche instabilità occasionale e nessuna GUI per attivare/disattivare i server.

Preimpostazioni. dsh carica uno dei quattro preset degli agenti per sessione, e ciascuno rappresenta un diverso compromesso:

• Standard — il set completo di strumenti: modifica di file, shell, recupero di file e pagine web, competenze, pianificazione, subagenti, flussi di lavoro. La scelta predefinita per l'uso quotidiano.

• PTC (Programmatic Tool Calling) — Standard più un SDK Code Mode che consente al modello di scrivere programmi TypeScript per orchestrare chiamate di strumenti multi-round. Più potente, più effetti collaterali.

• Minimale — solo bash e un editor di file, nient'altro. Progettato per il benchmarking dei modelli e la riproduzione minima; la modalità a cui i documenti dell'API DeepSeek V4 Flash facevano riferimento quando hanno rivelato che i propri punteggi degli agenti giravano su "Deep​Seek Harness minimal mode."

• Creazione — un playground runtime: ispeziona e carica in memoria i plugin Cordis, sperimenta e consolida una combinazione funzionante in un nuovo preset.

Riproduzione della traiettoria. Ogni esecuzione scrive un log di sessione append-only — prompt di sistema, ragionamento, chiamate agli strumenti e i loro risultati, pianificazione dei subagent. La visualizzazione Trajectory consente di ispezionare per sorgente, riprendere, creare un fork, cercare e riprodurre un'esecuzione. Questo è il debugger per il lavoro degli agenti: quando un task fallisce, non ti limiti a rieseguire e sperare; riproduci la traiettoria fallita, ne crei un fork nel passaggio sbagliato e testi una correzione senza scartare l'originale.

L'opzione SDK Python

Se preferisci usare l'harness da Python piuttosto che da un browser, c'è un SDK ufficiale: pip install deepseek-harness-sdk. Include il runtime dsh (la pip wheel contiene il runtime Node, quindi non è necessaria un'installazione separata di Node), e l'uso è un context manager: crea un'istanza Deep​SeekHarness, chiama run("task"). Eredita le variabili d'ambiente standard come DEEPSEEK_API_KEY e DEEPSEEK_BASE_URL, quindi un cambio di provider è un cambio di configurazione. Il problema: richiede Python 3.10+ e supporta solo Linux x64/arm64 e macOS 14+ arm64 — non esiste una wheel nativa per Windows, il che è una vera lacuna se il tuo host è Windows. Su Windows, attieniti alla via npm.

Puntare dsh ai modelli per cui paghi

dsh necessita di una chiave API per il modello ed è volutamente agnostico rispetto al fornitore: Impostazioni → Modelli accetta un fornitore personalizzato con un URL di base compatibile con OpenAI (in settings.yaml cioè api: openai-completions, baseURL, e un elenco di models). Il valore predefinito è l'API di DeepSeek; un fornitore personalizzato è il punto in cui un gateway di instradamento diventa utile.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

Per essere chiari sui confini: OrcaRouter ospita le chiamate dsh dei modelli; non ospita dsh stesso. dsh è un runtime locale per agenti, e lo esegui sulla tua macchina.

Dove questa guida non è adatta a te — problemi onesti con l'anteprima

Un tutorial di installazione che ti dice solo cosa digitare fa solo metà del lavoro. Ecco cosa l'anteprima sbaglia oggi, così non lo scopri alle 2 di notte:

• Le modifiche di rottura sono una promessa, non un avvertimento. Sei su 0.1.0-rc.6. Le chiavi di configurazione, l'API dei plugin e i formati dei preset possono cambiare senza preavviso. Tratta ~/.dsh come uno stato usa e getta — il costo di un aggiornamento non riuscito è una reinstallazione, ed è accettabile in questa fase solo perché l'installazione è un unico comando.

• Non hai bisogno di dsh per usare i modelli Deep​Seek come agente. Se il tuo unico obiettivo è DeepSeek V4 Flash o DeepSeek V4 Pro all'interno di un agente oggi, l'endpoint compatibile con Anthro​pic di Deep​Seek funziona già in Claude Code e altri strumenti per agenti senza alcun nuovo software. dsh è un'opzione di prima parte, non un prerequisito. Salta questa installazione finché non vuoi espressamente l'harness nativo.

• MCP è configurato tramite file e a volte è inaffidabile. Nessuna GUI, nessun interruttore di avvio/arresto per server, e chi lo ha provato segnala guasti intermittenti. Riserva tempo per il debug di YAML se il tuo flusso di lavoro dipende dai server MCP.

• La fiducia nei plugin è una decisione di sicurezza. I plugin di terze parti vengono eseguiti nel processo principale dell'harness e non esiste alcuna firma o verifica della fonte al momento dell'installazione. Installa solo plugin che hai letto o che provengono da una fonte di cui ti fidi, e provali in uno spazio di lavoro usa-e-getta prima di utilizzarli su lavoro reale. Il danger-full-access è un profilo sandbox che può modificare qualsiasi file visibile — tienilo per checkout usa-e-getta.

• Nell'anteprima sono presenti bug noti. Un ciclo bash bloccato è una modalità di errore documentata (interrompi e riprova) e il comportamento per le sessioni di lunga durata è ancora in fase di assestamento.

• Le build desktop non ufficiali sono una trappola. Diversi wrapper della community impacchettano dsh come un'app desktop installabile con un clic, con un runtime Node incluso. Funzionano, ma non sono firmati e non sono mantenuti da Deep​Seek; se ne usi uno, ti fidi di una terza parte per uno strumento che avrà i permessi del tuo file system.

• Se hai bisogno di stabilità in produzione, aspetta una release non-rc. L'harness è potente ma acerbo. Per uno stack di agenti in produzione, un harness maturo e provato sul campo — o la via dell'endpoint compatibile con Anthro​pic — è la scelta difendibile finché dsh non raggiunge un tag stabile.

Il risultato finale

Installare Deep​Seek Harness è davvero questione di un solo comando su qualsiasi macchina con Node 22.19+: npx @deepseek-ai/dsh web, aggiungi una chiave del modello e uno spazio di lavoro, invia un'attività di test. Scegli la build da sorgente solo se vuoi modificare o tracciare main; usa headless per gli script; aggiungi subito il mercato dei plugin; e tratta MCP come un lavoro in corso. L'avvertenza onesta è la stessa che il progetto stampa nel suo README: questa è un'anteprima 0.1.0-rc e romperà cose sulla strada verso la stabilità. È il giusto compromesso se vuoi vedere dove Deep​Seek sta portando il layer degli agenti — e i modelli che esegue, DeepSeek V4 Flash e DeepSeek V4 Pro, sono disponibili oggi al prezzo di listino tramite OrcaRouter, pronti ad alimentare l'harness dopo l'installazione.