Come installare DeepSeek Harness (dsh): app desktop, one-liner npx, build dai sorgenti e plugin

DeepSeek Harness (dsh) — il runtime open-source per agenti che DeepSeek ha rilasciato il 13 agosto 2026 — ha ottenuto un client desktop ufficiale il 24 settembre 2026. È un'app pacchettizzata per Windows e macOS con Apple silicon, pubblicata dall'host di download di DeepSeek stesso con il runtime harness incluso all'interno: nessuna installazione di Node.js, nessun npx, nessun terminale. La riga di comando non è affatto scomparsa — npx @deepseek-ai/dsh web resta la via più rapida su Linux, che la build desktop non copre. Due cose da sapere prima di iniziare: dsh non è un modello — è il livello harness che collega un modello come DeepSeek V4 Flash 0731 o DeepSeek V4 Pro 0813 a strumenti, file e un terminale — e ogni suo canale è ancora una developer preview, quindi aspettati modifiche che rompono la compatibilità tra una release e l'altra. Questa guida copre l'app desktop, il one-liner npx, la build dai sorgenti, la modalità headless, i plugin, MCP e gli aspetti ancora ruvidi, raccontati senza filtri.

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ù una serie di plugin che forniscono adattatori di modello, strumenti, sessioni e interfaccia utente. Secondo, i canali npm oggi sono 0.1.5-rc.3 su latest e 0.1.7-rc.2 su next, entrambe release candidate che il progetto stesso segnala come anteprima per sviluppatori: il README avverte, in lettere maiuscole, che sono in arrivo modifiche che rompono la compatibilità. La popolarità è reale — 50.000 stelle GitHub nelle prime 12 ore e 235.000 alla fine di settembre 2026 — ma le stelle misurano l'interesse, non la stabilità. Pianifica l'installazione come pianifichi un'anteprima: veloce da provare, economica da buttare via.

Prima di iniziare: i reali requisiti di sistema

Per le installazioni da riga di comando l'unico requisito indispensabile è Node.js. Il progetto supporta l'intervallo di versioni del motore ^22.19.0 || >=24.0.0 — in parole semplici, Node 22.19 o versioni successive, oppure qualsiasi Node 24.x. Controlla la tua con node --version. Se utilizzi una versione meno recente di Node, l'installazione con npx fallirà o si comporterà in modo anomalo, non si degraderà in modo controllato. L'app desktop di seguito è l'eccezione: include il proprio runtime, quindi non richiede affatto Node.js.

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 disco libero per il pacchetto npm, il workspace e i log di sessione, più tutto ciò di cui avrebbe bisogno un modello locale (dsh stesso non esegue i pesi). L'installer desktop è più pesante — 288 MB per il file .exe di Windows, un'immagine disco da 368 MB su macOS — perché contiene quel runtime al suo interno.

• OS: la via npm funziona su Windows, macOS e Linux. L'app desktop è più limitata — solo Windows x64 e macOS con Apple silicon, nessuna build per Intel-Mac e nessun target Linux. L'SDK Python è ancora 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 — l'app desktop ufficiale (Windows e macOS)

Il 24 settembre 2026, Deep​Seek ha pubblicato la prima build desktop pacchettizzata di Deep​Seek Harness. È un guscio Electron attorno alla stessa Web UI con il runtime dsh incluso all'interno, quindi non c'è nulla da installare prima e nulla da avviare manualmente: niente Node.js, niente npx, niente terminale e nessuna scheda del browser lasciata aperta su 127.0.0.1:3080. Il codice sorgente si trova nel repository pubblico sotto apps/desktop come pacchetto @deepseek-ai/dsh-desktop, gli artefatti sono serviti dall'host di download di produzione di Deep​Seek all'indirizzo download.deepseek.com/dsh-desk/, e l'app segue esattamente la versione dell'harness — la build attuale è 0.1.7-rc.2.

Che cosa stava servendo quell'host il 25 settembre 2026:

• Windows — deepseek-harness-0.1.7-rc.2-win-x64.exe, un programma di installazione da 288 MB, con accanto un file .blockmap per gli aggiornamenti differenziali.

• macOS — deepseek-harness-0.1.7-rc.2-mac-arm64.dmg, un'immagine disco da 368 MB, oppure la stessa build in un .zip da 373 MB. Solo Apple silicon.

• Versione — 0.1.7-rc.2, con data di rilascio 24 settembre 2026, corrispondente alla versione dell'harness sul tag next di npm.

• Mancante — nessuna build per Intel-Mac (il feed di aggiornamento mac-x64 restituisce 404) e nessun target Linux di alcun tipo.

Ogni target pubblica anche un feed di aggiornamento sotto download.deepseek.com/dsh-desk/feeds/, il cui campo releaseDate corrisponde alla data di build. Controllare quel file è il modo più rapido per vedere se esiste una build più recente senza aspettare che sia l'app a proporla.

Perché il client ufficiale è una cosa diversa dai wrapper della community. È di prima parte e si aggiorna automaticamente, include il runtime nell'installer invece di scaricarne uno al primo avvio, e non serve l'interfaccia utente dalla porta 3080 del profilo web: la shell carica l'applicazione tramite uno schema interno dsh-app:// e comunica con un processo host privato su una propria porta, 19387 per impostazione predefinita. Si comporta anche come un'applicazione desktop — chiudere la finestra mantiene attive le attività in esecuzione (Windows mantiene un'icona nell'area di notifica), uscire chiede prima quando c'è lavoro in corso, e le note di rilascio 0.1.7-rc.2 aggiungono un onboarding al primo avvio che introduce il credito disponibile e separa le attività finanziate dall'account da quelle con chiave API, così puoi accedere con un account DeepSeek invece di incollare una chiave.

Due avvertenze, perché questo client è stato distribuito in sordina invece che annunciato. Il README del repository documenta ancora solo npx e la build dai sorgenti, e la pagina del progetto su www.deepseek.com/harness non contiene alcun link di download — i binari e il loro feed di aggiornamenti sono attivi sull'host di Deep​Seek stesso, ed è ciò che abbiamo verificato il 25 settembre 2026, ma nessuna nota di rilascio da nessuna parte li descrive. E non abbiamo eseguito gli installer, quindi questa guida non prende posizione sullo stato di firma o notarizzazione dei binari pubblicati; la pipeline di packaging nel repository include effettivamente passaggi di code-signing per Windows e di notarizzazione per Apple, e questo è tutto ciò che si può dire dall'esterno.

Una conseguenza del fatto che la build desktop segue la versione dell'harness: al momento è più avanti di un'installazione predefinita da riga di comando. Il tag latest di npm punta ancora a 0.1.5-rc.3, mentre ogni artefatto desktop è 0.1.7-rc.2. Se vuoi l'harness più recente su una piattaforma che l'app desktop non copre, installa esplicitamente il tag — npx @deepseek-ai/dsh@next web — invece di fidarti dell'impostazione predefinita.

Metodo 2 — il comando npx in una riga (tutte le piattaforme, incluso Linux)

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

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (npm's latest tag currently resolves to 0.1.5-rc.3, not the newest harness), 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 3 — compila dal 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. The models dsh will actually call are all on it: DeepSeek V4 Flash 0731 (deepseek/deepseek-v4-flash-0731, $0.22 per million input tokens and $0.66 per million output), DeepSeek V4 Pro 0813 (deepseek/deepseek-v4-pro-0813, $0.66/$1.98) and DeepSeek V4.1 Flash (deepseek/deepseek-v4.1-flash, $0.15/$0.60), the model Deep​Seek's own rate card bills as deepseek-flash. Every rate doubles inside Deep​Seek's peak windows, 01:00-04:00 and 06:00-10:00 UTC on weekdays; the router passes that surcharge through rather than hiding it, and automatic failover moves a request to another provider if one wobbles. Figures checked against both rate cards on September 25, 2026. For dsh, the practical win is that you can keep the cheap tier 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 i modelli che dsh richiama; non ospita dsh stesso, e non distribuisce nemmeno il client desktop — quello arriva dall'host di download di Deep​Seek. dsh è un runtime di agenti locale, 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 che rompono la compatibilità sono una promessa, non un avviso. Ti trovi su una release candidate — 0.1.5-rc.3 se hai preso il default di npm, 0.1.7-rc.2 se hai installato l'app desktop o il tag next. Le chiavi di configurazione, l'API dei plugin e i formati dei preset possono tutti cambiare senza preavviso. Considera ~/.dsh come stato sacrificabile — il costo di un aggiornamento andato male è una reinstallazione, e a questo stadio è accettabile solo perché ogni modalità di installazione qui è un download o un singolo 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 non hanno più un ruolo. Fino al 24 settembre 2026 le uniche app desktop dsh installabili con un clic erano wrapper di comunità non firmati, e la scelta era tra quelli e la riga di comando. Il client ufficiale elimina il compromesso: first-party, runtime incluso, con aggiornamento automatico. Non esiste un vero percorso di migrazione tra i due tipi di shell — avvolgono lo stesso harness — quindi disinstalla l'uno e installa l'altro, mantenendo la stessa directory di workspace.

• 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.

In definitiva

Installare Deep​Seek Harness ora richiede due procedure diverse a seconda della piattaforma. Su Windows o su un Mac con Apple silicon, scarica la 0.1.7-rc.2 dall'host di Deep​Seek e il gioco è fatto — niente Node.js, niente terminale e la versione più recente dell'harness in qualsiasi canale. Ovunque altro serve ancora un solo comando su Node 22.19+: npx @deepseek-ai/dsh@next web, poi aggiungi una chiave del modello e un workspace e invia un'attività di prova. Usa la modalità headless per gli script, la build dai sorgenti solo se vuoi modificare o seguire main, e considera MCP un lavoro in corso. L'avvertenza onesta non è cambiata: ognuno di questi canali è una release candidate 0.x e romperà le cose lungo il cammino verso la stabile — uno scambio accettabile se vuoi vedere dove Deep​Seek sta portando il livello agente. I modelli che esegue — DeepSeek V4 Flash 0731, DeepSeek V4 Pro 0813 e DeepSeek V4.1 Flash — sono disponibili oggi a prezzo di listino tramite OrcaRouter, pronti ad alimentare l'harness dall'altra parte dell'installazione.