6 métodos para desplegar DeepSeek Harness localmente

TLDR DeepSeek Harness (dsh) es el runtime de agentes de código abierto de DeepSeek AI, publicado en developer preview alrededor del 13 de agosto de 2026 bajo la licencia MIT. Sigue el principio “Model + Harness = Agent”, con todas las capacidades (modelos, herramientas, sesiones, sandboxes, bucles, UI) implementadas como plugins intercambiables de Cordis.

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 interfaz Web en http://127.0.0.1:3080. Debes proporcionar una clave API de DeepSeek (u otro compatible con OpenAI) y un workspace. También hay compilaciones desde 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 costos mientras usas el harness, enruta las solicitudes a través del endpoint unificado compatible con OpenAI de CometAPI.

Key Takeaways

• 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.
• Admite modelos oficiales de DeepSeek (deepseek-v4-flash, deepseek-v4-pro), gateways personalizados compatibles con OpenAI y modelos locales vía plugins/Ollama.
• La arquitectura es totalmente basada en plugins (núcleo Cordis); los modos incluyen Standard, Minimal, Code y Creator.
• Adopción rápida: decenas de miles a más de 100k estrellas en GitHub en pocos días tras el lanzamiento.
• Recomendado para usuarios avanzados: combinar con CometAPI (https://www.cometapi.com/) como proveedor personalizado para acceso a 500+ modelos, ahorros del 20–40% y una sola clave API.
• Usa siempre un workspace aislado; el agente puede modificar archivos y ejecutar comandos.
• Estado de developer preview: se esperan breaking changes—fija versiones para experimentos cercanos a producción.

What Is DeepSeek Harness and Why It Matters in 2026

DeepSeek Harness (dsh) es un runtime de agentes de código abierto desarrollado por DeepSeek AI. Publicado bajo licencia MIT en developer preview, enfatiza la componibilidad: cada capacidad—adaptadores de modelo, herramientas, skills, sesiones, sandboxes, almacenamiento, bucles de agente, planificación y la UI—existe como un plugin de Cordis que puede montarse, desmontarse, intercambiarse o recomponerse mediante configuración. Efectivamente no hay un núcleo con privilegios que requiera parches.

Principios de diseño clave:

• Agent = Model + Harness.
• Flujos de eventos trazables con soporte para reanudar, bifurcar, buscar y reproducir.
• Múltiples modos de ejecución (conjunto completo estándar, modo de código/orquestación, modo minimal para benchmarking, modos creator/experimentales).
• Web UI local-first para uso interactivo, además de opciones headless y SDK para automatización.

Recursos oficiales:

• GitHub: https://github.com/deepseek-ai/deepseek-harness
• Product/landing: https://www.deepseek.com/harness/en/ (y su contraparte 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 diferentes. El DeepSeek Harness tratado en esta guía se ejecuta localmente en tu ordenador, pero el proyecto estándar deepseek-harness se conecta a DeepSeek V4-Pro o V4-Flash a través de una API. Eso significa que el harness, la configuración, las sesiones, la validación y la lógica del cliente pueden ser locales, mientras que la inferencia del modelo normalmente se realiza mediante la API de DeepSeek. Si necesitas inferencia realmente offline con los pesos del modelo en tu propia GPU, esa es una arquitectura de despliegue diferente.

Prerequisites and System Requirements

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. El rango objetivo es ^22.19.0 || >=24.0.0. Comprueba con node --version. Versiones intermedias de número impar fuera de este rango no están soportadas.
• Gestores de paquetes: npm/npx (vienen 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 API / endpoint: Una clave API de DeepSeek desde platform.deepseek.com, o cualquier endpoint compatible con OpenAI + clave + nombre de modelo.
• Hardware: No se requiere GPU para el harness en sí—la inferencia del modelo ocurre remotamente (o vía un proveedor local que configures). Los recursos de un portátil común son suficientes para la Web UI y la orquestación.
• Red: Necesaria en la primera ejecución para obtener paquetes; después la UI puede operar solo con las 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 para requisitos: README oficial y varias guías de instalación independientes publicadas poco después del lanzamiento.

Method 1: Official One-Liner with npx (Recommended for Most Users)

Esta es la vía más rápida y oficialmente promovida.

1. Asegúrate de que Node.js cumple el requisito de versión.
2. Abre una terminal y ejecuta:

Bash

npx @deepseek-ai/dsh web

1. El paquete se descarga (o usa caché), inicia el perfil de la Web UI y muestra la dirección de escucha—por defecto http://127.0.0.1:3080.
2. Abre esa URL en un navegador. Acepta el aviso de developer preview si aparece.
3. En el primer uso, configura un proveedor de modelos (Settings → Models) pegando tu clave API y seleccionando un modelo como deepseek-v4-flash o deepseek-v4-pro.
4. Elige o crea un directorio de workspace.
5. Comienza a ejecutar tareas.

Para usar un puerto distinto:

Bash
npx @deepseek-ai/dsh web --port 8080

Platform-specific one-liners que también garantizan la presencia de Node están disponibles en sitios comunitarios (PowerShell en Windows con winget, Homebrew en macOS, NodeSource en Debian/Ubuntu, etc.).

Pros: Huella de instalación permanente nula más allá de la caché de npm; siempre obtiene una versión reciente publicada; onboarding más simple. Contras: Depende de la red para el paquete inicial; menos conveniente para inspección profunda del código fuente o builds personalizados.

Method 2: Install and Run from Source

Usa esto cuando quieras leer plugins de 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

Aparecerá la misma Web UI en el puerto por defecto. Las builds de developer preview pueden romperse entre commits, así que trata esto como una vía experimental.

Method 3: Desktop Applications (Zero Node Setup)

Wrappers de escritorio comunitarios y de terceros empaquetan el runtime para que los usuarios eviten instalar Node/pnpm por su cuenta:

• Clientes ligeros basados en Tauri que bootstrappean un runtime de Node incluido y sincronizan el harness aguas arriba más reciente al inicio. Se ejecutan en 127.0.0.1:3080, mantienen los datos locales y registran comandos dsh.
• Empaquetado basado en Electron que incluye dependencias fijadas.

Descarga los instaladores desde las páginas de Releases de sus respectivos repositorios en GitHub (busca “deepseek-harness-desktop”). En el primer inicio se descargan los componentes principales (unos cientos de MB). Son convenientes para no técnicos pero no son productos oficiales de DeepSeek—revisa el repositorio y checksums SHA.

Method 4: Docker / Container Deployment

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   # set API key / public host
docker compose up -d --build

Útil para acceso por LAN, servidores o entornos donde no se desea Node en el host. Algunas configuraciones admiten settings.yaml personalizado para proveedores no-DeepSeek.

Method 5: Python SDK for Programmatic / Headless Use

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
# optional: export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# optional: 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 un directorio de sesiones aislados. El SDK incluye su propio runtime y no requiere Node.js del sistema.

Method 6: Ollama Integration

Ollama ofrece un lanzador de conveniencia:

Bash

ollama launch dsh
# or with a specific model
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 cloud de Ollama.

Configuring Models and Providers (Including CometAPI)

Dentro de la Web UI, ve a Settings → Models.

• Para DeepSeek oficial: pega la clave desde platform.deepseek.com. Modelos típicos: deepseek-v4-flash y deepseek-v4-pro.
• Para proveedores de catálogo (Anthropic, OpenAI, etc.): usa el flujo “Add provider”.
• Para endpoints personalizados/autohospedados/agregadores: elige “Add a custom provider”. Proporciona un ID de proveedor permanente, base URL, protocolo (normalmente openai-completions), referencia a variable de entorno de la clave API o valor, y al menos un ID de modelo.

Recomendación de CometAPI (muy sugerida para muchos flujos cercanos a producción). CometAPI es una plataforma unificada de infraestructura de IA que expone 500+ modelos (incluyendo variantes de DeepSeek, GPT, Claude, Gemini, Grok y muchos otros) mediante un único endpoint compatible con OpenAI: https://api.cometapi.com/v1.

Beneficios al usarlo con DeepSeek Harness:

• Una sola clave API en lugar de gestionar múltiples credenciales de proveedores.
• Precios competitivos (se reportan ahorros del 20–40% frente a tarifas directas de muchos proveedores).
• Alta disponibilidad (objetivo de 99.9% SLA), baja latencia mediana y facturación pay‑as‑you‑go.
• Cambio de modelo sencillo para A/B testing u optimización de costos 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
• Protocolo: openai-completions (o la opción equivalente soportada)
• Clave API: tu clave de CometAPI
• ID de modelo: cualquier cadena de modelo soportada del catálogo de modelos de CometAPI

Esta combinación conserva el potente runtime local de agentes y, a la vez, ofrece acceso multimarca flexible, rentable y de coste eficiente. Los nuevos usuarios suelen recibir créditos de prueba gratuitos. Documentación: https://apidoc.cometapi.com/.

Las claves se almacenan como write‑only (p. ej., bajo $DSH_HOME/.credentials.yaml); la UI solo muestra descriptores redactados.

Troubleshooting DeepSeek Harness

DEEPSEEK_API_KEY not found

Comprueba:

echo $DEEPSEEK_API_KEY

En Windows:

echo $env:DEEPSEEK_API_KEY

Si está vacío, configúralo de nuevo.

400 reasoning_content error

Esto normalmente apunta a un manejo incorrecto del ciclo de vida del razonamiento.

Verifica que tu aplicación preserve la información relevante de razonamiento del asistente a lo largo de las solicitudes de pensamiento/llamada de herramienta multi-turno.

Este es uno de los problemas centrales que el harness está específicamente diseñado para manejar.

Context-length error

Comprueba:

input tokens + max_tokens

El límite rígido documentado es:

1,048,576 tokens

Reduce el contexto de entrada o el tamaño de completion solicitado.

Tool calls become malformed during streaming

No asumas que los fragmentos del stream llegan en el orden de las herramientas.

Agrupa los deltas de llamadas a herramientas por tool_call.index, como recomienda el contrato del harness.

Requests are unexpectedly expensive

Revisa:

• modo de thinking
• longitud de la salida
• tasa de aciertos de caché
• estabilidad del prefijo de prompt
• elección de modelo
• precios actuales de la API

Una mejora simple suele ser mover tareas rutinarias de Pro a Flash.

Comparison of Installation and Deployment Methods

Datos sintetizados de la documentación oficial y guías publicadas tras el lanzamiento (agosto de 2026).

Conclusion and Next Steps

DeepSeek Harness aporta un runtime de agentes de diseño limpio y totalmente basado en plugins a las máquinas locales con una fricción casi nula mediante el one‑liner npx. Combinado con enrutamiento flexible de modelos—especialmente a través de una plataforma unificada como CometAPI—obtienes tanto el poder de flujos de trabajo de codificación agentic modernos como control práctico sobre el costo, la elección de modelos y la localidad de los 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 costos o el SDK de Python para automatización.

Para las instrucciones oficiales más recientes, da prioridad al repositorio de GitHub y doc. Para confiabilidad multimodelo y ventajas de precio mientras ejecutas el harness, explora CometAPI y su documentación en https://apidoc.cometapi.com/.