Come ho Installato DeepSeek Harness su Linux (e Come Puoi Farlo Anche Tu)

Come ho Installato DeepSeek Harness su Linux (e Come Puoi Farlo Anche Tu)

Ultimo aggiornamento: 11 Settembre 2026.

DeepSeek Harness è un framework che promette di semplificare il lavoro con i modelli AI direttamente dal proprio computer. La premessa è interessante: l’ambiente di lavoro e i propri file possono rimanere sul computer locale, evitando di dover utilizzare necessariamente un ambiente di sviluppo completamente basato sul cloud. Perfetto per chi, come me, ha un minimo di paranoia sulla privacy. Leggi questo articolo per saperne di più.

Peccato che l’installazione non sia stata proprio una passeggiata. Dopo diversi tentativi ed errori, alla fine ce l’ho fatta. E visto che la documentazione ufficiale non è sempre chiarissima, ho pensato di scrivere questa guida per risparmiarti il mio stesso travaglio.

Nota: Questa guida è basata sulla mia esperienza personale su Linux Mint. Se usi un’altra distribuzione, alcuni comandi potrebbero variare leggermente.

Cosa ti serve prima di iniziare

Prima di mettere mano al terminale, assicurati di avere:

  • Linux Mint (o Ubuntu/Debian, dovrebbe funzionare)
  • Una connessione Internet (ovviamente)
  • Un account su OpenRouter se vuoi usare modelli gratuiti – ci arriveremo dopo
  • Un po’ di pazienza, perché qualche intoppo è praticamente garantito

Non serve essere esperti di terminale, ma sapere come muoversi con i comandi base aiuta.

Passo 1: Installare Node.js e npm

DeepSeek Harness è un’applicazione basata su Node.js, quindi la prima cosa da fare è installare l’ambiente di sviluppo. Su Linux Mint, il modo più affidabile è usare il repository ufficiale di NodeSource.

Apri il terminale (Ctrl+Alt+T) e incolla questi comandi uno dopo l’altro:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl build-essential
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Una volta finito, controlla che tutto sia andato a buon fine con:

node --version
npm --version

Se vedi due numeri di versione (es. v22.23.2 per Node e 10.9.8 per npm), sei a posto. Se invece il terminale ti dice “comando non trovato”, qualcosa è andato storto: riprova i passaggi precedenti.

Passo 2: Installare DeepSeek Harness

Con npm installato, possiamo procedere con l’installazione globale di DeepSeek Harness. Il comando è uno solo, ma preparati perché ci mette un po’ (scarica circa 456 pacchetti). Questa, che consiglio, è una installazione globale. Il comando npx @deepseek-ai/dsh web, presente sulla home di DeepSeek Harness, è come un “prova prima di comprare”: scarica il pacchetto al volo in una cache temporanea, lo esegue e poi se ne dimentica. Perfetto per fare un test senza installare nulla di permanente, ma con il rischio di doverlo riscaricare ogni volta (con tutti i tempi di attesa del caso) e senza avere un comando “dsh” sempre disponibile. Più che altro è utile per curiosare, ma non per un uso serio e quotidiano. Quindi procediamo:

sudo npm install -g @deepseek-ai/dsh

Durante l’installazione, potresti vedere un avviso del tipo “npm warn deprecated node-domexception@1.0.0“. Non preoccuparti, è solo un pacchetto obsoleto che DeepSeek usa ma che non causa problemi. Ignoralo e vai avanti.

A volte, però, l’installazione si blocca con un altro avviso che parla di “script bloccati”. Se ti capita, esegui questo comando che sovrascrive quello sopra:

sudo npm install -g @deepseek-ai/dsh --allow-scripts=koffi,node-pty,protobufjs,@deepseek-ai/dsh-subprocess-local,@google/genai

Questo permette di eseguire alcuni script necessari alle dipendenze native utilizzate da DeepSeek Harness.

Passo 3: Installare pnpm (servirà dopo)

A un certo punto, quando ho provato a installare i plugin, mi sono imbattuto in un errore: “dsh: pnpm not found on PATH“. In pratica, DeepSeek Harness usa pnpm per gestire i plugin, e io non lo avevo installato.

Rimediamo subito:

sudo npm install -g pnpm

Verifica che sia installato:

pnpm --version

Se vedi un numero (tipo 8.15.9), sei a posto. Se no, riavvia il terminale e riprova.

Passo 4: Creare un account su OpenRouter e configurarlo con Ori

Per usare DeepSeek Harness con i modelli gratuiti, ho scelto OpenRouter come provider. È un servizio che aggrega decine di modelli AI (DeepSeek, Google, Meta, ecc.) e permette di usarli con una sola chiave API. La parte migliore? Ci sono diversi modelli completamente gratuiti.

1. Registrazione su OpenRouter

  1. Vai su openrouter.ai e clicca su “Sign Up” in alto a destra.
  2. Puoi registrarti con Google, GitHub o con una email.
  3. Non serve aggiungere credito per iniziare: i modelli con il suffisso :free sono gratuiti e ti permettono di fare test senza spendere un centesimo.

Dopo la registrazione, ho creato la chiave API andando su openrouter.ai/keys ,cliccando su “Create Key” e dandole un nome. Ho copiato subito la chiave (inizia con sk-or-v1-...) e l’ho salvata in un posto sicuro, perché non viene mostrata una seconda volta.

2. Installare Ori (autenticazione automatica)

Invece di copiare e incollare la chiave API a mano, ho usato Ori, lo strumento ufficiale di OpenRouter. Il vantaggio? Non devi gestire chiavi, non devi impostare variabili d’ambiente, e le credenziali vengono salvate in modo sicuro.

Prima di tutto, installa Ori:

curl -fsSL https://openrouter.ai/labs/ori/install.sh | bash

Poi esegui il login:

ori login

A questo punto, Ori aprirà una finestra del browser per farti autenticare con OpenRouter. Accedi con il tuo account, approva l’accesso, e il gioco è fatto. Le credenziali vengono salvate in ~/.ori/credentials.json – non dovrai più preoccupartene.

Passo 5: Configurare il file settings.yaml

Qui è dove ho perso più tempo. I modelli più recenti richiedono che il “reasoning” (il ragionamento interno del modello) sia attivo. Se non lo configuri, riceverai un errore 400 che dice “Reasoning is mandatory for this endpoint“.

Apri il file di configurazione con un editor di testo:

nano ~/.dsh/profiles/web/settings.yaml

E modificalo così:

ui-onboarding:
  welcomeNoticeVersion: 2026-08-13.1

llm-pi-ai:
  providers:
    openrouter:
      apiKeyEnv: OPENROUTER_API_KEY
      models:
        - id: openrouter/free
          reasoning: true
          reasoning_effort: medium

agent-default-model:
  provider: openrouter
  model: openrouter/free

Salva (Ctrl+O) ed esci (Ctrl+X). Se non ti senti sicuro a modificare il file, puoi anche saltare questo passaggio e, se vedrai l’errore 400, tornerai qui a sistemarlo.

Passo 6: Avviare e testare

Finalmente, il momento della verità. Avvia DeepSeek Harness con:

dsh web

Apri il browser e vai su http://127.0.0.1:3080. Se vedi l’interfaccia web, sei già a buon punto.

Attenzione: Il terminale deve rimanere aperto finché usi DeepSeek Harness. Se chiudi il terminale, il server si ferma. Per uscire, premi Ctrl+C.

Passo 7: Come aggiornare DeepSeek Harness

DeepSeek Harness non si aggiorna automaticamente. Se lo hai installato globalmente con npm, quando viene pubblicata una nuova versione puoi aggiornarlo direttamente dal terminale, senza dover disinstallare quella precedente: npm la sostituirà automaticamente con quella nuova.

Per controllare la versione installata:

dsh --version

Per sapere invece qual è l’ultima versione disponibile su npm:

npm view @deepseek-ai/dsh version

Se i due numeri sono diversi, significa che è disponibile un aggiornamento.

Se per l’installazione hai usato il comando normale:

sudo npm install -g @deepseek-ai/dsh

per installare l’ultima versione disponibile usa:

sudo npm install -g @deepseek-ai/dsh@latest

Se invece hai dovuto utilizzare il comando con gli script autorizzati:

sudo npm install -g @deepseek-ai/dsh --allow-scripts=koffi,node-pty,protobufjs,@deepseek-ai/dsh-subprocess-local,@google/genai

usa lo stesso metodo anche per gli aggiornamenti:

sudo npm install -g @deepseek-ai/dsh@latest --allow-scripts=koffi,node-pty,protobufjs,@deepseek-ai/dsh-subprocess-local,@google/genai

Nota: DeepSeek Harness è ancora in fase di sviluppo e le nuove versioni possono introdurre modifiche o incompatibilità. Prima di aggiornare, soprattutto se hai un’installazione perfettamente funzionante, è quindi consigliabile controllare le eventuali novità della nuova release.

Errori che ho incontrato (e come li ho risolti)

Visto che la documentazione ufficiale non copre tutti i casi, ecco una lista degli errori che ho visto e le relative soluzioni:

❌ “Command ‘npx’ not found”

Causa: Node.js non installato.
Soluzione: Torna al Passo 1.

❌ “pnpm not found on PATH”

Causa: pnpm non installato o non accessibile.
Soluzione: Installa pnpm con sudo npm install -g pnpm e riavvia il terminale.

❌ “Reasoning is mandatory for this endpoint”

Causa: Il modello richiede il reasoning attivo, ma è disabilitato nella configurazione.
Soluzione: Aggiungi reasoning: true a settings.yaml (Passo 5).

❌ “This model is unavailable for free”

Causa: Il modello gratuito che stai cercando di usare non è più disponibile su OpenRouter. I modelli gratuiti cambiano spesso, quindi è normale che uno slug come deepseek/deepseek-v4-flash:free smetta di funzionare da un giorno all’altro.
Soluzione: Usa il router intelligente openrouter/free. Questo slug non punta a un modello fisso, ma sceglie automaticamente il miglior modello gratuito disponibile in quel momento. È la soluzione più stabile. Lo abbiamo impostato sopra in settings.yaml (consigliato), ma si può anche usare l’interfaccia web in questo modo:

  1. Da DeepSeek harness (http://127.0.0.1:3080) vai su Settings → Models
  2. Trova il provider OpenRouter e clicca su Edit
  3. Nel campo Model ID, scrivi openrouter/free
  4. Salva e seleziona il modello dalla chat

❌ “MISSING_CREDENTIAL”

Causa: La chiave API di OpenRouter non è stata configurata.
Soluzione: Esegui ori login (Passo 4).

Una nota sulla privacy

Una delle ragioni per cui ho scelto DeepSeek Harness è che tutto rimane in locale. Quando analizzi una cartella del tuo computer, i file non vengono caricati da nessuna parte: il modello riceve solo il testo necessario per rispondere, ma i tuoi dati restano sul tuo disco.

Certo, le richieste vengono inviate al provider (OpenRouter, DeepSeek, ecc.), ma puoi scegliere modelli che rispettano la privacy. Se vuoi un livello di protezione extra, esiste anche un plugin chiamato dsh-mask che maschera i dati sensibili (numeri di telefono, email, ecc.) prima di inviarli al modello.

E ora?

Ora che tutto funziona, puoi iniziare a esplorare. Alcune cose che puoi fare:

  • Chat libera con il modello che preferisci
  • Analisi di cartelle (es. per estrarre informazioni da documenti)
  • Benchmark per confrontare le performance dei diversi modelli
  • Ricerca web (grazie al plugin AnySearch)

Io l’ho usato per analizzare un mucchio di documenti di lavoro e devo dire che, una volta superato lo scoglio dell’installazione, è uno strumento che dà davvero soddisfazione.

Buon lavoro!

Installare DeepSeek Harness su Linux Mint non è immediato, ma con questa guida spero di averti risparmiato qualche ora di tentativi. Se hai domande o incontri errori che non sono elencati qui, scrivi e cercherò di aiutarti.

Buon lavoro con DeepSeek Harness e Luna42.net! 🚀

Condividi su Facebook, X, ...