SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Plugin dsh: come funzionano e come valutarli

Un plugin dsh esegue codice di terzi con i permessi dell’agent. Scopri cosa può raggiungere, quando diventa attivo e come controllarlo prima dell’installazione.

Che cos’è un plugin dsh e cosa può fare?

I plugin dsh sono pacchetti Node che DeepSeek Harness carica nel proprio processo. Dopo il caricamento, un plugin esegue codice di terzi con i permessi del tuo agent, sulla macchina che l’agent può già raggiungere. La procedura di installazione è più protetta. pnpm blocca gli script di build delle dipendenze finché non li approvi e la documentazione CLI indica di «riavviare il profilo dopo aver aggiunto, rimosso o aggiornato un Bundle», quindi un plugin aggiunto con dsh plugin viene caricato al riavvio successivo. Un plugin installato dalla pagina web Plugins può invece diventare attivo immediatamente. Tra un plugin caricato e il resto dell’harness non esiste alcuna barriera. Prima di installarne uno, devi quindi chiederti quali risorse può modificare e come limitarne l’accesso.

dsh (DeepSeek Harness) è l’harness open source per agent di DeepSeek AI, basato su un framework per plugin chiamato Cordis. Il termine centrale è importante, perché un harness per agent è il programma che avvolge il modello e gestisce il ciclo di esecuzione, gli strumenti e i permessi; un plugin si integra esattamente a questo livello. Il README del progetto afferma che tutto è un plugin. L’adattatore per il modello è un plugin. Anche l’interfaccia web in cui digiti è un plugin. Qualsiasi componente installato dall’esterno del progetto entra nello stesso albero e allo stesso livello di attendibilità dei componenti distribuiti con il progetto. Se non hai ancora configurato un’istanza, inizia da DeepSeek Harness su un VPS e torna qui prima di aggiungervi qualsiasi componente.

Nell’agosto 2026 il repository AGENTS.md elencava i punti di estensione raggiungibili da un plugin, che comprendevano:

  • LLM (modello linguistico di grandi dimensioni): il provider pagato con la tua chiave API
  • Shell: la funzionalità bash, con provider local e pwsh
  • Filesystem: accesso ai file controllato dai criteri
  • Web: provider per la ricerca e il recupero dei contenuti
  • Subprocess: un provider per l’albero dei processi
  • Workflow: thread worker
  • Subagent: delega ad altri agent
  • Settings and credentials: la configurazione salvata e le variabili d’ambiente

Da allora quell’elenco non compare più in AGENTS.md. Al 17 novembre 2026 il docs/architecture.md del progetto indica invece i punti di estensione per nome e aggiunge backend sandbox, terminali persistenti, job in background, comandi impartiti dall’utente e sessioni attivate da webhook ai punti di integrazione per model, tool, shell, filesystem e subagent.

Un plugin registra inoltre strumenti in ctx.tools e la documentazione specifica che lo schema di uno strumento registrato entra nella composizione del prompt. È questa la parte che spesso viene trascurata. Un plugin può modificare le decisioni dell’agent senza che il proprio codice esegua attività insolite, perché la descrizione che aggiunge diventa testo letto dal modello. Il problema ha la stessa struttura di un prompt injection contro gli agent per il coding, con una differenza: questo testo arriva quando installi il plugin e rimane finché non lo rimuovi.

Come trova e carica i plugin dsh?

Non esiste una directory globale dei plugin. Un'istanza dsh in esecuzione è un albero di plugin composto all'avvio da livelli ordinati; il profilo contiene le scelte dell'utente. $DSH_HOME corrisponde per impostazione predefinita a ~/.dsh e ogni profilo si trova in $DSH_HOME/profiles/<name>. I profili web e headless vengono creati al primo utilizzo a partire dai template forniti.

Una directory di profilo contiene due file che determinano l'intera configurazione:

  • package.json, con le dipendenze dei plugin esterni all'albero e un manifest dsh.profile contenente l'elenco ordinato bundles
  • cordis.patch.yml, il proprio livello di patch applicato a quei bundle
ls ~/.dsh
ls ~/.dsh/profiles/web

All'avvio, i livelli vengono applicati nell'ordine seguente; i livelli successivi hanno la precedenza:

  1. una radice vuota
  2. i bundle del profilo, nell'ordine indicato dal manifest
  3. cordis.patch.yml del profilo
  4. $DSH_HOME/cordis.patch.yml
  5. eventuali overlay --patch <path> passati sulla riga di comando

Due flag mostrano il risultato di questa composizione senza avviare nulla:

dsh --profile web --dump-default-config
dsh --profile web --dump-config

--dump-default-config stampa soltanto i livelli dei bundle. --dump-config aggiunge i livelli di patch del profilo e della home directory, oltre agli overlay --patch; è quindi la rappresentazione più fedele dell'insieme di elementi che verranno caricati al prossimo avvio. Leggerlo prima di usare un sistema ereditato evita di affidarsi a una configurazione non verificata.

È necessario prestare attenzione ai file di patch. In questo caso la configurazione non è costituita soltanto da dati passivi, perché il formato consente valori contrassegnati !!js all'interno del blocco config di un plugin. Un frammento cordis.patch.yml copiato da un post del forum è codice. Va quindi trattato come uno script shell proveniente dalla stessa fonte.

Che cosa esegue effettivamente dsh plugin add?

dsh plugin --profile <name> <args> inoltra i relativi argomenti a pnpm nella directory del profilo. Per questo motivo, pnpm deve essere disponibile in PATH. I verbi sono quelli di pnpm:

dsh plugin --profile web add '<package-or-git-spec>'
dsh plugin --profile web remove '<package-name>'
dsh plugin --profile web why '<package-name>'
dsh plugin --profile web update

Il modello di sicurezza per l'installazione di un plugin dsh è quindi quello previsto per l'installazione di qualsiasi dipendenza in stile npm, con un passaggio aggiuntivo: il risultato viene caricato nell'agent. Il pacchetto include il proprio albero delle dipendenze e ogni pacchetto dell'albero finisce nello stesso processo. Tutto ciò che vale per il modo in cui gli attacchi alla supply chain di npm raggiungono un server vale anche in questo caso, senza modifiche.

A partire da pnpm 10, gli script di build delle dipendenze non vengono eseguiti per impostazione predefinita. L'approvazione viene concessa per pacchetto tramite pnpm approve-builds o tramite l'impostazione allowBuilds. pnpm 11 ha sostituito la precedente impostazione onlyBuiltDependencies con allowBuilds. Di conseguenza, una guida o una configurazione precedente che usa ancora onlyBuiltDependencies non approva nulla nelle versioni correnti di pnpm. Verifica quale versione di pnpm è installata:

pnpm --version

I plugin ospitati su Git sono il primo caso in cui si incontra questo comportamento. La documentazione CLI indica che un plugin Git che distribuisce il codice sorgente esegue la build durante l'installazione tramite lo script prepare. Per questo motivo, il primo add non riesce e pnpm mostra il suggerimento allowBuilds. Copia la chiave visualizzata in pnpm-workspace.yaml nel profilo e ripeti il comando. L'approvazione di quella chiave consente alla build del repository di essere eseguita con i permessi dell'utente. I tarball già compilati e i checkout locali non richiedono alcuna autorizzazione.

Questa impostazione predefinita è utile, ma nell'ecosistema è anche la funzionalità di sicurezza più spesso interpretata in modo eccessivo. Il blocco degli script di build impedisce l'esecuzione del codice durante l'installazione. Non protegge dal plugin stesso, perché lo scopo di un plugin è proprio consentire all'harness di importarlo e chiamarlo quando il profilo viene riavviato oppure, se hai usato la pagina web Plugins, non appena l'installazione viene applicata. Un plugin non ha bisogno di un hook postinstall. È stato autorizzato esplicitamente.

Cosa leggere prima di installare un plugin dsh

Scarica il tarball pubblicato e leggilo. Quando decomprimi un archivio non viene eseguito nulla.

npm pack '<package-name>@<version>'
tar -tzf '<package-name>-<version>.tgz'
tar -xzf '<package-name>-<version>.tgz'
less package/package.json

I quattro campi in package.json forniscono quasi tutte le informazioni necessarie. Leggi scripts per individuare le voci preinstall, install e postinstall. Leggi dependencies per i nomi che non riconosci o che differiscono di un carattere da nomi noti. Leggi bin per verificare cosa il pacchetto vuole trovare nel tuo PATH. Leggi main o exports per individuare il file di ingresso, quindi apri quel file e segui il flusso di esecuzione.

Poi leggi il codice che verrà effettivamente caricato. Un plugin che dichiara di fornire uno strumento per le notifiche non ha motivo di leggere ~/.ssh, contattare un host che non hai mai sentito nominare o avviare una shell. Se il pacchetto contiene soltanto JavaScript incluso o minificato e non esiste il relativo codice sorgente in un repository pubblico, hai già la risposta. Preferisci i plugin con codice sorgente leggibile e, possibilmente, di dimensioni ridotte.

Puoi anche interrogare il registry senza installare nulla:

pnpm view '<package-name>' dependencies
pnpm view '<package-name>' versions

Un pacchetto pubblicato la settimana scorsa, con una sola versione, senza un campo repository e con un nome che imita qualcosa di popolare è il trucco più vecchio di qualunque registry. Verificare i download con gli checksum è la pratica complementare: devi sapere esattamente cosa hai scaricato prima di consentirne l'esecuzione.

Blocca la versione e conserva il lockfile

Un intervallo di versioni fluttuante consente al codice eseguito nel processo dell'agent di cambiare a ogni installazione o aggiornamento, senza una decisione esplicita. Blocca la versione.

dsh plugin --profile web add --save-exact '<package-name>@<version>'

La posizione dei flag varia tra le versioni di pnpm. Controlla quindi il risultato invece di affidarti al comando. Apri poi il package.json del profilo e verifica che la dipendenza sia indicata con una versione semplice, senza ^ o ~ davanti. Quel file determina cosa viene installato.

Conserva quindi il lockfile, che blocca l'intero albero delle dipendenze transitive e non soltanto il nome di primo livello:

find ~/.dsh -maxdepth 3 -name 'pnpm-lock.yaml'

Copialo in una posizione inclusa nei backup, insieme al package.json del profilo. Questi due file ricostruiscono lo stesso albero su un nuovo server. Esegui dsh plugin --profile web update solo quando hai deciso di cambiare versione, mai per una pulizia ordinaria, quindi leggi il diff del lockfile.

Per un plugin installato da git anziché da un registry, blocca il commit invece del branch. Una specifica nella forma github:owner/repo#<full commit sha> identifica un albero fisso. Un nome di branch indica invece il contenuto disponibile in quel branch alla successiva risoluzione di pnpm. In questo modo deleghi ad altri una decisione che dovrebbe restare sotto il tuo controllo. Lo stesso vale per l'harness: la release npm latest è una release candidate e un'installazione senza versione bloccata può risolvere una release diversa in qualsiasi momento. Da qui derivano la maggior parte degli errori di installazione e versione di dsh.

Mercato dei plugin e valore della selezione

dsh dispone di un marketplace, installato come plugin. Questo fornisce un'indicazione sull'architettura:

dsh plugin --profile web add dshmarket

Dopo un riavvio, in dsh 0.2.1 e versioni successive viene visualizzato come scheda nella pagina Plugins, accanto a Installed. Negli host meno recenti è disponibile in Settings, quindi Plugin Market. Il relativo README descrive chiaramente i limiti. Le installazioni sono limitate alle origini elencate in un registro selezionato. Tutto il resto viene rifiutato. Gli script di build sono bloccati per impostazione predefinita. Per abilitarne uno è necessaria un'approvazione specifica per ogni pacchetto. I plugin terminali vengono segnalati prima di essere inseriti in un profilo web. La frase più importante specifica che la presenza nel registro non costituisce un'approvazione, perché i plugin sono codice di terze parti. Lo stesso README indica che la maggior parte dei plugin installati tramite questo sistema diventa attiva dopo il semplice aggiornamento della pagina, senza riavvio. Di conseguenza, un'installazione con un clic può essere eseguita all'interno dell'agent pochi secondi dopo.

Un elenco selezionato stabilisce un livello minimo di qualità. Non analizza il codice al posto dell'utente e non può indicare cosa farà la versione successiva di un plugin dopo il trasferimento dell'account del maintainer. Considera un'installazione con un clic come considereresti curl | bash dello stesso autore. Vale la pena ripetere un'altra riga di quel README: un backup esportato può contenere credenziali provenienti dalla configurazione del profilo. Non allegarlo quindi a una issue pubblica né caricarlo su un sito di paste. Se ti serve un elenco iniziale anziché un metodo, plugin dsh che vale la pena installare è l'articolo complementare a questo.

Anche l'harness dispone ora di un percorso dedicato. Un plugin sperimentale Custom plugin indexes bundle, attivabile dalla pagina Plugins, aggiunge una scheda Discover alimentata dai file di indice che aggiungi manualmente. dsh non include alcuna origine di indice. La documentazione specifica che gli indici sono contenuti di terze parti e che dsh verifica il formato del file, ma non ciò che un indice dichiara sul titolo, sull'autore o sull'origine di un plugin.

Esegui dsh con un utente dedicato, non come root

La verifica riduce la frequenza con cui entra qualcosa di dannoso. Il principio del privilegio minimo stabilisce cosa può raggiungere quando accade. Su un VPS, configurare questa seconda protezione richiede poco.

Assegna all'harness un account Unix dedicato con una home propria e non eseguirlo mai come root:

sudo adduser --disabled-password --gecos "" dshrun
sudo -iu dshrun

All'interno di quella sessione, avvia l'harness in modo che utilizzi come home la directory dell'account:

npx @deepseek-ai/dsh web

Per impostazione predefinita, l'interfaccia web è disponibile su http://127.0.0.1:3080. Lasciala in ascolto su quell'indirizzo. Se hai mai fatto clic da un altro computer sul link visualizzato e non hai ricevuto risposta, questo spiega cosa significa quell'indirizzo stampato da dsh. La composizione web fornita controlla gli header Host e Origin e richiede un browser autenticato o un Peer API autenticato per ogni metodo RPC Host e ogni flusso WebSocket; inoltre, dsh web rifiuta --host 0.0.0.0. I client API eseguono l'autenticazione tramite /connect e ricevono un cookie API firmato. Considera questo accesso come una seconda barriera, non come un motivo per pubblicare la porta 3080. Dietro l'interfaccia c'è un agent con accesso a una shell. Di conseguenza, un token di sessione esposto o un errore di autenticazione su una porta pubblica può consegnare a un estraneo una shell remota senza privilegi root, con un'interfaccia intuitiva. Raggiungilo dal laptop tramite un tunnel SSH:

ssh -L 3080:127.0.0.1:3080 you@your-vps

Poi verifica che nessun processo sia in ascolto su un indirizzo pubblico:

ss -lnt | grep 3080

L'indirizzo locale dovrebbe essere 127.0.0.1:3080. Se è 0.0.0.0:3080, qualcosa diverso dai valori predefiniti della dsh web fornita lo ha impostato in quel modo, ad esempio una composizione diversa o una modifica della configurazione; quella composizione gestisce la propria autenticazione. La documentazione del progetto dichiara che il web server sottostante non fornisce autonomamente autenticazione né una policy Origin. Finché non sai cosa protegge quella porta, considera il firewall l'unica barriera tra un estraneo e il tuo agent e riportala sull'interfaccia loopback. Il ragionamento alla base di eseguire Claude Code in sicurezza su un VPS si applica senza modifiche anche a dsh. Assegna all'agent una sola directory di lavoro che possa danneggiare e conserva fuori da quella macchina tutto ciò che non puoi ricreare. Ancora meglio, tratta il sistema come una VM usa e getta per gli agent di codifica, perché ricostruire un VPS richiede un'ora, mentre esaminarne uno richiede una settimana.

Dove risiedono le chiavi e perché i permessi dei file non bastano

dsh conserva le chiavi API in $DSH_HOME/.credentials.yaml e i valori dell'ambiente in $DSH_HOME/.env, mentre le impostazioni del modello si trovano in cordis.patch.yml del profilo attivo. Quando questa guida è stata verificata per la prima volta, nell'ottobre 2026, $DSH_HOME/settings.yaml di una versione precedente è stato importato una volta e rinominato settings.yaml.imported. Quale chiave debba essere inserita in ciascuno di questi file e quali dati escano effettivamente dal sistema in ogni modalità è spiegato in configurare le chiavi API, i modelli e gli endpoint di dsh. È opportuno chiarire questo aspetto prima di aggiungere un plugin, perché ogni chiave configurata è un'ulteriore informazione che un plugin può leggere. Proteggi almeno questi due file sensibili:

chmod 600 ~/.dsh/.credentials.yaml ~/.dsh/.env
ls -l ~/.dsh

La modalità 600 concede al proprietario i permessi di lettura e scrittura e non concede alcun permesso agli altri utenti. È utile conoscere questa impostazione in entrambe le notazioni (modalità numeriche e simboliche di chmod). Occorre però essere chiari sui suoi limiti. I permessi dei file proteggono questi file dagli altri account presenti sul sistema. Non proteggono da un plugin, perché il plugin viene eseguito dall'utente proprietario dei file, all'interno del processo che li legge. Per questo tenere i secret fuori dalla portata di un agente AI significa non conservarli affatto sul computer. Un sistema che esegue dsh dovrebbe contenere soltanto la chiave del modello necessaria. Le credenziali cloud e le chiavi di firma devono essere conservate altrove.

Perché un plugin che legge il Web modifica il modello delle minacce

Il livello Web fornisce ai plugin provider per la ricerca e il recupero dei contenuti. Un plugin che importa una pagina nella sessione importa testo che un attaccante può modificare. Il prompt del modello non separa le istruzioni dai dati. Una pagina recuperata può quindi contenere una riga indirizzata al tuo agente, e un harness che dispone della capacità di usare la shell deve solo eseguire un passaggio obbediente per avviarla.

Il controllo è già disponibile nell'harness. dsh-base, il bundle iniziale condiviso dei profili web, headless, sdk e acp, include la sandbox e la policy di approvazione (il profilo sdk-minimal ne è deliberatamente privo). Usalo. Una sessione che può recuperare pagine non attendibili deve richiedere un'approvazione per qualsiasi operazione di scrittura o esecuzione, in modo che un'istruzione recuperata non possa trasformarsi autonomamente in un'azione. Vincolare le azioni dell'agente alle approvazioni spiega come stabilire il punto in cui collocare questo limite. La relazione funziona anche nella direzione opposta: il tuo server è una pagina che l'agente di qualcun altro recupererà. Questo è il motivo per cui è importante bloccare i crawler AI sul tuo server.

Come verificare cosa ha modificato un plugin?

Eseguire uno snapshot prima dell’installazione, installare il plugin, eseguire uno snapshot dopo l’installazione, quindi leggere le differenze.

dsh --profile web --dump-config > /tmp/dsh-before.txt
dsh plugin --profile web add '<package-name>@<version>'
dsh --profile web --dump-config > /tmp/dsh-after.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after.txt

Il diff mostra quali voci del plugin l’installazione ha aggiunto all’albero composto. Solo un pacchetto che dichiara una patch per il bundle entra nell’albero; una dipendenza semplice non aggiunge nulla e dsh segnala il caso una volta. Se un plugin installato per una piccola funzionalità aggiunge diverse voci che non riesci a giustificare, interrompi la procedura e leggi il codice sorgente prima di avviarlo. dsh plugin --profile web why <package-name> risponde all’altra domanda: quali dipendenze dirette hanno introdotto un determinato pacchetto.

I pacchetti installati vengono inseriti nel node_modules del profilo, in $DSH_HOME/profiles/<name>/node_modules, quindi puoi esaminare l’albero anche sul disco:

ls ~/.dsh/profiles/web/node_modules

Mantieni un secondo profilo in cui non esegui mai esperimenti. Se un’installazione rompe l’harness, l’avvio di dsh --profile <clean-name> indica in pochi secondi se la causa è il plugin.

Come rimuovo un plugin dsh?

dsh plugin --profile web remove '<package-name>'
dsh --profile web --dump-config > /tmp/dsh-after-removal.txt
diff -u /tmp/dsh-before.txt /tmp/dsh-after-removal.txt

La rimozione della dipendenza non elimina sempre la configurazione. Le voci scritte nel file cordis.patch.yml del profilo restano al loro posto, perché quel file è di tua proprietà e l'harness non lo riscrive automaticamente. Apri il file ed elimina ogni blocco che indica il pacchetto rimosso.

less ~/.dsh/profiles/web/cordis.patch.yml

Poi devi gestire l'aspetto che nessun comando di disinstallazione può correggere. Se hai rimosso un plugin perché non ti fidavi più di esso, tutto ciò che poteva leggere è già stato letto. Ruota la chiave API di DeepSeek nella console del provider e ruota anche qualsiasi altro secret presente in $DSH_HOME. Verifica quindi a quali risorse del resto della rete poteva accedere l'account Unix con cui il plugin veniva eseguito.

La versione breve

  • Leggere il tarball pubblicato prima dell'installazione, iniziando da scripts e dal file di ingresso
  • Fissare la versione esatta oppure il commit esatto per una specifica git e conservare il lockfile
  • Installare in un unico profilo e mantenere un profilo pulito, che sia possibile avviare quando qualcosa si rompe
  • Confrontare --dump-config prima e dopo ogni installazione
  • Eseguire l'harness con un utente Unix dedicato, sull'interfaccia di loopback, e raggiungerlo tramite SSH
  • Conservare una sola chiave API sul server e ruotarla il giorno in cui si rimuove un plugin di cui non ci si fida più

Niente di tutto questo è un motivo per evitare i plugin. Il modello a plugin è il motivo per cui dsh è utile, e un harness che non è possibile estendere è un harness che prima o poi dovrete sostituire. È un motivo per sapere che cosa è stato installato, da chi e in quale versione, e per eseguire l'intero sistema in un ambiente che sia possibile ricostruire.

FAQ

I plugin vengono isolati tra loro da dsh?

No. Un plugin viene caricato nel processo harness tramite Cordis e può raggiungere le interfacce documentate per le funzionalità, tra cui shell, filesystem, web, subprocess, subagent e credentials. dsh-base, il bundle iniziale condiviso dei profili web, headless, sdk e acp, distribuisce la sandbox e la policy di approvazione che stabiliscono cosa possono fare gli strumenti dell'agente; la protezione dipende da questa policy. Non esiste un confine di autorizzazione specifico per ogni plugin. Il modello corretto è quindi considerare l'installazione di un plugin come un'estensione della fiducia all'autore e a ogni pacchetto incluso nella relativa struttura delle dipendenze.

Posso installare un plugin dsh senza eseguire i relativi script di installazione?

pnpm 10 e versioni successive bloccano per impostazione predefinita gli script di build delle dipendenze e dsh plugin ... add inoltra le richieste a pnpm. Con una versione aggiornata di pnpm, quindi, l'installazione non esegue gli script dei pacchetti finché non autorizzi il pacchetto interessato. Verifica la versione con pnpm --version. Questo non rende sicuro un plugin non verificato. Il codice del plugin viene eseguito quando l'harness lo carica, al riavvio successivo del profilo dopo un'installazione con dsh plugin oppure, spesso, subito dopo un'installazione dalla pagina Plugins web. Nessuna restrizione applicata durante l'installazione modifica questo comportamento.

Dove si trovano realmente i plugin dsh e la relativa configurazione?

Per impostazione predefinita, $DSH_HOME punta a ~/.dsh. I profili si trovano in $DSH_HOME/profiles/<name>. Ognuno contiene un package.json con le dipendenze dei plugin, il manifest dsh.profile dei bundle ordinati e un livello di patch cordis.patch.yml. I pacchetti installati vengono salvati nel node_modules specifico di ogni profilo, in $DSH_HOME/profiles/<name>/node_modules. Le chiavi si trovano in $DSH_HOME/.credentials.yaml, i valori dell'ambiente in $DSH_HOME/.env e un $DSH_HOME/cordis.patch.yml a livello della home directory viene applicato a tutti i profili. Esegui dsh --profile web --dump-config per visualizzare il risultato composto senza avviare il profilo.

È sicuro installare plugin dal market di dsh?

Il market limita le installazioni alle sorgenti presenti in un registry verificato e blocca gli script di build finché non li autorizzi per ogni pacchetto. Questo rappresenta un miglioramento concreto rispetto all'inserimento del nome di un pacchetto copiato da una chat. Il README del market specifica comunque che la pubblicazione non costituisce un'approvazione, perché i plugin sono codice di terze parti sviluppato da altri autori. Leggi il codice sorgente e blocca la versione. Esegui l'harness con un account utente e, idealmente, su una macchina che puoi permetterti di perdere.

Questo articolo ti è stato utile?