SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-11-06

Configurare dsh: chiavi API, modelli ed endpoint

Scopri dove dsh salva la configurazione su Linux, come usare una chiave DeepSeek o un endpoint Ollama locale e cosa esce esattamente dal sistema.

Dove dsh mantiene la configurazione

dsh (DeepSeek Harness) mantiene i dati del proprio harness in $DSH_HOME, che per impostazione predefinita è ~/.dsh, e legge la configurazione condivisa degli agenti da una radice separata, $DSH_AGENTS_HOME, che per impostazione predefinita è ~/.agents. Tutto ciò che si imposta nella Web UI viene scritto lì come file di testo. Quando si sposta la configurazione su un altro server, copiare la home dell’harness e le istruzioni e le skill globali dalla radice condivisa degli agenti.

Quattro percorsi contengono le impostazioni principali dell’harness, i secret e i log delle sessioni.

  • ~/.dsh/profiles/<profile>/cordis.patch.yml contiene le impostazioni scritte dalla Web UI per quel profilo, inclusi il provider e i percorsi dei modelli. dsh web esegue il profilo web, quindi il file è ~/.dsh/profiles/web/cordis.patch.yml.
  • ~/.dsh/.credentials.yaml contiene i secret. Le impostazioni conservano soltanto un riferimento a una credenziale, quindi il valore della chiave si trova in un unico file.
  • ~/.dsh/profiles/ contiene i profili denominati, mentre ~/.dsh/sessions/ contiene i log delle sessioni salvate.
  • ~/.dsh/cordis.patch.yml è il proprio livello di personalizzazione. Viene applicato sopra la configurazione integrata per ogni profilo e ha precedenza sul file del profilo. Di conseguenza, una modifica della Web UI che verrebbe sovrascritta da questo livello viene rifiutata invece di essere salvata.

La radice condivisa degli agenti resta al di fuori di $DSH_HOME perché viene usata anche da altri strumenti per agenti. dsh legge le istruzioni globali dell’utente da ~/.agents/AGENTS.md e cerca le skill in ~/.agents/skills/; impostare DSH_AGENTS_HOME consente di spostare questa radice.

Le build precedenti conservavano queste impostazioni in ~/.dsh/settings.yaml. Le build attuali importano quel file una volta nel profilo attivo e lo rinominano in settings.yaml.imported, quindi una guida precedente che indica di modificare settings.yaml fa ora riferimento a un file che dsh non legge più.

DeepSeek pubblica l’harness come anteprima per sviluppatori con licenza MIT e il README specifica che saranno introdotte modifiche incompatibili. I nomi dei campi e i percorsi riportati in questa guida corrispondono alla documentazione attuale del repository, verificata il 5 novembre 2026. Prima di copiare la configurazione da una guida, compresa questa, verificarli nella documentazione della versione installata, perché un’anteprima può rinominare gli elementi tra una release e l’altra.

Il minimo onesto per ottenere il primo output

dsh richiede Node.js 24.9 o versioni successive. Al 5 novembre 2026 il suo package.json dichiara >=24.9.0, quindi la linea 22 non è supportata. Anche Node 24.0–24.8 non è sufficiente. Controlla prima la versione, perché una mancata corrispondenza causa un errore all'avvio che può sembrare dovuto a un pacchetto danneggiato.

node -v
npx @deepseek-ai/dsh web

npx scarica il pacchetto dal registro npm e avvia la Web UI su http://127.0.0.1:3080. Si associa all'indirizzo di loopback, quindi la porta non è raggiungibile da un altro computer anche se il firewall ne consente il traffico. Su un VPS, inoltrala tramite SSH invece di esporre la porta 3080 a Internet. Se l'URL visualizzato è il punto poco chiaro, perché dsh si avvia su quell'indirizzo spiega cosa protegge l'associazione a loopback e cosa invece non protegge.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Apri http://127.0.0.1:3080 sul laptop, quindi vai a Settings e Models. La scheda DeepSeek contiene un solo campo per la chiave API. Incolla la chiave ottenuta da platform.deepseek.com e salvala. Il percorso del modello diventa immediatamente utilizzabile, senza riavvio, perché il server in esecuzione memorizza la credenziale e risolve il riferimento in tempo reale. Raggiungere la Web UI di dsh su un server remoto descrive il caso del tunnel e del reverse proxy, mentre installare DeepSeek Harness su un VPS descrive la preparazione del server presupposta da questa guida.

Dopo il salvataggio, controlla cosa ha creato l'applicazione.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

Dovresti vedere .credentials.yaml e profiles/, con le impostazioni della Web UI in profiles/web/cordis.patch.yml. Una home directory creata da una build precedente può contenere anche settings.yaml.imported. Se stat restituisce una modalità diversa da 600, esegui chmod 600 ~/.dsh/.credentials.yaml. Un file delle credenziali leggibile dal gruppo espone la chiave agli account appartenenti a quel gruppo; un file leggibile da tutti gli account la espone a ogni altro account del sistema.

Per una prima esecuzione senza browser è sufficiente un comando.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

Il profilo headless esegue una singola sessione e visualizza la risposta finale.

Variabili d’ambiente o file di configurazione

dsh può risolvere una chiave dalle credenziali salvate o dai fallback delle variabili d’ambiente.

Un provider di catalogo (DeepSeek, Anthropic, OpenAI e gli altri provider inclusi nell’elenco integrato) accetta una chiave tramite la pagina Models oppure usa il fallback della variabile d’ambiente supportata quando nessuna credenziale salvata la fornisce. Il valore viene inserito in ~/.dsh/.credentials.yaml e le impostazioni contengono soltanto un riferimento a tale valore. Dopo il salvataggio, la Web UI non mostra più la chiave.

Un provider personalizzato può specificare un riferimento a una credenziale con apiKeyEnv, che supporta a sua volta i fallback delle variabili d’ambiente. Questa è la struttura indicata nella documentazione per una voce in una patch del profilo come ~/.dsh/profiles/web/cordis.patch.yml.

- id: llm-pi-ai
  config:
    providers:
      my-gateway:
        apiKeyEnv: GATEWAY_API_KEY
        api: openai-completions
        baseURL: https://gateway.example/v1
        models:
          - id: legacy-chat
          - id: vision-preview
            input: [text, image]

Aggiungi prima un provider tramite la Web UI, quindi apri cordis.patch.yml del profilo e copia la struttura generata. Durante un’anteprima per sviluppatori, la struttura annidata è l’elemento più soggetto a modifiche e il file appena scritto dall’applicazione è sempre aggiornato.

apiKeyEnv risolve la credenziale tramite il relativo archivio: prima viene usato il file salvato, poi l’ambiente di avvio, quindi .env della directory da cui viene eseguito il comando e infine $DSH_HOME/.env. Una chiave esportata soltanto in una sessione interattiva non è visibile a un’unità systemd. Di conseguenza, senza un’altra sorgente di credenziali, la stessa configurazione che funziona quando digiti manualmente dsh web restituisce MISSING_CREDENTIAL quando viene eseguita da un servizio. Assegna all’unità un file dedicato.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

Mantieni quel file con permessi 600 e assegnalo come proprietario all’utente con cui viene eseguito il servizio.

Scelta dei modelli e ID che non puoi rinominare

Ogni provider configurato appare nel selettore dei modelli. La selezione di un modello lo imposta anche come predefinito per le nuove sessioni. Le sessioni che hanno già inviato una richiesta conservano il modello registrato al loro interno, quindi il cambio non modifica una conversazione precedente.

Il Provider ID è permanente. Le richieste, le sessioni salvate, i modelli predefiniti e i riferimenti alle credenziali puntano tutti a questo ID, quindi non esiste un pulsante per rinominarlo. Per modificarlo devi creare un nuovo provider ed eliminare quello precedente. Scegli un nome che possa restare invariato: local-ollama invece di test2.

I modelli personalizzati senza capacità di gestione delle immagini ereditata sono solo testuali, salvo diversa dichiarazione. Aggiungi input: [text, image] alla voce del modello per dichiarare il supporto alle immagini oppure imposta defaultInput a livello di route come fallback per i modelli non descritti nel catalogo. Sulla route proprietaria di DeepSeek, un modello senza modalità dichiarate viene considerato solo testuale; quindi seleziona una voce del catalogo compatibile con le immagini (deepseek-flash per impostazione predefinita) prima di allegare un'immagine. Un'immagine inviata a un modello che non dichiara il supporto alle immagini viene rifiutata prima dell'invio.

Indirizza dsh a un endpoint locale per mantenere il codice sul server

Ollama espone un'API compatibile con OpenAI su http://127.0.0.1:11434/v1. dsh può comunicare con qualsiasi URL di base compatibile con OpenAI tramite un provider personalizzato, quindi i due componenti si collegano direttamente. Configura prima il server del modello: self-hosting di un LLM con Ollama su un VPS descrive l'installazione e il download del modello.

Verifica che l'endpoint risponda prima di modificare dsh.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list stampa il tag esatto di ogni modello scaricato. Copia questa stringa. curl restituisce gli stessi modelli in formato JSON. Un elenco vuoto indica che Ollama è in esecuzione senza modelli scaricati. Connection refused indica che Ollama non è in esecuzione oppure non è in ascolto sulla porta 11434.

Scegli un modello compatibile con questa macchina. Un server Ollama autenticato espone anche i modelli cloud tramite lo stesso indirizzo locale. Un tag cloud come gemma4:cloud viene eseguito sui server di Ollama, quindi i prompt lasciano il server anche se dsh comunica soltanto con 127.0.0.1.

Aggiungi quindi il provider alla patch del profilo. Per questa configurazione specifica un valore non vuoto per la chiave API; il server Ollama locale la ignora.

- id: llm-pi-ai
  config:
    providers:
      local-ollama:
        apiKeyEnv: OLLAMA_API_KEY
        api: openai-completions
        baseURL: http://127.0.0.1:11434/v1
        models:
          - id: <the exact tag printed by ollama list>

Esporta la variabile nell'ambiente in cui sarà visibile al processo dsh.

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

Tre errori coprono quasi tutti i tentativi. MISSING_CREDENTIAL indica che il riferimento specificato da apiKeyEnv non ha prodotto alcun valore. Controlla quindi le credenziali salvate e l'ambiente di avvio, non soltanto il terminale. UNKNOWN_MODEL indica che id non corrisponde a un modello configurato. Confrontalo carattere per carattere con ollama list, incluso il tag dopo i due punti. Un errore 401 durante il recupero dei modelli disponibili proviene dal rilevamento dei modelli, che chiama GET /models sull'URL di base. Gli endpoint che non espongono questo percorso richiedono l'inserimento manuale dei modelli.

Un altro problema possibile riguarda l'URL di base. Se ometti /v1, le richieste vengono inviate a percorsi che Ollama non espone. La chiamata restituisce quindi un errore 404 e il modello non viene mai eseguito. Il suffisso fa parte dell'interfaccia compatibile con OpenAI; non è un elemento ornamentale.

Se Ollama è in esecuzione su un'altra macchina, l'indirizzo di quella macchina diventa l'URL di base. I prompt attraversano quindi la rete in chiaro tramite HTTP semplice. Mantieni Ollama sullo stesso host oppure pubblicalo dietro TLS (Transport Layer Security) e autenticazione: proteggere un endpoint Ollama esposto.

Cosa lascia il sistema in ciascuna modalità

Con una chiave DeepSeek e l'endpoint predefinito, le richieste al modello vengono inviate all'API di DeepSeek. La richiesta contiene il prompt, il contenuto dei file letti dall'agente per rispondere, l'output dei comandi eseguiti e gli eventuali risultati degli strumenti che l'agente ha scelto di includere. Quando l'agente apre un file, il codice sorgente si trova all'interno di quel payload. Questo è il funzionamento di un modello ospitato ed è il motivo per cui occorre valutare con attenzione la directory dalla quale si avvia l'agente.

Le release attuali allegano inoltre alle richieste, tramite l'adapter nativo DeepSeek e per impostazione predefinita, un suffisso non ancora accettato del log degli eventi della sessione, inclusi i gateway configurati, in un campo dsh_session_log separato. Il modello non lo vede, ma la destinazione della richiesta lo riceve. Disattivare questa funzione in Settings, General ("Upload Session Log when using the official model API") oppure impostare enabled: false sul plugin session-log-deepseek. Gli switch di telemetria riportati di seguito non controllano questo caricamento.

I profili distribuiti inviano inoltre i nomi e le versioni dei pacchetti dei plugin attivi tramite l'adapter nativo DeepSeek, in un campo dsh_plugin_packages separato. Impostare enabled: false su plugin-package-inventory-deepseek per impedire questo contributo.

Con un altro provider del catalogo o con un gateway aziendale, lo stesso payload viene inviato invece a quel fornitore. L'URL di base indica esattamente la destinazione.

Con un endpoint locale, la richiesta al modello viene inviata a 127.0.0.1:11434, ma il solo indirizzo di loopback non garantisce che resti sul sistema. La documentazione di Ollama afferma: "To use cloud models through this server, sign in to Ollama," quindi un modello cloud selezionato tramite lo stesso server locale invia prompt e codice al cloud di Ollama. La richiesta al modello resta sul sistema solo quando il modello viene eseguito localmente. Anche in questo caso, tre elementi attraversano la rete. npx scarica il pacchetto dal registry npm. Qualsiasi strumento eseguito dall'agente può raggiungere autonomamente Internet, inclusi i server MCP (model context protocol) a cui ci si è connessi; l'articolo eseguire server MCP su un VPS tratta questo argomento in dettaglio. Un plugin rientra nella stessa categoria, perché installarlo esegue codice di un altro autore con i permessi dell'agente; è quindi opportuno verificare a cosa può accedere un plugin prima di installarlo. Lo stesso vale per la telemetria, che nelle release attuali autorizza l'esportazione verso DeepSeek ogni volta che si invia un feedback, esattamente come con un modello ospitato.

Per impostazione predefinita, la telemetria è limitata al feedback. DSH_TELEMETRY_MODE seleziona la modalità e, nella configurazione di base attualmente distribuita, un valore non impostato o vuoto viene risolto in FEEDBACK_ONLY. In questa modalità, la normale attività non autorizza alcuna raccolta di telemetria. Quando si invia un feedback scritto, si crea o modifica una valutazione, si modifica una nota oppure si ritira un feedback, dsh autorizza l'esportazione verso https://dsh-otel-collector.deepseeksvc.com/v1/logs del prefisso del log della sessione non ancora consegnato all'exporter, attraverso quell'evento di feedback e includendo il contesto ereditato. La consegna completa non è garantita: un evento troppo grande viene rifiutato senza troncamento e, all'uscita dalla CLI, i prefissi di grandi dimensioni possono rimanere parzialmente non inviati. I batch autorizzati possono continuare a essere inviati senza un'altra interazione o chiamata al modello. Il README della telemetria specifica che questo vale "for all users and providers", quindi l'esecuzione locale del modello non disattiva la funzione. DISABLED non crea alcun trasporto OpenTelemetry (OTel). FULL non è più accettato: qualsiasi valore diverso dai due indicati viene rifiutato con unsupported mode. Un'esportazione di feedback può contenere testo dei messaggi, argomenti e risultati degli strumenti e percorsi del workspace; il feedback va quindi considerato come un'autorizzazione all'invio a DeepSeek del prefisso della sessione.

Per un blocco completo che non dipenda dall'impostazione corretta della stringa della modalità, impostare DSH_TELEMETRY_DISABLED=1. Qualsiasi valore non vuoto costituisce un opt-out autorevole, inclusi 0 e false, e viene letto prima dell'avvio dell'esecuzione; il codice del progetto non può quindi riattivarlo durante la sessione. L'indirizzo predefinito del collector è dsh-otel-collector.deepseeksvc.com; DSH_TELEMETRY_OTLP_URL lo sostituisce.

Verificare invece di fidarsi dell'impostazione. Con un'attività in esecuzione, elencare le connessioni in uscita mantenute dal processo.

sudo ss -tnp | grep -i node

Con un modello eseguito localmente, il traffico del modello usa la porta di loopback 11434, ma le connessioni pubbliche possono comunque essere originate dagli strumenti senza che sia stato inviato alcun feedback. I profili distribuiti includono ricerca e recupero web e il preset di autorizzazioni predefinito non limita l'accesso alla rete. Identificare ogni destinazione pubblica prima di attribuirla alla telemetria; il solo tempismo non dimostra che una connessione sia l'esportazione del feedback. Questo snapshot può inoltre non rilevare le connessioni di breve durata. Il controllo riguarda solo il processo dsh: il traffico di un modello cloud esce dal server Ollama, quindi verificare anche che il modello id non sia un tag cloud. Qualsiasi altra destinazione deve essere identificata prima di procedere. Cosa invia un coding agent all'esterno esegue lo stesso controllo su altri harness e spiega come interpretare il risultato.

Dove non memorizzare i secret

  • Cronologia della shell. export DEEPSEEK_API_KEY=sk-... viene scritto in ~/.bash_history in chiaro e resta lì molto tempo dopo la rotazione della chiave. Anteponi uno spazio al comando quando HISTCONTROL=ignorespace è impostata oppure evita la shell e scrivi direttamente il valore in un file con modalità 600.
  • File dot versionati. Una chiave in ~/.bashrc o ~/.zshrc è a un solo git add di distanza da un repository pubblico se memorizzi i file dot in git. Esegui git grep -I -n 'sk-' in quel repository prima del push.
  • File di patch dei profili. Usa apiKeyEnv per i provider personalizzati, in modo che cordis.patch.yml contenga il nome di una variabile anziché un secret. I file di configurazione vengono incollati nei report dei problemi e nelle chat con il supporto. I file delle credenziali no.
  • Output di env e screenshot del terminale. Qualsiasi comando che stampa l’intero ambiente stampa anche la chiave.
  • Backup. Vale la pena eseguire il backup di ~/.dsh, ma .credentials.yaml al suo interno è un secret attivo. Escludi quel file oppure cifra l’archivio.

Queste regole non sono specifiche di dsh e mantenere i secret fuori dai file env di Compose tratta lo stesso problema dal lato dei container sullo stesso server.

Gestire una developer preview

Bloccare la versione testata è importante, perché una preview può modificare una chiave di configurazione in una patch release e impedire al provider di caricarsi. Se l'installazione con versione bloccata rifiuta di avviarsi oppure npx continua a fornire una build diversa da quella richiesta, gli errori di installazione e versione prodotti da una preview descrive la cache di npx e la versione di npm inclusa in Node. Mantieni la home cordis.patch.yml e i file delle patch in profiles/ sotto controllo versione, escludendo il file delle credenziali, così puoi vedere cosa è cambiato dopo un aggiornamento.

Due flag sono utili quando un profilo non si comporta come previsto. --dump-default-config stampa la configurazione predefinita composta senza avviare il servizio, mentre --dump-config stampa nello stesso modo la configurazione composta per il tuo profilo. Il confronto mostra quali modifiche ha realmente applicato il livello delle patch, ed è più rapido che leggere manualmente i vari livelli.

dsh --profile web --dump-config

Quando qualcosa si rompe dopo un aggiornamento, esegui prima questo comando. Una chiave spostata tra una release e l'altra appare nel dump come un ramo mancante; la correzione richiede una modifica di una sola riga, non una reinstallazione.

FAQ

Dove memorizza dsh la mia chiave API di DeepSeek?

In $DSH_HOME/.credentials.yaml, ovvero ~/.dsh/.credentials.yaml, a meno che non impostiate personalmente DSH_HOME. La pagina Models scrive la chiave in quel file e le impostazioni contengono soltanto un riferimento, quindi il secret resta in un unico file. Verificate i permessi con stat -c '%a %n' ~/.dsh/.credentials.yaml e impostateli su 600 se sono meno restrittivi. Un provider personalizzato può evitare del tutto il file specificando una variabile d’ambiente con apiKeyEnv.

Come posso fare in modo che dsh usi un modello locale invece dell’API di DeepSeek?

Aggiungete un provider personalizzato con come base URL il vostro endpoint locale compatibile con OpenAI. Per Ollama è http://127.0.0.1:11434/v1, con api: openai-completions e un modello id copiato esattamente da ollama list. Per questa configurazione fornite un valore non vuoto per la chiave API; il server Ollama locale lo ignora. Verificate la risposta dell’endpoint con curl -s http://127.0.0.1:11434/v1/models prima di modificare la configurazione di dsh, perché un endpoint non raggiungibile e una configurazione errata producono errori simili.

dsh invia il mio codice da qualche parte per impostazione predefinita?

Con un modello ospitato, sì. Il prompt e il contenuto dei file letti dall’agente vengono inclusi nella richiesta API inviata al relativo provider. Anche le richieste tramite l’adapter nativo di DeepSeek, inclusi i gateway configurati, trasportano per impostazione predefinita un suffisso del log di sessione finché non disabilitate l’upload in Settings, General. Con un modello eseguito localmente da Ollama, la richiesta viene inviata al loopback e resta sul computer. Tuttavia, un modello cloud come gemma4:cloud la inoltra al cloud di Ollama attraverso lo stesso indirizzo di loopback. La ricerca web e il fetch integrati, gli altri strumenti e i plugin possono contattare autonomamente servizi pubblici, indipendentemente dal feedback. La telemetria è un flusso separato: nelle release attuali DSH_TELEMETRY_MODE restituisce FEEDBACK_ONLY quando non è impostato. Di conseguenza, il feedback autorizza l’esportazione del prefisso del log di sessione tramite quell’evento, incluso il contesto ereditato, per ogni provider, compresi i modelli locali. La consegna non è garantita e gli upload autorizzati possono continuare dopo l’interazione di feedback. Impostatelo su DISABLED per non usare alcun exporter, oppure impostate DSH_TELEMETRY_DISABLED=1 per un opt-out letto prima dell’avvio dell’esecuzione.

Perché dsh segnala MISSING_CREDENTIAL quando la mia variabile è impostata?

Perché il riferimento indicato da apiKeyEnv deve essere risolto nelle origini delle credenziali di dsh. Le credenziali salvate hanno la precedenza rispetto all’ambiente di avvio. Seguono .env e $DSH_HOME/.env della directory da cui viene avviato il processo. Una variabile esportata nella shell non è disponibile per un servizio systemd, per la sessione di un altro utente o per un processo avviato prima dell’esportazione. Inserite il valore in un EnvironmentFile con permessi 600 per l’unità, oppure esportatelo nella stessa shell che avvia dsh. Verificate quali valori sono effettivamente disponibili nel processo in esecuzione con sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

Quale versione di Node.js richiede dsh?

Node.js 24.9 o versioni successive, secondo il package.json del repository alla data del 5 novembre 2026. La serie 22 non è più supportata e anche Node 24.0-24.8 è insufficiente. Eseguite node -v prima di qualsiasi altra operazione, perché un avvio non riuscito causato da un runtime non supportato può sembrare un’installazione danneggiata e indurre a reinstallare il pacchetto invece del runtime.

Questo articolo ti è stato utile?