Plugins de dsh: cómo funcionan y cómo revisarlos
Un plugin de dsh ejecuta código ajeno dentro de su agente, con sus permisos. Aprenda qué puede alcanzar y cómo revisarlo antes de instalarlo.
¿Qué es un plugin de dsh y qué puede hacer?
Los plugins de dsh son paquetes de Node que DeepSeek Harness carga en su propio proceso. Una vez cargado, un plugin ejecuta código de terceros con los permisos de su agente y en las máquinas a las que el agente ya puede acceder. El proceso de instalación está más protegido. pnpm mantiene bloqueados los scripts de compilación de las dependencias hasta que usted los aprueba, y la referencia de la CLI indica que debe «reiniciar ese Profile después de añadir, quitar o actualizar un Bundle», por lo que un plugin añadido con dsh plugin se carga en el siguiente reinicio. Uno instalado desde la página web Plugins puede aplicarse de inmediato. Nada se interpone entre un plugin cargado y el resto de harness. Por tanto, antes de instalar uno debe preguntarse a qué puede acceder ese código y cómo mantener ese acceso limitado.
dsh (DeepSeek Harness) es el harness de agentes de código abierto de DeepSeek AI, basado en un framework de plugins llamado Cordis. Esa parte intermedia es importante, porque un harness de agentes es el programa que envuelve al modelo y controla el ciclo de ejecución, las herramientas y los permisos. Un plugin se integra exactamente en ese nivel. El propio README del proyecto indica que todo es un plugin. El adaptador del modelo es un plugin. La interfaz web en la que usted escribe es un plugin. Todo lo que instala desde fuera del proyecto entra en el mismo árbol y con el mismo nivel de confianza que las partes incluidas originalmente. Si todavía no ha puesto uno en marcha, empiece por DeepSeek Harness en un VPS y vuelva aquí antes de añadirle nada.
En agosto de 2026, el AGENTS.md del repositorio enumeraba los puntos de extensión a los que puede acceder un plugin. Incluían:
- LLM (modelo de lenguaje grande): el proveedor que paga con su clave de API
- Shell: la capacidad de bash, con proveedores local y pwsh
- Filesystem: acceso a archivos controlado por políticas
- Web: proveedores de búsqueda y descarga
- Subprocess: un proveedor de árboles de procesos
- Workflow: hilos de trabajo
- Subagent: delegación a otros agentes
- Settings and credentials: su configuración guardada y las variables de entorno
Desde entonces, esa lista ha desaparecido de AGENTS.md. A fecha de 17 de noviembre de 2026, el docs/architecture.md del proyecto enumera en su lugar los puntos de extensión. Además, añade backends de sandbox, terminales persistentes, trabajos en segundo plano, comandos humanos y sesiones activadas por webhook a los puntos de integración de modelo, herramientas, shell, filesystem y subagent.
Un plugin también registra herramientas en ctx.tools, y la documentación indica de forma explícita que el esquema de una herramienta registrada se incorpora al ensamblado del prompt. Esta segunda parte suele pasarse por alto. Un plugin puede cambiar lo que su agente decide hacer sin que su propio código haga nada inusual, porque la descripción que aporta se convierte en texto que el modelo lee. Es el mismo tipo de problema que la inyección de prompts contra agentes de programación, con una diferencia: este texto llega cuando instala el plugin y permanece hasta que lo elimina.
¿Cómo busca y carga plugins dsh?
No existe un directorio global de plugins. Un dsh en ejecución es un árbol de plugins que se compone durante el arranque a partir de capas ordenadas, y el elemento que contiene sus selecciones es un perfil. $DSH_HOME apunta de forma predeterminada a ~/.dsh, y cada perfil se encuentra en $DSH_HOME/profiles/<name>. Los perfiles web y headless se crean automáticamente en el primer uso a partir de las plantillas incluidas.
Un directorio de perfil contiene dos archivos que determinan todo:
package.json, con las dependencias de plugins externos y un manifiestodsh.profileque contiene la lista ordenada debundlescordis.patch.yml, su propia capa de cambios sobre esos paquetes
ls ~/.dsh
ls ~/.dsh/profiles/webEl arranque aplica las capas en este orden; las capas posteriores tienen prioridad:
- una raíz vacía
- los paquetes del perfil, en el orden indicado por el manifiesto
cordis.patch.ymldel perfil$DSH_HOME/cordis.patch.yml- cualquier superposición
--patch <path>pasada en la línea de comandos
Dos opciones muestran el resultado de esta composición sin iniciar nada:
dsh --profile web --dump-default-config
dsh --profile web --dump-config--dump-default-config muestra sólo las capas de paquetes. --dump-config añade las capas de parches del perfil y del directorio personal, además de cualquier superposición --patch. Por tanto, es lo más parecido a un inventario fiable de lo que cargará el próximo arranque. Léalo antes de confiar en una máquina que ha heredado.
Una advertencia sobre esos archivos de parches. La configuración no son datos inertes en este caso, porque el formato permite valores etiquetados !!js dentro del bloque config de un plugin. Un fragmento cordis.patch.yml copiado de una publicación de un foro es código. Trátelo como trataría un script de shell procedente de la misma fuente.
¿Qué ejecuta realmente dsh plugin add?
dsh plugin --profile <name> <args> reenvía sus argumentos a pnpm dentro del directorio de ese perfil, por lo que pnpm debe estar en PATH. Los verbos son los de 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 updateEl modelo de seguridad de instalar un complemento de dsh es, por tanto, el mismo que el de instalar cualquier dependencia de estilo npm, más un paso adicional en el que el resultado se carga en el agente. El paquete incluye su propio árbol de dependencias, y todos los paquetes de ese árbol terminan en el mismo proceso. Todo lo descrito en cómo los ataques a la cadena de suministro de npm llegan a un servidor se aplica aquí sin modificaciones.
pnpm 10 y versiones posteriores no ejecutan de forma predeterminada los scripts de compilación de una dependencia. La aprobación se realiza por paquete mediante pnpm approve-builds o mediante el ajuste allowBuilds. pnpm 11 sustituyó el ajuste anterior onlyBuiltDependencies por allowBuilds, por lo que una guía o una configuración antigua que todavía use onlyBuiltDependencies no aprueba nada en una versión actual de pnpm. Compruebe qué versión de pnpm tiene:
pnpm --versionLos complementos alojados en Git son el primer caso en el que se encuentra con esto. La referencia de la CLI indica que un complemento de Git que distribuye código fuente se compila durante la instalación mediante su script prepare. Por eso el primer add falla con la indicación allowBuilds de pnpm: debe copiar la clave mostrada en pnpm-workspace.yaml del perfil y volver a ejecutar el comando. Aprobar esa clave permite que la compilación del repositorio se ejecute con los permisos de su usuario. Los tarballs ya compilados y las copias de trabajo locales no necesitan autorización.
Ese valor predeterminado es útil, pero también es la función de seguridad que más se sobreinterpreta en este ecosistema. Los scripts de compilación bloqueados impiden que se ejecute código durante la instalación. No hacen nada respecto al complemento en sí, porque la finalidad de un complemento es que el entorno de ejecución lo importe y lo llame cuando se reinicie el perfil, o en cuanto se aplique la instalación si utilizó la página web Plugins. Un complemento no necesita un hook postinstall. Se le ha dado acceso explícitamente.
Qué leer antes de instalar un plugin de dsh
Descargue el tarball publicado y léalo. No se ejecuta nada al desempaquetar un archivo.
npm pack '<package-name>@<version>'
tar -tzf '<package-name>-<version>.tgz'
tar -xzf '<package-name>-<version>.tgz'
less package/package.jsonCuatro campos de ese package.json le proporcionan casi toda la información que necesita. Lea scripts para consultar las entradas preinstall, install y postinstall. Lea dependencies para revisar nombres que no reconozca o nombres que se diferencien en un solo carácter de otros conocidos. Lea bin para comprobar qué elementos quiere el paquete en su PATH. Lea main o exports para localizar el archivo de entrada. Después, abra ese archivo y sígalo.
A continuación, lea el código que se cargará realmente. Un plugin que anuncia una herramienta de notificaciones no tiene ningún motivo para leer ~/.ssh, conectarse a un host que no conoce o iniciar un shell. Si el paquete sólo incluye JavaScript agrupado o minimizado y no existe el código fuente correspondiente en un repositorio público, esa es la respuesta. Prefiera plugins cuyo código fuente pueda leer y dé prioridad a los que sean pequeños.
También puede consultar el registro sin instalar nada:
pnpm view '<package-name>' dependencies
pnpm view '<package-name>' versionsUn paquete publicado la semana pasada, con una sola versión, sin campo de repositorio y con un nombre que suplanta a algo popular es el truco más antiguo de cualquier registro. Verificar las descargas con sumas de comprobación es la práctica complementaria: sepa exactamente qué ha descargado antes de permitir que se ejecute.
Fije la versión y conserve el archivo de bloqueo
Un rango de versiones flotante significa que el código dentro del proceso de su agente puede cambiar durante cualquier instalación o actualización sin que usted lo decida. Fíjelo.
dsh plugin --profile web add --save-exact '<package-name>@<version>'La posición de las opciones varía entre versiones de pnpm, así que compruebe el resultado en lugar de confiar en el comando. Abra después el package.json del perfil y confirme que la dependencia aparece como una versión simple, sin ^ ni ~ delante. Ese archivo determina qué se instala.
A continuación, conserve el archivo de bloqueo, que fija todo el árbol transitivo y no sólo el nombre de nivel superior:
find ~/.dsh -maxdepth 3 -name 'pnpm-lock.yaml'Cópielo en una ubicación incluida en sus copias de seguridad, junto con el package.json del perfil. Esos dos archivos reconstruyen el mismo árbol en un servidor nuevo. Ejecute dsh plugin --profile web update cuando haya decidido cambiar de versión, nunca como limpieza rutinaria, y revise después las diferencias del archivo de bloqueo.
Para un plugin instalado desde git en lugar de un registro, fije el commit en vez de la rama. Una especificación con el formato github:owner/repo#<full commit sha> proporciona un árbol fijo. Un nombre de rama proporciona lo que esa rama contenga la próxima vez que pnpm lo resuelva. Es una decisión que ha delegado en otra persona. El propio entorno de ejecución exige la misma disciplina, porque la versión de npm latest es una versión candidata y una instalación sin versión fijada puede resolver una diferente cualquier día. De ahí proceden la mayoría de los errores de instalación y versión de dsh.
El mercado de plugins y el valor de que estén «seleccionados»
dsh tiene un mercado que se instala como plugin. Esto aporta información sobre su arquitectura:
dsh plugin --profile web add dshmarketDespués de reiniciar, aparece como una pestaña en la página Plugins, junto a Installed, en dsh 0.2.1 y versiones posteriores. En hosts antiguos, se accede desde Settings y después Plugin Market. Su README deja claros los límites. Las instalaciones están restringidas a las fuentes incluidas en un registro seleccionado, y cualquier otra fuente se rechaza. Los scripts de compilación están bloqueados de forma predeterminada, y habilitar uno requiere aprobación por paquete. Los plugins de terminal se marcan antes de incorporarse a un perfil web. La frase más importante indica que aparecer en el registro no constituye una recomendación, porque los plugins son código de terceros. El mismo README indica que la mayoría de los plugins instalados desde ahí se activan después de actualizar la página, sin reiniciar. Por tanto, una instalación con un clic puede estar ejecutándose dentro de su agente en cuestión de segundos.
Una lista seleccionada eleva el nivel mínimo de seguridad. No revisa el código por usted y no puede decirle qué hará la siguiente versión de un plugin si la cuenta de su mantenedor cambia de propietario. Trate una instalación con un clic como trataría curl | bash del mismo autor. Conviene repetir otra línea de ese README: una copia de seguridad exportada puede contener credenciales de su configuración de perfil. No la adjunte nunca a un issue público ni a un sitio de publicación de texto. Si quiere una lista inicial en lugar de un método, plugins de dsh que merece la pena instalar es el artículo complementario de este.
El harness también tiene ahora su propia ruta. Un plugin Custom experimental llamado Indexes, que se activa desde la página Plugins, añade una pestaña Discover alimentada por archivos de índice que usted incorpora manualmente. dsh no incluye ninguna fuente de índices. Su documentación indica que los índices son contenido de terceros y que dsh comprueba el formato del archivo, pero no verifica lo que un índice afirma sobre el título, el autor o la fuente de un plugin.
Ejecute dsh con su propio usuario, no como root
La evaluación reduce la frecuencia con la que entra algo malicioso. El principio de mínimo privilegio limita lo que puede alcanzar cuando entra. En un VPS, configurar esa segunda capa es sencillo.
Asigne a la herramienta una cuenta unix propia con su propio directorio de inicio y no la ejecute nunca como root:
sudo adduser --disabled-password --gecos "" dshrun
sudo -iu dshrunDentro de esa sesión, inicie la herramienta para que escriba su directorio de inicio con esa cuenta:
npx @deepseek-ai/dsh webLa interfaz web se publica en http://127.0.0.1:3080 de forma predeterminada. Déjela ahí. Si alguna vez hizo clic desde otra máquina en ese enlace impreso y no obtuvo respuesta, qué significa que dsh imprima esa dirección explica el motivo. La composición web incluida comprueba las cabeceras Host y Origin y requiere un navegador autenticado o un API Peer para cada método RPC de Host y cada flujo WebSocket, y dsh web rechaza --host 0.0.0.0. Los clientes de la API se autentican mediante /connect y reciben una cookie de API firmada. Considere ese inicio de sesión como un segundo control de acceso, no como un motivo para publicar 3080. Detrás hay un agente con acceso a un shell, por lo que un token de sesión filtrado o un fallo de inicio de sesión en un puerto público entrega a un desconocido un shell remoto sin privilegios de root mediante una interfaz sencilla. Acceda desde su portátil a través de un túnel SSH:
ssh -L 3080:127.0.0.1:3080 you@your-vpsDespués, confirme que no haya nada escuchando en una dirección pública:
ss -lnt | grep 3080La dirección local debería ser 127.0.0.1:3080. Si es 0.0.0.0:3080, algo distinto de los valores predeterminados incluidos en dsh web la estableció así, como una composición diferente o un cambio de configuración, y esa composición gestiona su propia autenticación. La documentación del proyecto indica que el servidor web subyacente no proporciona autenticación ni una política Origin propias. Por tanto, hasta saber qué protege ese puerto, suponga que el firewall es lo único que separa a un desconocido de su agente y vuelva a enlazarlo con loopback. El razonamiento de cómo ejecutar Claude Code de forma segura en un VPS se aplica a dsh sin cambios. Asigne al agente un único directorio de trabajo que pueda destruir y mantenga fuera de esa máquina todo lo que no pueda reconstruir. Mejor aún, trate el equipo como una VM desechable para agentes de programación, porque reconstruir un VPS cuesta una hora, mientras que auditarlo cuesta una semana.
Dónde se almacenan las claves y por qué los permisos de archivo tienen límites
dsh guarda las claves de API en $DSH_HOME/.credentials.yaml y los valores de entorno en $DSH_HOME/.env, mientras que la configuración del modelo se encuentra en cordis.patch.yml del perfil activo. Cuando esta guía se incorporó por primera vez en octubre de 2026, se importó una vez el $DSH_HOME/settings.yaml de una versión anterior y se le cambió el nombre a settings.yaml.imported. La clave que corresponde a cada uno de esos archivos y lo que realmente sale del equipo en cada modo se explica en configurar las claves de API, los modelos y los endpoints de dsh. Conviene resolverlo antes de añadir un plugin, porque cada clave que conecte es un elemento más que un plugin puede leer. Restrinja los permisos de los dos archivos sensibles:
chmod 600 ~/.dsh/.credentials.yaml ~/.dsh/.env
ls -l ~/.dshEl modo 600 permite al propietario leer y escribir, y no concede ningún permiso al resto. Es importante conocerlo en ambas notaciones (modos numéricos y simbólicos de chmod). Sea preciso sobre lo que ofrece. Los modos de archivo protegen esos archivos frente a otras cuentas del equipo. No protegen frente a un plugin, porque el plugin se ejecuta como el usuario propietario de los archivos, dentro del proceso que los lee. Por eso, mantener los secretos fuera del alcance de un agente de IA implica no almacenarlos en el equipo. Un equipo con dsh debería contener únicamente la clave del modelo que necesita. Las credenciales de su proveedor cloud y sus claves de firma deben estar en otro lugar.
Por qué un plugin que lee la web cambia el modelo de amenazas
La interfaz web proporciona a los plugins proveedores de búsqueda y obtención de datos. Un plugin que extrae una página hacia su sesión está extrayendo texto que un atacante puede escribir. Un prompt de modelo no separa las instrucciones de los datos, por lo que una página obtenida puede contener una línea dirigida a su agente, y un entorno que posea la capacidad de shell está a un paso obediente de ejecutarla.
El control ya existe en el entorno. dsh-base, el primer paquete compartido de los perfiles web, headless, sdk y acp, incluye el sandbox y la política de aprobación (el perfil sdk-minimal lo omite deliberadamente). Úselo. Una sesión que pueda obtener páginas no confiables debería requerir aprobación para cualquier operación que escriba o ejecute algo, de modo que una instrucción obtenida no pueda convertirse en una acción por sí misma. Limitar las acciones del agente mediante aprobaciones cubre cómo determinar dónde se establece ese límite. La relación también funciona en ambas direcciones, ya que su propio servidor es una página que el agente de alguien obtendrá, lo cual es el caso de bloquear rastreadores de IA en su servidor.
¿Cómo compruebo qué cambió un plugin?
Tome una instantánea antes de instalarlo, instálelo, tome otra instantánea y lea las diferencias.
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.txtLa diferencia muestra qué entradas del plugin añadió la instalación al árbol compuesto. Sólo un paquete que declare un parche de bundle se incorpora al árbol. Una dependencia normal no añade nada allí, y dsh muestra una advertencia al respecto una vez. Si un plugin instalado para una función pequeña añade varias entradas que no puede justificar, deténgase y lea el código fuente antes de iniciarlo. dsh plugin --profile web why <package-name> responde a la otra pregunta: qué dependencia directa suya incorporó un paquete determinado.
Los paquetes instalados se guardan en el node_modules propio del perfil, en $DSH_HOME/profiles/<name>/node_modules. Por tanto, también puede consultar el árbol en el disco:
ls ~/.dsh/profiles/web/node_modulesMantenga un segundo perfil en el que nunca haga pruebas. Si una instalación rompe el arnés, iniciar dsh --profile <clean-name> le permite saber en segundos si la causa fue el plugin.
¿Cómo elimino un complemento de 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.txtEliminar la dependencia no siempre elimina la configuración. Las entradas escritas en cordis.patch.yml del perfil permanecen porque ese archivo es suyo y el arnés no lo reescribe por usted. Ábralo y elimine cualquier bloque que indique el paquete que quitó.
less ~/.dsh/profiles/web/cordis.patch.ymlDespués, aborde la parte que ningún comando de desinstalación puede resolver. Si quitó un complemento porque dejó de confiar en él, todo lo que podía leer ya lo había leído. Rote la clave de API de DeepSeek en la consola del proveedor y rote cualquier otro dato que estuviera en $DSH_HOME. Después, determine a qué recursos del resto de la red podía acceder la cuenta de Unix con la que se ejecutaba.
La versión corta
- Lea el tarball publicado antes de instalarlo, empezando por
scriptsy el archivo de entrada - Fije la versión exacta o el commit exacto para una especificación de git, y conserve el archivo de bloqueo
- Instale en un solo perfil y conserve un perfil limpio que pueda iniciar cuando algo falle
- Compare
--dump-configantes y después de cada instalación - Ejecute el harness con su propio usuario de Unix, en loopback, y acceda a él mediante SSH
- Mantenga una sola clave de API en el equipo y rótela el día que elimine un plugin en el que ya no confíe
Nada de esto es motivo para evitar los plugins. El modelo de plugins es la razón por la que dsh resulta útil, y un harness que no pueda ampliar será reemplazado. Es motivo para saber qué instaló, de quién procede y qué versión usa, y para ejecutar todo en un entorno que pueda reconstruir.
FAQ
¿dsh aísla entre sí los plugins?
No. Cordis carga cada plugin en el proceso del harness, y este puede acceder a las interfaces de capacidad documentadas, incluidos shell, filesystem, web, subprocess, subagent y credentials. dsh-base, el primer bundle compartido de los perfiles web, headless, sdk y acp, incluye la política de sandbox y aprobación que controla lo que pueden hacer las herramientas del agente. Esa política es la que proporciona la protección. No existe un límite de permisos independiente para cada plugin. Por tanto, el modelo correcto es que instalar un plugin implica confiar en su autor y en todos los paquetes de su árbol de dependencias.
¿Puedo instalar un plugin de dsh sin ejecutar sus scripts de instalación?
pnpm 10 y versiones posteriores bloquean de forma predeterminada los scripts de compilación de las dependencias, y dsh plugin ... add delega en pnpm. Por tanto, con una versión actual de pnpm, la instalación no ejecuta scripts de paquetes a menos que apruebe ese paquete. Confirme la versión con pnpm --version. Esto no hace seguro un plugin no revisado. El código del propio plugin se ejecuta cuando el harness lo carga, durante el siguiente reinicio del perfil después de una instalación mediante dsh plugin, o a menudo inmediatamente después de instalarlo desde la página web Plugins. Ninguna restricción aplicada durante la instalación afecta a esa ejecución.
¿Dónde se encuentran realmente los plugins de dsh y su configuración?
$DSH_HOME usa ~/.dsh de forma predeterminada. Los perfiles se encuentran en $DSH_HOME/profiles/<name>. Cada uno contiene un package.json con sus dependencias de plugins, el manifiesto dsh.profile de bundles ordenados y una capa de parches cordis.patch.yml. Los paquetes instalados se guardan en el node_modules propio de cada perfil, en $DSH_HOME/profiles/<name>/node_modules. Las claves están en $DSH_HOME/.credentials.yaml, los valores de entorno en $DSH_HOME/.env y un $DSH_HOME/cordis.patch.yml del nivel de inicio se aplica a todos los perfiles. Ejecute dsh --profile web --dump-config para ver el resultado combinado sin iniciar el perfil.
¿Es seguro instalar plugins desde el mercado de plugins de dsh?
El mercado limita las instalaciones a fuentes de un registro seleccionado y bloquea los scripts de compilación hasta que los apruebe por paquete. Esto supone una mejora real frente a pegar el nombre de un paquete desde una ventana de chat. Su propio README sigue indicando que la inclusión en el registro no constituye una recomendación, porque los plugins son código de terceros escrito por otras personas. Lea el código fuente y fije la versión. Ejecute el harness con una cuenta de usuario y, si es posible, en una máquina que pueda permitirse perder.