TL;DR DeepSeek Harness (dsh) es el runtime de agentes de código abierto de DeepSeek AI, publicado en versión preliminar para desarrolladores alrededor del 13 de agosto de 2026 bajo licencia MIT. Sigue el principio “Modelo + Harness = Agente”, con cada capacidad (modelos, herramientas, sesiones, sandboxes, bucles, UI) implementada como plugins Cordis intercambiables.
La forma más rápida de ejecutarlo localmente es npx @deepseek-ai/dsh web (requiere Node.js ^22.19 o ≥24), lo que inicia una Web UI en http://127.0.0.1:3080. Debes proporcionar una clave de API de DeepSeek (o compatible con OpenAI) y un workspace. También hay compilaciones desde el código fuente, aplicaciones de escritorio, Docker, SDK de Python e integraciones con Ollama. Para acceso multimodelo de nivel producción, confiabilidad y control de costes mientras usas el harness, enruta las solicitudes a través del endpoint unificado compatible con OpenAI de CometAPI.
Puntos clave
- DeepSeek Harness no es un modelo: es el runtime/orquestador local que permite a los modelos actuar sobre archivos, shells, herramientas y sesiones.
- One-liner oficial:
npx @deepseek-ai/dsh web→ abre la Web UI local en el puerto 3080. - El requisito de Node.js es estricto: ^22.19.0 o ≥24.x.
- Compatible con modelos oficiales de DeepSeek (deepseek-v4-flash, deepseek-v4-pro), gateways personalizados compatibles con OpenAI y modelos locales vía plugins/Ollama.
- Arquitectura totalmente basada en plugins (kernel Cordis); los modos incluyen Standard, Minimal, Code y Creator.
- Adopción rápida: de decenas de miles a más de 100k estrellas en GitHub en días tras el lanzamiento.
- Recomendado para usuarios avanzados: combínalo con CometAPI (https://www.cometapi.com/) como proveedor personalizado para acceder a 500+ modelos, ahorrar 20–40% en costes y usar una sola clave de API.
- Usa siempre un workspace aislado; el agente puede modificar archivos y ejecutar comandos.
- El estado de versión preliminar para desarrolladores implica cambios incompatibles; fija versiones para experimentos de tipo producción.
Qué es DeepSeek Harness y por qué importa en 2026
DeepSeek Harness (dsh) es un runtime de agentes de código abierto desarrollado por DeepSeek AI. Publicado bajo licencia MIT en versión preliminar para desarrolladores, enfatiza la composabilidad: cada capacidad—adaptadores de modelos, herramientas, skills, sesiones, sandboxes, almacenamiento, bucles de agente, programación y la UI—existe como un plugin Cordis que puede montarse, desmontarse, intercambiarse o recomponerse mediante configuración. En la práctica no hay un núcleo privilegiado que requiera parches.
Principios de diseño clave incluyen:
- Agente = Modelo + Harness.
- Flujos de eventos trazables con reanudación, bifurcación, búsqueda y reproducción.
- Múltiples modos de ejecución (conjunto completo estándar, modo de código/orquestación, modo minimal para benchmarking, modos creator/experimentales).
- Interfaz web local para uso interactivo más opciones sin interfaz y SDK para automatización.
Recursos oficiales:
- GitHub: https://github.com/deepseek-ai/deepseek-harness
- Producto/landing: https://www.deepseek.com/harness/en/ (y su versión en chino)
- Las páginas de instalación y mirrors de la comunidad refuerzan los mismos comandos básicos.
Nota importante de terminología: “despliegue local” puede significar dos cosas distintas. El DeepSeek Harness tratado en esta guía se ejecuta localmente en tu equipo, pero el proyecto estándar
deepseek-harnessse conecta a DeepSeek V4-Pro o V4-Flash mediante una API. Esto significa que el harness, la configuración, las sesiones, la validación y la lógica de cliente pueden ser locales, mientras que la inferencia del modelo normalmente la realiza la API de DeepSeek. Si necesitas inferencia realmente offline con los pesos del modelo en tu propia GPU, eso es una arquitectura de despliegue diferente.
Requisitos previos y del sistema
Antes de instalar, verifica lo siguiente:
- Sistemas operativos: Windows 10+, macOS 10.15+, Linux mainstream (x64 o arm64). El SDK de Python tiene restricciones adicionales (Linux x64/arm64 o macOS 14+ arm64).
- Node.js: Requerido para la ruta principal de la Web UI. Rango objetivo: ^22.19.0 || ≥24.0.0. Comprueba con node --version. Versiones intermedias impares fuera de este rango no están soportadas.
- Gestores de paquetes: npm/npx (incluidos con Node). Las compilaciones desde fuente requieren pnpm (instala con npm install -g pnpm).
- Git: Requerido para clonar el código fuente.
- Python (opcional): 3.10+ para el SDK oficial de Python.
- Clave de API / endpoint: una clave de API de DeepSeek desde platform.deepseek.com, o cualquier endpoint compatible con OpenAI + clave + nombre de modelo.
- Hardware: No se requiere GPU para el propio harness; la inferencia del modelo ocurre de forma remota (o vía un proveedor local que configures). Recursos de un portátil común bastan para la Web UI y la orquestación.
- Red: Necesaria en la primera ejecución para descargar paquetes; después la UI puede operar solo con llamadas a la API del modelo.
- Workspace: Prepara un directorio aislado. El agente puede leer, escribir y ejecutar comandos dentro del workspace configurado; nunca lo apuntes a datos de producción o personales sin salvaguardas.
Fuentes de requisitos: README oficial y múltiples guías de instalación independientes publicadas poco después del lanzamiento.
Método 1: One-liner oficial con npx (recomendado para la mayoría)
Esta es la ruta más rápida y promovida oficialmente.
- Asegúrate de que Node.js cumple el requisito de versión.
- Abre una terminal y ejecuta:
Bash
npx @deepseek-ai/dsh web
- El paquete se descarga (o usa la caché), inicia el perfil de Web UI y muestra la dirección de escucha; por defecto http://127.0.0.1:3080.
- Abre esa URL en un navegador. Acepta el aviso de versión preliminar si aparece.
- En el primer uso, configura un proveedor de modelos (Settings → Models) pegando tu clave de API y seleccionando un modelo como deepseek-v4-flash o deepseek-v4-pro.
- Elige o crea un directorio de workspace.
- Comienza a lanzar tareas.
Para usar un puerto diferente:
Bash
npx @deepseek-ai/dsh web --port 8080
One-liners específicos por plataforma que también aseguran que Node esté presente están disponibles desde sitios comunitarios (PowerShell en Windows con winget, Homebrew en macOS, NodeSource en Debian/Ubuntu, etc.).
Ventajas: Huella de instalación nula más allá de la caché de npm; siempre obtiene una versión publicada reciente; onboarding más simple. Contras: Depende de la red para el paquete inicial; menos conveniente para inspección profunda del código fuente o compilaciones personalizadas.
Método 2: Instalar y ejecutar desde el código fuente
Úsalo cuando quieras leer plugins Cordis, fijar un commit, desarrollar presets personalizados o contribuir.
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
La misma Web UI aparece en el puerto por defecto. Las compilaciones de versión preliminar para desarrolladores pueden romperse entre commits, así que trátalo como una ruta experimental.
Método 3: Aplicaciones de escritorio (sin configurar Node)
Wrappers de escritorio de la comunidad y terceros empaquetan el runtime para que los usuarios eviten instalar Node/pnpm:
- Clientes ligeros basados en Tauri que arrancan un runtime de Node incluido y sincronizan el harness upstream más reciente al iniciar. Corren en 127.0.0.1:3080, mantienen los datos locales y registran comandos dsh.
- Empaquetado con Electron que incluye dependencias fijadas.
Descarga instaladores desde las páginas de Releases de sus respectivos GitHub (busca “deepseek-harness-desktop”). El primer arranque descarga los componentes principales (unos cientos de MB). Son convenientes para no técnicos pero no son productos oficiales de DeepSeek; revisa el repositorio y los checksums SHA.
Método 4: Despliegue con Docker / contenedores
Existen imágenes Docker y archivos compose de la comunidad para ejecutar la Web UI dentro de un contenedor, a menudo con terminación HTTPS vía nginx y soporte para gateways arbitrarios compatibles con OpenAI. Flujo típico:
Bash
git clone <docker-repo>
cd <docker-repo>
cp .env.example .env # establece la clave de API / host público
docker compose up -d --build
Útil para acceso en LAN, servidores o entornos donde no se desea Node en el host. Algunas configuraciones admiten settings.yaml personalizado para proveedores que no sean DeepSeek.
Método 5: SDK de Python para uso programático / sin interfaz
Para agentes desatendidos o integración en pipelines de Python:
Bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install deepseek-harness-sdk
Configura variables de entorno:
Bash
export DEEPSEEK_API_KEY=sk-your-key-here
# opcional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# opcional: export DSH_MODEL=deepseek-v4-flash
Luego ejecuta los ejemplos incluidos o usa la clase DeepSeekHarness en tu propio código contra un workspace y directorio de sesión aislados. El SDK incluye su propio runtime y no requiere Node.js en el sistema.
Método 6: Integración con Ollama
Ollama proporciona un lanzador conveniente:
Bash
ollama launch dsh
# o con un modelo específico
ollama launch dsh --model deepseek-v4-flash:cloud
Ollama puede instalar el paquete si es necesario y guarda la configuración de lanzamiento por separado. La búsqueda web y el soporte de herramientas dependen del modelo elegido y del acceso en la nube de Ollama.
Configuración de modelos y proveedores (incluido CometAPI)
Dentro de la Web UI ve a Settings → Models.
- Para DeepSeek oficial: pega la clave desde platform.deepseek.com. Los modelos típicos son deepseek-v4-flash y deepseek-v4-pro.
- Para catálogos de proveedores (Anthropic, OpenAI, etc.): usa el flujo “Add provider”.
- Para endpoints personalizados/autogestionados/agrupadores: elige “Add a custom provider”. Indica un Provider ID permanente, base URL, protocolo (normalmente openai-completions), referencia a variable de entorno de la clave API o valor, y al menos un Model ID.
Recomendación CometAPI (muy sugerida para muchos flujos de trabajo tipo producción) CometAPI es una plataforma unificada de infraestructura de IA que expone 500+ modelos (incluidas variantes de DeepSeek, GPT, Claude, Gemini, Grok y muchos más) mediante un único endpoint compatible con OpenAI: https://api.cometapi.com/v1.
Beneficios al usarlo con DeepSeek Harness:
- Una sola clave de API en lugar de gestionar credenciales de múltiples proveedores.
- Precios competitivos (se reporta 20–40% de ahorro frente a tarifas directas de muchos proveedores).
- Alta disponibilidad (objetivo de SLA 99.9%), baja latencia mediana y facturación de pago por uso.
- Cambio fácil de modelo para pruebas A/B u optimización de costes sin cambiar la configuración del harness más allá del ID de modelo.
- Compatibilidad plug-and-play: los patrones existentes del SDK de OpenAI funcionan tras cambiar solo base_url y la clave.
En el formulario de proveedor personalizado del harness:
- Base URL:
https://api.cometapi.com/v1 - Protocol: openai-completions (o la opción equivalente compatible)
- API key: tu clave de CometAPI
- Model ID: cualquier cadena de modelo soportada del catálogo de CometAPI
Esta combinación mantiene el potente runtime de agente local mientras ofrece acceso multimarca flexible, rentable y de coste efectivo. Los nuevos usuarios suelen recibir créditos de prueba gratuitos. Documentación: https://apidoc.cometapi.com/.
Las claves se almacenan en modo solo escritura (p. ej., bajo $DSH_HOME/.credentials.yaml); la UI solo muestra descriptores redactados.
Solución de problemas de DeepSeek Harness
DEEPSEEK_API_KEY no encontrado
Comprueba:
echo $DEEPSEEK_API_KEY
En Windows:
echo $env:DEEPSEEK_API_KEY
Si está vacío, configúralo de nuevo.
Error 400 reasoning_content
Normalmente apunta a un manejo incorrecto del ciclo de razonamiento.
Verifica que tu aplicación preserve la información relevante de razonamiento del asistente a lo largo de solicitudes multivuelta de razonamiento/llamadas a herramientas.
Este es uno de los problemas centrales que el harness está diseñado específicamente para manejar.
Error de longitud de contexto
Comprueba:
input tokens + max_tokens
El límite máximo documentado es:
1,048,576 tokens
Reduce el contexto de entrada o el tamaño de la respuesta solicitada.
Las llamadas a herramientas se deforman durante el streaming
No asumas que los fragmentos del stream llegan en orden de herramientas.
Agrega los deltas de tool-call por tool_call.index, como recomienda el contrato del harness.
Las solicitudes son inesperadamente costosas
Comprueba:
- modo de razonamiento
- longitud de salida
- tasa de aciertos de caché
- estabilidad del prefijo del prompt
- elección de modelo
- precios actuales de la API
Una mejora simple suele ser mover tareas rutinarias de Pro a Flash.
Comparación de métodos de instalación y despliegue
| Método | Facilidad de uso | Requiere Node | Ideal para | Persistencia / Control | Puerto / Acceso típico | Notas |
|---|---|---|---|---|---|---|
| one-liner npx | Muy alta | Sí | Pruebas rápidas, la mayoría de usuarios | Efímero (solo caché) | 3080 (configurable) | Recomendado oficialmente |
| Código fuente (pnpm) | Media | Sí | Desarrollo, plugins, fijar commits | Control total del código fuente | 3080 | Requiere pnpm + compilación |
| Escritorio (Tauri/Electron) | Alta | No (incluido) | Usuarios no técnicos | Perfiles locales y autoactualización | 3080 (interno) | Paquetes de la comunidad |
| Docker | Media | No (contenedor) | Servidores, LAN, HTTPS | Volúmenes de contenedor | Personalizado / 443 | Imágenes de la comunidad |
| SDK de Python | Media | No (incluido) | Sin UI, automatización, pipelines | Sesiones programáticas | N/D (sin UI por defecto) | SDK oficial |
| Lanzamiento con Ollama | Alta | Opcional | Experimentos con modelos locales | Configuración de Ollama | 3080 | Se integra con Ollama |
Datos sintetizados de la documentación oficial y guías posteriores al lanzamiento (agosto de 2026).
Conclusión y próximos pasos
DeepSeek Harness ofrece un runtime de agentes totalmente basado en plugins para máquinas locales con casi cero fricción vía el one-liner npx. Combinado con enrutamiento de modelos flexible—especialmente mediante una plataforma unificada como CometAPI—obtienes tanto el poder de flujos de trabajo modernos de codificación agentic como control práctico sobre costes, elección de modelos y localidad de datos.
Empieza hoy con:
npx @deepseek-ai/dsh web
Configura una clave de DeepSeek o CometAPI, apúntalo a un workspace seguro y explora el modo Standard. Luego experimenta con el modo Minimal para benchmarks, proveedores personalizados para optimización de costes o el SDK de Python para automatización.
Para las instrucciones oficiales más recientes, da preferencia siempre al repositorio de GitHub y a la documentación. Para fiabilidad multimodelo y ventajas de precio mientras ejecutas el harness, explora CometAPI y su documentación en https://apidoc.cometapi.com/.


