DeepSeek Harness

DeepSeek Harness è un ambiente open source per usare agenti AI capaci di lavorare in contesti reali: leggere file, usare strumenti, aprire sessioni, interagire con il terminale e collegarsi a diversi provider di modelli linguistici.

Non è solo una chat. È un harness, cioè una struttura che collega una LLM a strumenti concreti. Il modello è il “cervello”; Harness è il sistema che gli permette di operare.

La cosa più interessante è che DeepSeek Harness può essere usato in due configurazioni:

1. Cloud, con le API ufficiali DeepSeek.
2. Locale, con una LLM installata tramite Ollama e servita da un endpoint compatibile OpenAI.

La seconda modalità è fantastica perché può azzerare i costi a token, aumentare la privacy e ridurre la dipendenza da servizi esterni.

Nota: DeepSeek Harness è in developer preview. Alcuni comandi o dettagli di configurazione possono cambiare nelle versioni future.

Cos’è DeepSeek Harness

DeepSeek Harness segue una logica semplice:

Agent = Model + Harness

Una LLM da sola genera testo. Un agente, invece, può usare strumenti e lavorare dentro un ambiente operativo. DeepSeek Harness fornisce proprio questa parte: plugin, sessioni, provider LLM, strumenti, UI web, filesystem, shell e configurazione.

In termini pratici, con Harness puoi chiedere a un agente di:

• analizzare una codebase;
• spiegare l’architettura di un progetto;
• modificare file;
• proporre refactoring;
• eseguire comandi;
• lavorare dentro una directory locale;
• usare provider diversi senza cambiare completamente strumento.

L’architettura è basata su plugin. I provider LLM, gli strumenti e i servizi vengono composti tramite configurazione. Questo significa che puoi partire con DeepSeek via API e poi passare a Ollama in locale mantenendo lo stesso ambiente di lavoro.

Perché usare DeepSeek Harness

I vantaggi principali sono:

• Flessibilità: supporta provider cloud, gateway compatibili OpenAI e modelli locali.
• Controllo: puoi decidere modello, endpoint, credenziali e comportamento.
• UI web integrata: avviabile in locale su browser.
• Uso tecnico ma accessibile: adatto a sviluppatori, data worker, power user e team.
• Privacy: con Ollama i prompt e i file possono restare sulla macchina locale.
• Costi ridotti: in locale non paghi token a un provider cloud.

Prerequisiti

Per usare DeepSeek Harness servono:

• Node.js, necessario per eseguire il pacchetto @deepseek-ai/dsh;
• un terminale: PowerShell, Windows Terminal, Bash, zsh o simili;
• una API key DeepSeek, se vuoi usare il cloud;
• Ollama, se vuoi usare un modello locale.

Verifica Node.js:

node --version
npm --version

Se non è installato, scaricalo da https://nodejs.org/.

Installare e avviare DeepSeek Harness

Il modo più rapido è usare npx:

npx @deepseek-ai/dsh web

Questo avvia la Web UI su:

http://127.0.0.1:3080

In alternativa puoi installarlo globalmente:

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

Poi avviarlo con:

dsh web

Comandi utili:

dsh web --no-open

Avvia la UI senza aprire automaticamente il browser.

dsh web --port 3081

Avvia la UI su un’altra porta.

dsh web --dump-config

Mostra la configurazione effettiva composta da Harness.

Configurazione con le API DeepSeek

La configurazione cloud è la più diretta: Harness usa i modelli ufficiali DeepSeek tramite API.

1. Ottieni la API key DeepSeek

Crea una chiave API dalla piattaforma DeepSeek. L’endpoint ufficiale è normalmente:

https://api.deepseek.com

2. Avvia Harness

dsh web

oppure:

npx @deepseek-ai/dsh web

3. Configura la chiave nella UI

Nella Web UI vai in:

Settings → Models

Inserisci la chiave nella scheda DeepSeek e salva.

DeepSeek Harness gestisce le chiavi come credenziali: la UI salva il riferimento alla credenziale, mentre il valore sensibile viene conservato nell’home di Harness. È meglio evitare di scrivere chiavi API direttamente nei file YAML.

Metodo alternativo: variabile d’ambiente

Su macOS/Linux:

export DEEPSEEK_API_KEY="la-tua-api-key"
dsh web

Su Windows PowerShell:

$env:DEEPSEEK_API_KEY="la-tua-api-key"
dsh web

Per renderla persistente su Windows:

setx DEEPSEEK_API_KEY "la-tua-api-key"

Poi riapri il terminale.

Provider e modelli

L’adapter nativo di DeepSeek Harness registra il provider:

deepseek-official

I modelli disponibili dipendono dalla versione e dalla configurazione, ma nella UI potrai selezionare il modello DeepSeek da usare per le nuove sessioni.

Come si usa DeepSeek Harness

Dopo l’avvio, apri la UI web e crea una nuova sessione. Seleziona una cartella di lavoro e chiedi all’agente, per esempio:

Analizza questo progetto e spiegami l’architettura.

Oppure:

Trova eventuali problemi nel codice e proponi un refactoring.

Oppure:

Crea una piccola CLI Node.js in questa directory.

La differenza rispetto a una normale chat è che l’agente può usare strumenti reali nel contesto della cartella scelta.

Configurazione locale con Ollama

Con Ollama puoi installare una LLM localmente e farla usare a DeepSeek Harness tramite endpoint compatibile OpenAI.

Schema della configurazione:

DeepSeek Harness → provider custom OpenAI-compatible → Ollama → modello locale

L’endpoint locale di Ollama è di solito:

http://localhost:11434/v1

Questa configurazione è ideale se vuoi:

• non pagare token;
• lavorare su dati privati;
• testare agenti AI senza costi ricorrenti;
• usare modelli diversi in base all’hardware disponibile.

Installare Ollama e scaricare una LLM

Installa Ollama da:

https://ollama.com/

Verifica:

ollama --version

Scarica un modello. Esempio con Qwen3 8B:

ollama pull qwen3:8b

Oppure con DeepSeek-R1 8B:

ollama pull deepseek-r1:8b

Test rapido:

ollama run qwen3:8b

Elenco dei modelli installati:

ollama list

Metodo semplice: Ollama Launch

Ollama include un’integrazione per DeepSeek Harness. Il comando più comodo è:

ollama launch dsh

Per scegliere un modello:

ollama launch dsh --model qwen3:8b

oppure:

ollama launch dsh --model deepseek-r1:8b

Per configurare senza avviare subito:

ollama launch dsh --config

Ollama salva le impostazioni in:

~/.ollama/launch/dsh/settings.yaml

Su Windows il percorso è in genere:

C:\Users\TUO_UTENTE\.ollama\launch\dsh\settings.yaml

Questa modalità è consigliata se vuoi arrivare rapidamente a una configurazione locale funzionante.

Metodo manuale: aggiungere Ollama come provider custom

Puoi anche configurare Ollama direttamente dalla UI di DeepSeek Harness.

Apri:

dsh web

Vai in:

Settings → Models → Add a custom provider

Inserisci:

Provider ID: ollama-local
Display name: Ollama locale
Base URL: http://localhost:11434/v1
API protocol: openai-completions
API key: ollama
Model: qwen3:8b

L’API key ollama è un segnaposto: l’istanza locale di Ollama normalmente non richiede una vera chiave API. Molti client OpenAI-compatible, però, si aspettano comunque un campo API key.

Se disponibile, usa Fetch available models: Harness interroga /v1/models, endpoint supportato da Ollama.

Configurazione manuale via settings.yaml

Gli utenti più tecnici possono modificare il file:

~/.dsh/settings.yaml

Su Windows:

C:\Users\TUO_UTENTE\.dsh\settings.yaml

Esempio:

llm-pi-ai:
  providers:
    ollama-local:
      displayName: Ollama locale
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens
      models:
        - id: qwen3:8b
          name: Qwen3 8B locale
          contextWindow: 32768
          maxTokens: 4096

Poi imposta la variabile d’ambiente.

macOS/Linux:

export OLLAMA_API_KEY="ollama"
dsh web

Windows PowerShell:

$env:OLLAMA_API_KEY="ollama"
dsh web

Nella UI seleziona il provider ollama-local e il modello configurato.

Perché usare compat

Gli endpoint OpenAI-compatible non sono sempre identici a OpenAI. Due differenze frequenti sono:

• il ruolo developer non sempre è accettato;
• il limite di output può chiamarsi max_tokens invece di max_completion_tokens.

Per questo nell’esempio usiamo:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

Se il provider locale rifiuta le richieste, questi sono i primi parametri da verificare.

Testare Ollama prima di usarlo con Harness

Prima di configurare Harness, controlla che Ollama risponda come endpoint OpenAI-compatible:

curl http://localhost:11434/v1/models

Test di completamento chat:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {"role": "user", "content": "Scrivi una frase in italiano."}
    ],
    "stream": false
  }'

Se ricevi una risposta JSON, Ollama è raggiungibile.

API DeepSeek vs Ollama locale

Usa API DeepSeek se:

• vuoi modelli potenti senza gestire hardware;
• ti serve velocità costante;
• lavori su task complessi;
• accetti il costo a consumo.

Usa Ollama locale se:

• vuoi ridurre o azzerare i costi a token;
• lavori su codice o documenti sensibili;
• preferisci mantenere i dati sul computer;
• vuoi sperimentare liberamente;
• hai hardware sufficiente.

La soluzione migliore spesso è ibrida: Ollama per attività quotidiane e DeepSeek API per task più difficili.

Risoluzione problemi

MISSING_CREDENTIAL

Harness non trova la credenziale richiesta. Imposta DEEPSEEK_API_KEY per DeepSeek o OLLAMA_API_KEY=ollama per la configurazione manuale con Ollama.

UNKNOWN_MODEL

Il modello non è stato configurato o non esiste in Ollama. Controlla:

ollama list

Il nome nel file YAML deve coincidere esattamente, ad esempio qwen3:8b.

L’endpoint locale non risponde

Verifica:

curl http://localhost:11434/v1/models

Se non risponde, Ollama non è avviato o la porta è diversa.

Il provider rifiuta le richieste

Controlla i campi compat, in particolare:

supportsDeveloperRole: false
maxTokensField: max_tokens

Il modello locale è lento

È normale se gira su CPU o se il modello è grande. Prova modelli più piccoli o quantizzati, oppure usa una GPU supportata.

Conclusione

DeepSeek Harness è un ambiente potente perché separa l’agente dal provider del modello. Puoi usarlo con le API DeepSeek per avere potenza cloud, oppure con Ollama per lavorare in locale con più privacy e senza costi a token.

La combinazione DeepSeek Harness + Ollama è particolarmente utile per sviluppatori e team che vogliono sperimentare agenti AI su progetti reali mantenendo controllo, riservatezza e sostenibilità economica.