Instalar DeepSeek Harness se hace con un solo comando. Treinta segundos después estás mirando una interfaz hermosa y completamente vacía en http://127.0.0.1:3080, y nadie te ha dicho qué hacer a continuación.
El README es famosamente escueto. El artículo de Cordis al que enlaza habla de composabilidad espaciotemporal. Tú solo querías que la cosa leyera tu código.
Esta guía comienza en esa pantalla vacía. Sí, obtendrás el comando de instalación, pero la parte que realmente te cuesta una tarde es conectar un proveedor de modelo, y hay tres valores predeterminados en ese paso que silenciosamente rompen los modelos de DeepSeek y desperdician el 75% de tu ventana de contexto. Casi nadie los documenta.
Conclusiones clave
npx @deepseek-ai/dsh webes toda la instalación. Node.js^22.19.0o>=24.0.0es el único requisito previo.- DeepSeek Harness es un armazón (harness), no un modelo. Viene sin ninguna credencial, por lo que no hace nada hasta que le conectes un proveedor.
- Cualquier endpoint compatible con OpenAI funciona, incluyendo la propia API de DeepSeek, una puerta de enlace (gateway) o un servidor local de Ollama.
- Cuando agregas un proveedor personalizado, el armazón adivina el dialecto de razonamiento a partir de tu URL base. Si adivina mal,
reasoning_contentfalla. - Los modelos declarados manualmente tienen por defecto una ventana de contexto de 262,144, por lo que la ventana completa de 1,048,576 de V4 permanece desactivada hasta que indiques lo contrario.
Terminal mostrando pruebas verdes que pasan junto a un armazón modular brillante, ilustrando cómo instalar DeepSeek Harness
La versión de 60 segundos de lo que estás construyendo
Aquí está la recompensa antes de cualquier teoría. Tres archivos en una carpeta vacía, un prompt para pegar, y el agente lee el código, ejecuta pytest, observa que fallan dos pruebas, cambia un solo carácter y vuelve a ejecutar hasta que el conjunto esté en verde.
DeepSeek Harness leyendo fizzbuzz.py, ejecutando pytest, corrigiendo el error de off-by-one y re-ejecutando hasta 3 pruebas pasadas
El bucle completo: leer, ejecutar, diagnosticar, parchear, re-ejecutar. Cada paso queda registrado en un registro de sesión de solo añadido que puedes reproducir más tarde.
Esa es la demostración que construiremos juntos en el Paso 6. Es deliberadamente lo suficientemente pequeña para reproducirla en un directorio de pruebas, y no depende de ningún repositorio externo que pueda cambiar la próxima semana.
Por qué la mayoría de los intentos de instalar DeepSeek Harness se estancan en el paso dos
La instalación es realmente trivial. El estancamiento ocurre inmediatamente después, y es una decisión de diseño más que un error: DeepSeek Harness no incluye claves, ni proveedor predeterminado, ni modelo empaquetado.
DeepSeek publicó el proyecto como código abierto el 13 de agosto de 2026 bajo la licencia MIT, y se disparó. Al 17 de agosto de 2026, el repositorio tiene 144,361 estrellas y 14,689 bifurcaciones (GitHub, agosto de 2026), lo que significa mucha gente llegando a la misma pantalla vacía en la misma semana.
El hilo de Hacker News de la semana de lanzamiento captura la reacción dividida. A la gente le encanta la transparencia: todo lo que el modelo ve se registra en un registro de sesión de solo añadido, y un comentarista señaló que "los modelos estadounidenses no te permiten ver eso". Las quejas son igual de consistentes. "El README es bastante escueto fuera de las instrucciones de instalación", escribió un desarrollador, y el artículo de Cordis obtuvo el veredicto de que parece "ensalada de palabras" (Hacker News, agosto de 2026).
Por lo tanto, las cuatro cosas que realmente bloquean a las personas son todas posteriores a la instalación:
- Node es demasiado antiguo, por lo que
npxfalla antes de que comience cualquier cosa. - El puerto 3080 ya está ocupado por otro servidor de desarrollo.
- El proveedor personalizado devuelve 401, o la lista de modelos aparece vacía.
- El modelo se conecta pero la salida de razonamiento llega dañada, o los archivos largos agotan la ventana de contexto temprano.
Los pasos 1 a 5 a continuación apuntan directamente a esos cuatro.
Antes de instalar DeepSeek Harness: elige un modelo y una clave
Responde primero: el armazón en sí es gratuito y local, pero no hará nada útil hasta que le proporciones una URL base compatible con OpenAI, una clave y al menos un ID de modelo. Decide esto antes de instalar y toda la configuración te llevará diez minutos.
Todo sucede en una pestaña del navegador en 127.0.0.1:3080. Puedes elegir entre tres rutas, y las tres funcionan.
Tabla B: opciones de acceso a modelos que funcionan con DeepSeek Harness hoy
| Ruta | URL base | Precio por 1M de tokens | Contexto | Pago | Mejor para |
|---|---|---|---|---|---|
| API oficial de DeepSeek | https://api.deepseek.com | V4-Flash $0.22 entrada / $0.66 salida valle, $0.44 / $1.32 pico. Aciertos de caché desde $0.007 | 1M | Varía según la región | Comportamiento propio, aciertos de caché muy baratos |
| Puerta de enlace compatible con OpenAI (ejemplo: Atlas Cloud) | https://api.atlascloud.ai/v1 | V4-Flash $0.14 entrada / $0.28 salida. V4-Pro $1.68 / $3.38 | 1,048,576 | Tarjeta, sin gasto mínimo | Tarifas planas sin recargo por hora punta |
| Ollama local | http://localhost:11434/v1 | Sin costo de tokens | Depende del modelo | Ninguno | Código privado, trabajo sin conexión |
Dos cosas que vale la pena saber antes de elegir. La API propia de DeepSeek cambió a facturación de pico y valle, donde las horas pico son de 01:00 a 04:00 y de 06:00 a 10:00 UTC, y el valle es exactamente la mitad del pico (Documentación de API de DeepSeek, agosto de 2026). El precio de entrada de aciertos de caché es extremadamente bajo, por lo que una carga de trabajo que relee el mismo contexto repetidamente puede ser muy barata con la API propia.
Una puerta de enlace intercambia eso por previsibilidad. Atlas Cloud sirve los mismos modelos de DeepSeek a una tarifa plana sin recargo por hora punta y sin suscripción, que es el ejemplo que usaré en la configuración a continuación porque no necesita un método de pago regional. Cambia a la ruta que se ajuste a tu situación; la forma de la configuración es idéntica para todas.
Cómo instalar DeepSeek Harness, paso a paso
Hay tres formas de hacerlo. Elige una fila, luego sigue los pasos.
Tabla A: métodos de instalación comparados
| Método | Tiempo | Necesita | Actualizaciones | Mejor para |
|---|---|---|---|---|
| npx | Menos de un minuto | Node 22.19+ o 24+ | Re-ejecutar npx | Casi todo el mundo |
| Desde fuente | De 5 a 10 minutos | Node, pnpm, git | git pull y rebuild | Contribuyentes, autores de plugins |
| Compilación de escritorio | Alrededor de un minuto | Nada | Reinstalar | Cualquiera que evite instalar Node |
Paso 1: Verifica tus requisitos previos antes de instalar DeepSeek Harness
El fallo más común es una versión de Node que parece lo suficientemente reciente pero no lo es. El repositorio requiere ^22.19.0 || >=24.0.0. Nada en la línea 23.x califica en ningún nivel de parche.
bash1node -v # debe ser >= 22.19.0 en 22.x, o >= 24.0.0 2npm -v 3
Si node -v imprime 22.14 o 20.x, actualiza antes de continuar. Solo necesitas pnpm si planeas compilar desde la fuente o crear plugins:
bash1npm install -g pnpm 2
Paso 2: Instala DeepSeek Harness con un solo comando
Esta es la instalación completa. Descarga e inicia el perfil web de una sola vez.
bash1npx @deepseek-ai/dsh web 2
Abre http://127.0.0.1:3080. Si ese puerto ya está ocupado, el lanzador pasa cualquier bandera que no reconozca directamente al perfil, por lo que puedes cambiarlo:
bash1npx @deepseek-ai/dsh web --port 8080 2
Lo que obtienes es un caparazón vacío. Sin proveedor, sin modelo, sin clave. Eso es esperado, y es donde la mayoría de las guías se detienen.
La interfaz web de DeepSeek Harness en 127.0.0.1:3080 inmediatamente después de la instalación, sin proveedor ni modelo configurados
Instalación completa, y completamente inerte. Todo a partir de aquí es cableado.
Paso 3: Obtén una clave de API para DeepSeek Harness
Cualquiera que sea la ruta que hayas elegido de la Tabla B, necesitas una clave y una URL base. Para la ruta propia, regístrate en platform.deepseek.com y crea una clave allí. Las opciones de facturación varían según la región, así que verifica que tu método de pago sea compatible antes de comprometerte.
Para la ruta de puerta de enlace utilizada en este tutorial, crea una clave en el panel de Atlas Cloud en Claves de API, luego expórtala para que el armazón pueda leerla sin almacenarla en un archivo de configuración:
bash1export ATLASCLOUD_API_KEY="sk-your-key-here" 2
La página de Claves de API del panel de Atlas Cloud con una clave recién creada, parcialmente oculta
Copia la clave una vez. No se mostrará de nuevo después de salir de la página.
Paso 4: Agrega tu proveedor de modelo a DeepSeek Harness
En la interfaz de usuario, ve a Configuración, luego Modelos, y luego Agregar un proveedor personalizado. El formulario necesita un ID de proveedor, un nombre para mostrar, una URL base, un protocolo de API, una credencial y al menos un modelo.
Una advertencia que los documentos repiten: el ID de proveedor es permanente. Se escribe en las solicitudes, sesiones guardadas, valores predeterminados del modelo y referencias de credenciales. Si no te gusta más tarde, tu única opción es crear un nuevo proveedor y eliminar el antiguo.
| Campo | Qué ingresar |
|---|---|
| ID de proveedor | atlas (minúsculas, permanente) |
| Nombre para mostrar | Atlas Cloud |
| URL base | https://api.atlascloud.ai/v1 |
| Protocolo de API | openai-completions |
| Clave de API | Tu clave |
| Modelos | Haz clic en Obtener modelos disponibles, o escribe deepseek-ai/deepseek-v4-flash manualmente |
Si obtener modelos devuelve 401, la clave es incorrecta. Si devuelve una lista vacía, el endpoint simplemente no expone un índice de modelos, lo cual es inofensivo: escribe el ID del modelo manualmente y continúa.
El formulario Agregar un proveedor personalizado completado, con la URL base, el protocolo de API y el control Obtener modelos marcados
Los tres campos que deciden si el siguiente paso funciona: URL base, protocolo y la lista de modelos.
Paso 5: Los tres valores predeterminados de DeepSeek Harness que rompen silenciosamente los modelos de DeepSeek
Esta es la parte que ninguna otra guía de instalación cubre, y es la razón por la que tu configuración puede parecer conectada pero comportarse de manera extraña.
La capa de LLM del armazón infiere qué dialecto de razonamiento hablar a partir de la URL de tu endpoint. Los documentos internos son contundentes sobre la consecuencia: "pi-ai adivina a partir de la URL del endpoint; la URL de una puerta de enlace privada no dice nada, por lo que a una puerta de enlace de dialecto DeepSeek se le hablaría en el dialecto de OpenAI sin forma de corregirlo". En términos simples, cualquier URL base que no sea claramente DeepSeek se trata como OpenAI, y el manejo de reasoning_content de DeepSeek falla.
La segunda y tercera trampas son de capacidad. Un modelo que declaraste manualmente utiliza defaultContextWindow de 262,144 y defaultMaxTokens de 32,768. V4 admite 1,048,576 tokens de contexto, por lo que aceptar el valor predeterminado desperdicia tres cuartas partes.
Escribe estos en tu archivo de configuración:
yaml1# $DSH_HOME/settings.yaml (por defecto es ~/.dsh/settings.yaml) 2llm-pi-ai: 3 providers: 4 atlas: 5 displayName: Atlas Cloud 6 api: openai-completions 7 baseURL: https://api.atlascloud.ai/v1 8 apiKeyEnv: ATLASCLOUD_API_KEY 9 compat: 10 thinkingFormat: deepseek # 1. detener la adivinanza basada en URL 11 defaultContextWindow: 1048576 # 2. el valor predeterminado es solo 262144 12 defaultMaxTokens: 32768 # 3. aumentar para trabajos de salida larga 13 models: 14 - id: deepseek-ai/deepseek-v4-flash 15 contextWindow: 1048576 16 - id: deepseek-ai/deepseek-v4-pro 17 contextWindow: 1048576 18
Tres cosas a tener en cuenta. La configuración resuelve primero el modelo, luego la ruta, luego la entrada del catálogo instalado, luego la adivinanza derivada de la URL, por lo que un valor por modelo siempre gana. Ambos interruptores compat, thinkingFormat y supportsReasoningEffort, existen solo bajo openai-completions; ponerlos en otro protocolo y la resolución falla. Y este adaptador deliberadamente no cubre Bedrock, Vertex, Azure ni Codex, cuyos flujos de autenticación necesitan más que una clave, un endpoint y encabezados.
Paso 6: Ejecuta tu primera tarea real en DeepSeek Harness
Ahora la demostración del principio de este artículo. Crea una carpeta vacía y agrega tres archivos.
fizzbuzz.py, que contiene un error de off-by-one:
python1def fizzbuzz(n): 2 out = [] 3 for i in range(1, n): 4 if i % 15 == 0: 5 out.append("FizzBuzz") 6 elif i % 3 == 0: 7 out.append("Fizz") 8 elif i % 5 == 0: 9 out.append("Buzz") 10 else: 11 out.append(str(i)) 12 return out 13
test_fizzbuzz.py, donde dos de tres pruebas fallan:
python1from fizzbuzz import fizzbuzz 2 3def test_starts_correctly(): 4 assert fizzbuzz(5)[:3] == ["1", "2", "Fizz"] 5 6def test_covers_every_number(): 7 assert len(fizzbuzz(15)) == 15 8 9def test_fifteen_is_fizzbuzz(): 10 assert fizzbuzz(15)[-1] == "FizzBuzz" 11
Y requirements.txt:
text1pytest>=8.0 2
Vale la pena ejecutar el conjunto manualmente primero, para que sepas a qué se enfrenta el agente:
text1.FF [100%] 2=================================== FAILURES =================================== 3___________________________ test_covers_every_number ___________________________ 4E AssertionError: assert 14 == 15 5___________________________ test_fifteen_is_fizzbuzz ___________________________ 6E AssertionError: assert '14' == 'FizzBuzz' 7=========================== short test summary info ============================ 82 failed, 1 passed in 0.01s 9
Configura el modo del agente en Estándar y el modelo en deepseek-ai/deepseek-v4-flash, luego pega este prompt exactamente:
Ejecuta pytest en este espacio de trabajo. Dos pruebas fallan. Encuentra la causa raíz en fizzbuzz.py, corrígela con el cambio más pequeño posible, luego vuelve a ejecutar pytest y muéstrame el resultado final. No edites el archivo de prueba.
La corrección correcta es un carácter: range(1, n) se convierte en range(1, n + 1), y el conjunto informa 3 passed.
Ahora la parte que hace que un armazón sea diferente de una ventana de chat. Cada ejecución se registra en un registro de sesión de solo añadido, y puedes bifurcarlo. Vuelve al punto donde el agente leyó por primera vez fizzbuzz.py y ramifica un segundo intento:
Bifurca esta sesión desde el paso donde leíste por primera vez fizzbuzz.py. Esta vez reescríbelo como una búsqueda basada en diccionario en lugar de parchear la rama if, luego ejecuta pytest de nuevo.
Bifurcación de un registro de sesión de DeepSeek Harness para producir una segunda implementación basada en diccionario desde el mismo punto de partida
Un punto de partida, dos ramas. Esta es la característica que realmente le importaba a la multitud de la semana de lanzamiento.
Paso 7: Usa el modo headless para scripts y CI
Dos perfiles se inicializan al primer uso: web y headless. Has estado usando web, y dsh web es solo un alias para dsh --profile web.
Headless ejecuta una sesión nueva persistente, imprime la respuesta final y sale, que es exactamente la forma que un trabajo de CI quiere:
bash1dsh --profile headless "Ejecuta las pruebas y corrige cualquier fallo. Informa del diff." 2
Cualquier otro perfil debe crearse a través de dsh plugin. Los perfiles viven en $DSH_HOME/profiles/<nombre>, que por defecto es ~/.dsh/profiles/<nombre>.
Salida de terminal de una ejecución headless de DeepSeek Harness que imprime la respuesta final y sale
Modo headless: una sesión, una respuesta, código de salida en el que puedes bifurcar.
Otras formas de instalar DeepSeek Harness
La ruta npx cubre a la mayoría de las personas. Estas tres vale la pena conocerlas.
Instalar DeepSeek Harness desde la fuente con pnpm
Si quieres leer el código, parchearlo o escribir plugins para él:
bash1git clone https://github.com/deepseek-ai/deepseek-harness 2cd deepseek-harness 3pnpm install 4pnpm run build 5pnpm dsh web 6
La compilación de escritorio de 5 MB
Un proyecto de la comunidad, hairyf/deepseek-harness-desktop, envuelve el armazón en Tauri y ofrece un instalador de aproximadamente 5 MB para Windows, macOS y Linux sin necesidad de instalar Node. No es un lanzamiento oficial de DeepSeek, así que trátalo en consecuencia: al momento de escribir esto tiene alrededor de 400 estrellas y se creó un día después del armazón mismo.
Ejecutar DeepSeek Harness completamente local con Ollama
Ollama incluye una integración de primera parte. La versión corta es un solo comando:
bash1ollama launch dsh 2
Eso instala y ejecuta el armazón con Ollama conectado, manteniendo su configuración en ~/.ollama/launch/dsh/settings.yaml (Documentación de Ollama, agosto de 2026). Una advertencia que vale la pena leer antes de asumir que todo está fuera de línea: la búsqueda web incorporada está habilitada automáticamente y necesita acceso a la nube de Ollama además de un modelo que admita herramientas. Un modelo realmente local te da un costo de token cero, a costa de velocidad y, generalmente, una capacidad de llamada a herramientas más débil.
DeepSeek Harness conectado a un servidor local de Ollama ejecutando la misma tarea de prueba fallida
Misma tarea, sin ida y vuelta de red, sin factura por token.
¿DeepSeek Harness es gratuito? Lo que realmente cuesta ejecutarlo
Respuesta primero: el software es gratuito y tiene licencia MIT, incluso para uso comercial. Los tokens no son gratuitos, a menos que ejecutes modelos localmente. Nada sobre el armazón en sí mismo es medido, restringido o vinculado a una cuenta de DeepSeek.
Tabla C: qué es realmente gratuito y qué no
| Componente | ¿Gratuito? | Notas |
|---|---|---|
| El software del armazón | Sí | Licencia MIT, no se necesita cuenta |
| Tokens de modelo a través de una API | No | Facturado por token por quien sirve el modelo |
| Tokens de modelo a través de Ollama local | Sí | Pagas en hardware y latencia en su lugar |
| Contexto largo | Depende | Precio por token, por lo que una ventana de 1M cuesta lo que la llenes |
Un ejemplo práctico, usando números redondos en lugar de una ejecución específica. Supongamos que una sesión de depuración como el Paso 6 consume 200,000 tokens de entrada y 20,000 tokens de salida, lo cual es realista una vez que el agente ha leído algunos archivos e iterado. A la tarifa plana de la puerta de enlace de $0.14 entrada y $0.28 salida, esa sesión cuesta alrededor de 3.4 centavos. En la API propia a tasas de fallo de caché en valle, es alrededor de 5.7 centavos, y durante las horas pico alrededor de 11 centavos. Si la mayor parte de tu entrada son aciertos de caché, la API propia se vuelve drásticamente más barata en el lado de entrada, porque la entrada de aciertos de caché comienza en $0.007 por 1M de tokens.
Las palancas prácticas, en orden de impacto: mantén las sesiones cortas para que el contexto no se acumule, ejecuta el trabajo rutinario en Flash y guarda Pro para las tareas realmente difíciles, y usa el modo Mínimo para ejecuciones de tipo benchmark, ya que le da al modelo exactamente dos herramientas y sin compactación de contexto.
Antes de implementar: licencia de DeepSeek Harness y riesgos de vista previa
Tres cosas breves, y luego las preguntas frecuentes.
La licencia es MIT, por lo que el uso comercial está bien. Pero el proyecto se etiqueta a sí mismo como una vista previa para desarrolladores y establece, en mayúsculas, que habrá cambios que rompen la compatibilidad. Fija una versión y no lo conectes a un pipeline de lanzamiento de producción todavía.
Tus credenciales viven en texto plano en tu máquina, en $DSH_HOME/.credentials.yaml con la configuración junto a $DSH_HOME/settings.yaml, ambos con valor predeterminado en ~/.dsh. Si tu directorio de armazón alguna vez termina dentro de un repositorio, agrégalo a .gitignore:
text1.dsh/ 2
Y la obvia que es fácil de olvidar: tu código va al endpoint que configuraste en el Paso 4. Lee los términos de datos de ese proveedor antes de apuntar un agente a una base de código privada.
Preguntas frecuentes
¿DeepSeek Harness es gratuito?
El armazón es gratuito y tiene licencia MIT, sin necesidad de cuenta ni suscripción, y puedes usarlo comercialmente. Los tokens del modelo se facturan por separado por el proveedor que conectes. Apuntarlo a un modelo local de Ollama te da una configuración verdaderamente sin costo de token, pagada en hardware y velocidad.
¿Necesito una clave de API de DeepSeek para instalar DeepSeek Harness?
No. La instalación y una clave de DeepSeek no están relacionadas. npx @deepseek-ai/dsh web se ejecuta sin ninguna credencial. Solo necesitas una clave cuando quieras que el agente realmente llame a un modelo, y puede ser una clave para cualquier endpoint compatible con OpenAI, incluido un servidor local.
¿Puede DeepSeek Harness ejecutar modelos que no sean de DeepSeek?
Sí. Los proveedores personalizados aceptan openai-completions, y el adaptador cubre protocolos que pueden describirse con una clave, un endpoint y encabezados. Agrega un segundo proveedor añadiendo otro bloque bajo providers: en settings.yaml con su propio ID, URL base y modelos. Bedrock, Vertex, Azure y Codex están deliberadamente fuera del alcance porque su autenticación necesita más que eso.
¿Por qué mi proveedor personalizado devuelve 401 o "modelo desconocido"?
Un 401 casi siempre significa que la clave es incorrecta o no se está leyendo desde la variable de entorno nombrada en apiKeyEnv. Un modelo desconocido generalmente significa que el endpoint no expone un índice de modelos, por lo que no se obtuvo nada: escribe el ID del modelo manualmente. También verifica la ortografía del ID de proveedor, ya que no se puede renombrar, solo reemplazar.
¿Dónde almacena DeepSeek Harness mi clave de API y configuración?
Las claves van a $DSH_HOME/.credentials.yaml y la configuración del modelo escrita a mano a $DSH_HOME/settings.yaml, ambos en ~/.dsh a menos que sobrescribas DSH_HOME. Las sesiones viven en $DSH_HOME/storages y los perfiles en $DSH_HOME/profiles/<nombre>. Mantén todo el directorio fuera del control de versiones.
¿DeepSeek Harness está listo para producción?
Todavía no, según su propia cuenta. El proyecto se publica como una vista previa para desarrolladores y advierte explícitamente sobre cambios que rompen la compatibilidad, lo cual es una descripción justa de un software que tiene unos pocos días. Úsalo para desarrollo local y asistencia en CI, fija la versión que probaste y vuelve a leer la documentación de proveedores después de las actualizaciones.
Verificado contra la vista previa para desarrolladores de DeepSeek Harness el 17 de agosto de 2026. Este proyecto incluye cambios de ruptura por diseño, por lo que si un nombre de campo en tu compilación se ve diferente del YAML anterior, consulta la documentación oficial de proveedores antes de asumir que la configuración es incorrecta.
