6 metodi per distribuire DeepSeek Harness in locale

TLDR DeepSeek Harness (dsh) è il runtime per agenti open source di DeepSeek AI, rilasciato in anteprima per sviluppatori intorno al 13 agosto 2026 sotto licenza MIT. Segue il principio “Modello + Harness = Agente”, con ogni capacità (modelli, strumenti, sessioni, sandbox, loop, UI) implementata come plugin Cordis intercambiabili.

Il modo più veloce per eseguirlo in locale è npx @deepseek-ai/dsh web (richiede Node.js ^22.19 o ≥24), che avvia una Web UI su http://127.0.0.1:3080. Fornisci una chiave API DeepSeek (o compatibile con OpenAI) e un workspace. Sono disponibili anche build da sorgente, app desktop, Docker, SDK Python e integrazioni con Ollama. Per accesso multi‑modello di livello produzione, affidabilità e controllo dei costi mentre usi l’harness, instrada le richieste tramite l’endpoint unificato compatibile con OpenAI di CometAPI.

Punti chiave

• DeepSeek Harness non è un modello: è il runtime/orchestratore locale che consente ai modelli di agire su file, shell, strumenti e sessioni.
• One‑liner ufficiale: npx @deepseek-ai/dsh web → apre la Web UI locale sulla porta 3080.
• Requisito Node.js rigoroso: ^22.19.0 o ≥24.x.
• Supporta i modelli ufficiali DeepSeek (deepseek-v4-flash, deepseek-v4-pro), gateway personalizzati compatibili con OpenAI e modelli locali via plugin/Ollama.
• Architettura completamente basata su plugin (kernel Cordis); le modalità includono Standard, Minimal, Code e Creator.
• Adozione rapida: da decine di migliaia a oltre 100k stelle GitHub entro pochi giorni dal lancio.
• Consigliato per power user: abbinalo a CometAPI (https://www.cometapi.com/) come provider personalizzato per accedere a 500+ modelli, risparmio del 20–40% e una singola chiave API.
• Usa sempre un workspace isolato; l’agente può modificare file ed eseguire comandi.
• Stato di developer preview: sono previsti breaking change—fissa le versioni per esperimenti “quasi‑produttivi”.

Cos’è DeepSeek Harness e perché conta nel 2026

DeepSeek Harness (dsh) è un runtime open source per agenti sviluppato da DeepSeek AI. Rilasciato sotto licenza MIT in developer preview, enfatizza la componibilità: ogni capacità—adattatori di modelli, strumenti, skill, sessioni, sandbox, storage, loop agentici, scheduling e UI—esiste come plugin Cordis che possono essere montati, smontati, scambiati o ricomposti via configurazione. Di fatto non c’è un core privilegiato che richieda patch.

Principi di progettazione chiave:

• Agente = Modello + Harness.
• Flussi di eventi tracciabili che supportano resume, fork, ricerca e replay.
• Modalità runtime multiple (toolset completo standard, modalità code/orchestration, modalità minimal per benchmarking, modalità creator/sperimentali).
• Web UI local‑first per uso interattivo, oltre a opzioni headless e SDK per automazione.

Risorse ufficiali:

• GitHub: https://github.com/deepseek-ai/deepseek-harness
• Product/landing: https://www.deepseek.com/harness/en/ (e controparte cinese)
• Pagine di guida all’installazione e mirror della community ribadiscono gli stessi comandi di base.

Nota terminologica importante: “distribuzione locale” può significare due cose diverse. Il DeepSeek Harness discusso in questa guida gira in locale sul tuo computer, ma il progetto standard deepseek-harness si connette a DeepSeek V4-Pro o V4-Flash tramite API. Ciò significa che l’harness, la configurazione, le sessioni, la validazione e la logica client possono essere locali, mentre l’inferenza del modello è normalmente eseguita dall’API di DeepSeek. Se hai bisogno di inferenza davvero offline con pesi del modello sulla tua GPU, si tratta di un’architettura di distribuzione diversa.

Prerequisiti e requisiti di sistema

Prima di installare, verifica quanto segue:

• Sistemi operativi: Windows 10+, macOS 10.15+, Linux mainstream (x64 o arm64). L’SDK Python ha vincoli aggiuntivi (Linux x64/arm64 o macOS 14+ arm64).
• Node.js: necessario per il percorso principale della Web UI. Intervallo target ^22.19.0 || ≥24.0.0. Controlla con node --version. Le versioni intermedie con numerazione dispari fuori da questo intervallo non sono supportate.
• Gestori pacchetti: npm/npx (inclusi con Node). Le build da sorgente richiedono pnpm (installa con npm install -g pnpm).
• Git: necessario per il clone dei sorgenti.
• Python (opzionale): 3.10+ per l’SDK Python ufficiale.
• Chiave/endpoint API: una chiave API DeepSeek da platform.deepseek.com, o qualsiasi endpoint compatibile con OpenAI + chiave + nome modello.
• Hardware: nessuna GPU richiesta per l’harness stesso—l’inferenza del modello avviene in remoto (o tramite un provider locale che configuri). Le risorse di un normale laptop sono sufficienti per Web UI e orchestrazione.
• Rete: necessaria al primo avvio per scaricare pacchetti; successivamente la UI può operare con le sole chiamate API al modello.
• Workspace: prepara una directory isolata. L’agente può leggere, scrivere ed eseguire comandi all’interno del workspace configurato—non puntarlo mai a dati di produzione o personali senza protezioni.

Fonti dei requisiti: README ufficiale e diverse guide d’installazione indipendenti pubblicate poco dopo il lancio.

Metodo 1: One‑liner ufficiale con npx (consigliato per la maggior parte degli utenti)

È il percorso più rapido e promosso ufficialmente.

1. Assicurati che Node.js soddisfi il requisito di versione.
2. Apri un terminale ed esegui:

Bash

npx @deepseek-ai/dsh web

1. Il pacchetto viene scaricato (o usa la cache), avvia il profilo Web UI e stampa l’indirizzo in ascolto—per impostazione predefinita http://127.0.0.1:3080.
2. Apri quell’URL in un browser. Accetta l’avviso di developer preview se mostrato.
3. Al primo utilizzo, configura un provider di modelli (Settings → Models) incollando la tua chiave API e selezionando un modello come deepseek-v4-flash o deepseek-v4-pro.
4. Scegli o crea una directory di workspace.
5. Inizia a inviare task.

Per usare una porta diversa:

Bash
npx @deepseek-ai/dsh web --port 8080

One‑liner specifici per piattaforma che assicurano anche la presenza di Node sono disponibili da siti della community (PowerShell su Windows con winget, Homebrew su macOS, NodeSource su Debian/Ubuntu, ecc.).

Pro: impatto d’installazione nullo oltre alla cache npm; scarica sempre una versione pubblicata recente; onboarding più semplice. Contro: dipende dalla rete per il pacchetto iniziale; meno comodo per ispezione profonda del sorgente o build personalizzate.

Metodo 2: Installazione ed esecuzione dai sorgenti

Usalo quando vuoi leggere i plugin Cordis, fissare un commit, sviluppare preset personalizzati o contribuire.

Bash

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Appare la stessa Web UI sulla porta predefinita. Le build in developer preview possono rompersi tra i commit, quindi consideralo un percorso sperimentale.

Metodo 3: Applicazioni desktop (senza setup di Node)

Wrapper desktop della community e di terze parti impacchettano il runtime così che gli utenti evitino di installare Node/pnpm:

• Client leggeri basati su Tauri che avviano un runtime Node integrato e sincronizzano l’ultima versione upstream dell’harness all’avvio. Girano su 127.0.0.1:3080, mantengono i dati in locale e registrano i comandi dsh.
• Packaging basato su Electron che include dipendenze fissate.

Scarica gli installer dalle rispettive pagine GitHub Releases (cerca “deepseek-harness-desktop”). Al primo avvio scaricano i componenti core (alcune centinaia di MB). Comodi per i non tecnici, ma non sono prodotti ufficiali DeepSeek—verifica repository e checksum SHA.

Metodo 4: Distribuzione Docker/container

Esistono immagini Docker e file compose della community per eseguire la Web UI dentro un container, spesso con terminazione HTTPS via nginx e supporto per gateway arbitrari compatibili con OpenAI. Flusso tipico:

Bash

git clone <docker-repo>
cd <docker-repo>
cp .env.example .env   # imposta chiave API / host pubblico
docker compose up -d --build

Utile per accesso in LAN, server o ambienti dove non si desidera Node sull’host. Alcune configurazioni supportano settings.yaml personalizzati per provider non‑DeepSeek.

Metodo 5: SDK Python per uso programmatico/headless

Per agenti non presidiati o integrazione in pipeline Python:

Bash

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk

Imposta le variabili d’ambiente:

Bash

export DEEPSEEK_API_KEY=sk-your-key-here
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: export DSH_MODEL=deepseek-v4-flash

Poi esegui gli esempi inclusi o usa la classe DeepSeekHarness nel tuo codice contro un workspace e una directory di sessione isolati. L’SDK include il proprio runtime e non richiede Node.js di sistema.

Metodo 6: Integrazione con Ollama

Ollama fornisce un launcher conveniente:

Bash

ollama launch dsh
# o con un modello specifico
ollama launch dsh --model deepseek-v4-flash:cloud

Ollama può installare il pacchetto se necessario e memorizza separatamente le impostazioni di lancio. La ricerca web e il supporto strumenti dipendono dal modello scelto e dall’accesso cloud di Ollama.

Configurazione di modelli e provider (incluso CometAPI)

All’interno della Web UI vai su Settings → Models.

• Per DeepSeek ufficiale: incolla la chiave da platform.deepseek.com. I modelli tipici sono deepseek-v4-flash e deepseek-v4-pro.
• Per provider catalogo (Anthropic, OpenAI, ecc.): usa il flusso “Add provider”.
• Per endpoint personalizzati/self‑hosted/aggregatori: scegli “Add a custom provider”. Fornisci un Provider ID permanente, base URL, protocollo (di solito openai-completions), riferimento o valore della chiave API e almeno un ID modello.

Raccomandazione CometAPI (fortemente suggerita per molti workflow quasi‑produttivi) CometAPI è una piattaforma di infrastruttura AI unificata che espone 500+ modelli (inclusi varianti DeepSeek, GPT, Claude, Gemini, Grok e molti altri) tramite un singolo endpoint compatibile con OpenAI: https://api.cometapi.com/v1.

Vantaggi con DeepSeek Harness:

• Una sola chiave API invece di gestire credenziali di provider multipli.
• Prezzi competitivi (riportati risparmi del 20–40% rispetto alle tariffe dirette di molti vendor).
• Alta disponibilità (obiettivo SLA 99,9%), bassa latenza mediana e fatturazione pay‑as‑you‑go.
• Cambio modello semplice per A/B test o ottimizzazione dei costi senza modificare la configurazione dell’harness oltre all’ID modello.
• Compatibilità drop‑in: i pattern degli SDK OpenAI esistenti funzionano cambiando solo base_url e chiave.

Nel form del provider personalizzato dell’harness:

• Base URL: https://api.cometapi.com/v1
• Protocol: openai-completions (o opzione equivalente supportata)
• API key: la tua chiave CometAPI
• Model ID: qualsiasi stringa di modello supportata dal catalogo modelli CometAPI

Questa combinazione mantiene il potente runtime agente locale offrendo accesso multi‑vendor flessibile, conveniente ed economico. I nuovi utenti ricevono tipicamente crediti di prova gratuiti. Documentazione: https://apidoc.cometapi.com/.

Le chiavi sono archiviate in sola scrittura (ad es. sotto $DSH_HOME/.credentials.yaml); la UI mostra solo descrittori redatti.

Risoluzione dei problemi con DeepSeek Harness

DEEPSEEK_API_KEY non trovato

Controlla:

echo $DEEPSEEK_API_KEY

Su Windows:

echo $env:DEEPSEEK_API_KEY

Se vuoto, configurala di nuovo.

Errore 400 reasoning_content

Di solito indica una gestione errata del ciclo di vita del reasoning.

Verifica che la tua applicazione preservi le informazioni di reasoning rilevanti dell’assistente tra richieste multi‑turno di thinking/tool‑call.

Questo è uno dei problemi principali che l’harness è progettato specificamente per gestire.

Errore di lunghezza del contesto

Controlla:

input tokens + max_tokens

Il tetto massimo documentato è:

1,048,576 token

Riduci il contesto in input o la dimensione di completion richiesta.

Le chiamate agli strumenti diventano malformate durante lo streaming

Non presumere che i chunk di stream arrivino nell’ordine degli strumenti.

Aggrega i delta delle tool‑call per tool_call.index, come raccomandato dal contratto dell’harness.

Le richieste risultano inaspettatamente costose

Controlla:

• modalità di thinking
• lunghezza dell’output
• tasso di cache‑hit
• stabilità del prompt di prefisso
• scelta del modello
• pricing API corrente

Un miglioramento semplice è spesso spostare i task di routine da Pro a Flash.

Confronto dei metodi di installazione e distribuzione

Dati sintetizzati da documentazione ufficiale e guide post‑lancio (agosto 2026).

Conclusione e prossimi passi

DeepSeek Harness porta un runtime per agenti dal design pulito e completamente basato su plugin sulle macchine locali con quasi zero attrito tramite l’one‑liner npx. Combinato con un routing dei modelli flessibile—soprattutto tramite una piattaforma unificata come CometAPI—ottieni sia la potenza dei moderni workflow agentici di coding sia un controllo pratico su costi, scelta del modello e località dei dati.

Inizia oggi con:

npx @deepseek-ai/dsh web

Configura una chiave DeepSeek o CometAPI, puntalo a un workspace sicuro ed esplora la modalità Standard. Poi sperimenta la modalità Minimal per benchmark, i provider personalizzati per l’ottimizzazione dei costi o l’SDK Python per l’automazione.

Per le istruzioni ufficiali più recenti preferisci sempre il repository GitHub e la doc. Per affidabilità multi‑modello e vantaggi di prezzo mentre usi l’harness, esplora CometAPI e la sua documentazione su https://apidoc.cometapi.com/.