Cómo instalar DeepSeek Harness (dsh): comando npx de una sola línea, compilación desde el código fuente, headless y plugins

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

Qué es Deep​Seek Harness — y qué no es

La fórmula interna de Deep​Seek, confirmada por el investigador sénior Chen Deli, es Modelo + Harness = Agente. El modelo es el cerebro; el harness es todo lo que lo convierte en algo que realiza trabajo: gestión de contexto y memoria, llamada de herramientas, planificación de tareas, lectura y escritura de archivos, ejecución de terminal, retroalimentación de errores y decidir cuándo una tarea está completa. Deep​Seek Harness es esa capa, publicada como código abierto bajo la licencia MIT el 13 de agosto de 2026 — el mismo día en que la compilación DeepSeek V4 Pro 0813 llegó a la API de Deep​Seek.

Dos hechos definen la experiencia de instalación. Primero, la arquitectura es «todo es un plugin», construida sobre Cordis, un contenedor de plugins TypeScript; así que lo que instalas es un núcleo pequeño más un conjunto de plugins que proporcionan adaptadores de modelo, herramientas, sesiones e interfaz de usuario. Segundo, la versión disponible hoy en npm es 0.1.0-rc.6, un candidato de lanzamiento que el propio proyecto señala como vista previa para desarrolladores: el README advierte, en mayúsculas, que se avecinan cambios que rompen la compatibilidad. La popularidad es real — 50,000 estrellas en GitHub en sus primeras 12 horas, 100,000 en unas 42 horas, y más de 120,000 para el 16 de agosto según la prensa tecnológica china — pero las estrellas miden interés, no estabilidad. Planifica tu instalación como planificarías una vista previa: rápida de probar, barata de desechar.

Antes de empezar: los requisitos reales del sistema

El único requisito indispensable es Node.js. El proyecto apunta al rango de motores ^22.19.0 || >=24.0.0 — en términos simples, Node 22.19 o superior, o cualquier Node 24.x. Verifica el tuyo con node --version. Si estás en una versión anterior de Node, la instalación con npx fallará o se comportará mal, no se degradará correctamente.

Todo lo demás es más ligero de lo que asume la multitud que prioriza el modelo:

• Una clave de API del modelo. dsh ejecuta un modelo real; necesita una clave para la API de DeepSeek o cualquier proveedor compatible con OpenAI que configures. Puedes añadir una en la interfaz web después del primer inicio.

• pnpm — solo para la compilación desde el código fuente. Instale una vez con npm install -g pnpm.

• ~1 GB de espacio libre en disco para el paquete npm, el espacio de trabajo y los registros de sesión, más lo que necesite un modelo local (dsh en sí no ejecuta los pesos).

• OS: la ruta npm funciona en Windows, macOS y Linux. El SDK de Python es más limitado (Linux x64/arm64, macOS 14+ arm64 — sin Windows nativo), se cubre a continuación.

Tú no necesitas una GPU. El arnés solo orquesta; el modelo se ejecuta de forma remota a través de una API.

Método 1 — el one-liner de npx (recomendado para casi todos)

La guía de inicio rápido oficial es un solo comando, y de verdad es un solo comando:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

El primer inicio tiene exactamente dos pasos de configuración:

• Añade una clave de modelo. Configuración → Modelos → introduce tu clave de API. Se guarda en $DSH_HOME/.credentials.yaml y no se muestra en texto plano después. En una instalación estándar DSH_HOME se establece por defecto en ~/.dsh.

• Elija un espacio de trabajo. Agregue el directorio del proyecto en el que dsh puede trabajar. La entrada permanece bloqueada hasta que se completen ambos pasos.

Luego envía una primera tarea: una buena prueba de humo es "Resume este repositorio e identifica sus paquetes principales." Si el resumen regresa y las llamadas a herramientas aparecen en el rastro de ejecución, tu instalación funciona.

Método 2 — compilar desde el código fuente

¿Prefieres ejecutar desde el repositorio? La ruta oficial es:

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

Necesitas pnpm para esto (los contribuidores fijan pnpm 11.7.0). Elige la compilación desde el código fuente cuando quieras ejecutar la última main en lugar de la versión candidata publicada, cuando planees leer o modificar el harness, o cuando quieras construir un preset personalizado desde el directorio apps/cli/config/agent-presets/ del repositorio. Para todos los demás, la ruta de npx es el mismo software con menos ceremonia: la compilación desde el código fuente no desbloquea funciones que le falten al paquete npm.

Los tres perfiles: web, headless y tui.

dsh se distribuye como tres perfiles de ejecución, y cuál uses depende de dónde se realiza el trabajo:

• web (por defecto) — la interfaz completa del navegador en el puerto 3080. Esto es lo que npx @deepseek-ai/dsh web inicia, y es el perfil que la mayoría de la gente instalará primero.

• headless — una tarea y luego salir. dsh --profile headless "run the test suite and report failures" inicia una sesión, ejecuta la tarea, escribe sus resultados y finaliza. El runtime headless es explícitamente un proceso de una sola tarea: no puedes inyectar seguimientos a mitad de ejecución, y las correcciones son una nueva ejecución contra el mismo espacio de trabajo. Este es el perfil para integrar en scripts y CI.

• tui — una interfaz de terminal para sesiones controladas por teclado: dsh --profile tui.

Los tres comparten la misma configuración (~/.dsh/profiles/<name>/) y el mismo sistema de plugins, por lo que mover una tarea de la interfaz web a headless es un cambio de comando, no una reinstalación.

Añadiendo plugins

La gestión de plugins es un comando CLI de primera clase, no un asunto de edición en el lugar:

npx @deepseek-ai/dsh plugin --profile web add <source>

La fuente puede ser un nombre de paquete npm, un repositorio de GitHub (github:user/repo), un tarball, o una carpeta local. La primera instalación más útil es el mercado oficial de plugins, que convierte el descubrimiento de plugins en una interfaz de usuario:

npx @deepseek-ai/dsh plugin --profile web add dshmarket

Luego reinicia el servicio web y abre Configuración → Mercado de plugins para explorar e instalar con un clic desde el catálogo. Dos reglas que confunden a la gente: los paquetes de plugins se montan al inicio del perfil, por lo que un plugin recién añadido necesita un reinicio de dsh web; y un simple npm install no registra un plugin en un perfil — debes usar dsh plugin. El ecosistema es joven pero no está vacío: la lista awesome-dsh-plugin mantenida por la comunidad ya cataloga cientos de plugins en categorías como interfaz de usuario, habilidades, herramientas, proveedores y notificaciones.

MCP, los cuatro preajustes y la reproducción de trayectoria.

Tres características importan una vez que superas una instalación básica:

MCP. dsh habla con el Model Context Protocol a través de un @deepseek-ai/dsh-mcp-client plugin incorporado. Hoy eso se configura en archivos, no en la interfaz: editas ~/.dsh/profiles/web/cordis.patch.yml (o un parche local del proyecto) y declaras el transporte de cada servidor — stdio para comandos locales como npx @playwright/mcp@latest, streamable-http para URLs remotas. Funciona, pero es la superficie menos pulida en la vista previa; espera inestabilidad ocasional y no hay GUI para alternar servidores.

Preajustes. dsh carga uno de los cuatro preajustes de agente por sesión, y cada uno representa una compensación diferente:

• Standard — el conjunto completo de herramientas: edición de archivos, shell, recuperación de archivos y web, habilidades, planificación, subagentes, flujos de trabajo. El predeterminado de uso diario.

• PTC (Llamada Programática a Herramientas) — Estándar más un SDK de Code Mode que permite al modelo escribir programas en TypeScript para orquestar llamadas a herramientas en múltiples rondas. Más potente, con más efectos secundarios.

• Minimal — solo bash y un editor de archivos, nada más. Construido para benchmarking de modelos y reproducción mínima; el modo que los documentos de la API de DeepSeek V4 Flash referenciaron cuando revelaron que sus propias puntuaciones de agente se ejecutaron en "Deep​Seek Harness minimal mode."

• Creación — un entorno de pruebas en tiempo de ejecución: inspecciona y carga plugins de Cordis en memoria, experimenta y consolida una combinación funcional en un nuevo preset.

Reproducción de trayectoria.Cada ejecución escribe un registro de sesión de solo anexión — indicaciones del sistema, razonamiento, llamadas a herramientas y sus resultados, planificación de subagentes. La vista de Trayectoria te permite inspeccionar por fuente, reanudar, bifurcar, buscar y reproducir una ejecución. Ese es el depurador para el trabajo de agentes: cuando una tarea falla, no vuelves a ejecutar y esperas; reproduces la trayectoria fallida, la bifurcas en el paso incorrecto y pruebas una corrección sin descartar la original.

La opción del SDK de Python

Si prefieres manejar el harness desde Python en lugar de desde un navegador, hay un SDK oficial: pip install deepseek-harness-sdk. Incluye el runtime de dsh (la rueda de pip incluye el runtime de Node, por lo que no necesitas instalar Node por separado), y su uso es un administrador de contexto: construye una instancia de Deep​SeekHarness, llama a run("task"). Hereda variables de entorno estándar como DEEPSEEK_API_KEY y DEEPSEEK_BASE_URL, por lo que cambiar de proveedor es solo un cambio de configuración. La pega: es Python 3.10+ y solo admite Linux x64/arm64 y macOS 14+ arm64 — no hay rueda nativa para Windows, lo que es una carencia real si Windows es tu sistema. En Windows, quédate con la ruta de npm.

Apuntando dsh a los modelos que pagas

dsh necesita una clave de API de modelo, y es deliberadamente agnóstico respecto al proveedor: Configuración → Modelos acepta un proveedor personalizado con una URL base compatible con Open​AI (en settings.yaml es decir, api: openai-completions, baseURL, y una lista de models). El valor predeterminado es la API propia de Deep​Seek; un proveedor personalizado es donde un gateway de enrutamiento se vuelve útil.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

Para ser claros sobre los límites: OrcaRouter aloja los modelos y las llamadas dsh; no aloja dsh en sí. dsh es un runtime de agente local, y lo ejecutas en tu propia máquina.

Dónde esta guía falla para ti — problemas honestos con la vista previa

Un tutorial de instalación que solo te dice qué escribir está haciendo la mitad del trabajo. Esto es lo que la vista previa hace mal hoy, para que no lo descubras a las 2 a.m.:

• Los cambios disruptivos son una promesa, no una advertencia. Estás en 0.1.0-rc.6. Las claves de configuración, la API de plugins y los formatos de preset pueden cambiar sin previo aviso. Trata ~/.dsh como estado desechable — el costo de una mala actualización es una reinstalación, y eso es aceptable en esta etapa solo porque la instalación es un comando.

• No necesitas dsh para usar los modelos Deep​Seek como agente. Si tu único objetivo hoy es DeepSeek V4 Flash o DeepSeek V4 Pro dentro de un agente, el endpoint compatible con Anthro​pic de Deep​Seek ya funciona en Claude Code y otras herramientas de agente sin necesidad de software nuevo. dsh es una opción de primera parte, no un requisito previo. Omite esta instalación hasta que quieras específicamente el harness nativo.

• MCP está configurado mediante archivos y a veces es inestable. No hay GUI, no hay interruptor de inicio/parada por servidor, y los informes de primera mano describen fallos intermitentes. Reserva tiempo para depurar YAML si tu flujo de trabajo depende de los servidores MCP.

• La confianza en los plugins es una decisión de seguridad.Los plugins de terceros se ejecutan dentro del proceso principal del harness, y no hay verificación de firma ni de origen en el momento de la instalación. Instala solo plugins que hayas leído o que provengan de una fuente de confianza, y pruébalos en un espacio de trabajo desechable antes de usarlos en trabajo real. El danger-full-access, que es un perfil de sandbox, puede modificar cualquier archivo visible: resérvalo para checkouts desechables.

• Existen errores conocidos en la vista previa. Un bucle bash colgado es un modo de fallo documentado (interrumpir y reintentar), y el comportamiento en torno a sesiones de larga duración todavía se está estabilizando.

• Las compilaciones de escritorio no oficiales son una trampa. Varios wrappers de la comunidad empaquetan dsh como una aplicación de escritorio que se instala con un clic y que incluye un runtime de Node. Funcionan, pero no están firmados ni mantenidos por Deep​Seek; si usas uno, estás confiando en un tercero con una herramienta que tendrá los permisos de tu sistema de archivos.

• Si necesitas estabilidad en producción, espera a una versión que no sea rc. El harness es potente pero inmaduro. Para una pila de agentes de producción, un harness maduro y probado en batalla — o la ruta de endpoint compatible con Anthropic — es la opción defendible hasta que dsh alcance una etiqueta estable.

En resumen

Instalar DeepSeek Harness es realmente un trabajo de un solo comando en cualquier máquina con Node 22.19+: npx @deepseek-ai/dsh web, añade una clave de modelo y un espacio de trabajo, envía una tarea de prueba. Elige la compilación desde el código fuente solo si quieres modificar o seguir main; usa el modo headless para scripts; añade el mercado de plugins desde el principio; y trata MCP como un trabajo en curso. La advertencia honesta es la misma que el proyecto imprime en su propio README: esto es una vista previa 0.1.0-rc y romperá cosas en el camino hacia la versión estable. Es el trade-off correcto si quieres ver hacia dónde lleva DeepSeek la capa de agentes — y los modelos que ejecuta, DeepSeek V4 Flash y DeepSeek V4 Pro, están disponibles hoy al precio de lista a través de OrcaRouter, listos para impulsar el harness al otro lado de la instalación.