DeepSeek Harness (dsh): Instalación, Ejecuciones sin interfaz gráfica, Prueba de referencia con 3 modelos

Categoría
IA y LLM Local
Publicado
18 agosto 2026
Actualizado
16 septiembre 2026
Por
Jacob Lloyd — escrito con ayuda de IA, después del proyecto
Tiempo de lectura
18 min de lectura

En palabras simples: DeepSeek lanzó un “agente de programación” gratuito y de código abierto: un programa que analiza tu proyecto, edita archivos y ejecuta comandos por ti, similar a Claude Code. En este artículo explico cómo lo instalé en mi PC con Linux, cómo hice que se iniciara automáticamente, cómo lo configuré para que utilizara tanto los modelos en la nube de DeepSeek como un modelo alojado en mi propio hardware; además, lo probé en 5 pequeñas tareas de programación reales. Las 15 pruebas se completaron con éxito; las ejecuciones en la nube costaron unos pocos centavos, aunque todavía existen algunos aspectos que necesitan mejorar.

Seis segundos: se creó el archivo, se ejecutó el programa, se imprimió la respuesta y el código de salida fue 0. Eso es lo que DeepSeek Harness (dsh) hizo con la primera tarea que le asigné. DeepSeek lo lanzó el 13 de agosto de 2026 como un agente de programación bajo licencia MIT, basado en una idea simple: todo es un plugin, incluyendo el adaptador del modelo, las herramientas, el entorno aislado y el propio bucle del agente. Lo instalé esa misma semana, lo configuré para que usara tanto los modelos en la nube de DeepSeek como un modelo en mi propia GPU, y lo sometí a una serie de pruebas. A continuación detallo lo que implicó, cuánto costó y dónde presentaron problemas.

Resumen rápido

  • ¿Qué es?: un agente similar a Claude Code (lee y edita archivos, ejecuta comandos del shell, mantiene un plan de trabajo y genera subagentes) distribuido como paquete npm. Cuenta con una interfaz web en 127.0.0.1:3080 y un modo headless que imprime una única respuesta y finaliza, ideal para scripts.
  • Costo: el software es gratuito. Mi conjunto de pruebas, compuesto por 5 tareas, costó aproximadamente 3 centavos en V4-Flash y 7 centavos en V4-Pro a tarifas máximas; con el modelo local no hubo costo alguno.
  • Resultado: 15/15 pruebas superadas tanto en V4-Flash como en V4-Pro y en un modelo Gemma-4-26B local, utilizando la versión 0.1.0-rc.7; el tiempo total de ejecución fue de 43 a 56 segundos. En una tarea real (compilar y verificar enlaces de un sitio web de 290 páginas), detectó, sin que se lo pidiera, que mi guía de procedimientos estaba desactualizada.
  • Requisitos: Node.js, además de una clave API de DeepSeek o cualquier servidor compatible con OpenAI. Yo utilicé ambos.
  • Advertencia: se trata de una versión preliminar para desarrolladores. El README advierte que algunas funcionalidades podrían dejar de funcionar entre versiones; por eso es recomendable fijar la versión y volver a probar tras cada actualización.

Actualización del 16-09-2026: las pruebas aquí descritas se realizaron en agosto con la versión 0.1.0-rc.7. Posteriormente pasé a usar la 0.1.5-rc.1; su README incluye también perfiles SDK y ACP. El 09-09-2026 retiré de mi entorno Reasonix, el otro agente de programación con el que comparaba en este artículo; ahora esa comparación queda únicamente como una breve nota histórica al final.

El proceso: desde lo básico hasta lo avanzado

Los pasos del 1 al 3 le permitirán tener un agente funcional en unos diez minutos. Los pasos 4 y 5 lo convertirán en algo que otros programas puedan invocar.

¿Qué obtienes al final?

La parte que realmente uso es el modo headless. Desde dentro de una carpeta de proyecto:

$ cd ~/scratch/dsh-demo
$ dsh --profile headless "Create fizz.py that prints FizzBuzz for 1..15 and run it; reply with the program output only."

1
2
Fizz
4
Buzz
…
FizzBuzz
$ echo $? 0

Los triple comillas invertidas son propias de dsh: envuelve sus respuestas en un bloque de código Markdown. No escribe nada fuera de la carpeta desde la cual se inicia (el modo de permisos por defecto es workspace-write). Solo imprime el mensaje final en stdout, y guarda cada ejecución para que puedas abrirla más tarde en la interfaz web y ver cada llamada a herramientas así como el conteo de tokens.

La mejor prueba fue una tarea real, no un simple ejercicio. Le indiqué que procesara la carpeta de código fuente de este sitio web y le pedí que leyera el manual de operaciones del proyecto, ejecutara las comprobaciones de construcción y enlaces, y generara un informe, sin realizar ediciones ni publicar nada. En 53 segundos leyó el manual, ejecutó los comandos adecuados y reportó los resultados del verificador: 290 páginas, 1.752 imágenes, cero enlaces rotos, además del tiempo de compilación. Luego, sin que se lo pidiera, señaló que el manual aún indicaba “288 páginas” y resaltó esa discrepancia. Ese es el tipo de tarea sencilla que ahora delego sin pensarlo dos veces.

La interfaz web tiene el diseño habitual de 2026: sesiones a la izquierda, chat en el centro y una página de configuración para los modelos. Un buen hábito: pega la clave API en esa página de configuración, no en un archivo de configuración.

La interfaz web de dsh integrada en una app de chat: una sesión finalizada 'Crear y ejecutar hello.py' muestra sus pasos de inyección de contexto, 'Think', 'Write' y 'Bash', la respuesta 'hello from dsh' y una línea de estadísticas con turnos, pasos, latencia y tasa de aciertos en el caché; debajo, una barra de estado con el estado 'Running', un desplegable de modelos ajustado en DeepSeek-V4-Flash, y botones para Iniciar, Reiniciar y Detener
La interfaz web de dsh (capturada en agosto, integrada en mi propia app de chat). Una sesión finalizada muestra el historial de pasos realizados (Think → Write → Bash) y una línea de estadísticas por turno. La barra inferior corresponde a los controles de mi app para la unidad systemd y el modelo predeterminado; no forma parte de dsh.

Paso 1: instalación (dos minutos)

Se trata de un único paquete npm. Yo utilizo un prefijo privado para Node destinado a herramientas de agentes, de modo que nada se instala en el árbol del sistema; en un escritorio Fedora inmutable como el mío, ese es el único lugar adecuado para ello. La instalación global sigue siendo el mismo comando.

npm install -g @deepseek-ai/dsh
dsh --version          # 0.1.0-rc.7 when I benchmarked it
dsh web                # starts the UI, prints http://127.0.0.1:3080

Abra la URL correspondiente, vaya a Configuración → Modelos, pegue su clave de DeepSeek y guárdela. Esto creará el archivo ~/.dsh/.credentials.yaml (con permisos 0600), y el modelo comenzará a funcionar de inmediato, sin necesidad de reiniciar nada. Si desea automatizar este proceso, el archivo es un simple mapeo en formato YAML (DEEPSEEK_API_KEY: sk-…). Yo generé el mío a partir del archivo de entorno que ya utilizan mis otros servicios; de ese modo, la clave nunca aparece en el historial del shell ni en ningún archivo de configuración.

Dos cosas que debe saber antes de continuar:

  • La telemetría está desactivada por defecto. Si no se define la variable DSH_TELEMETRY_MODE, esta queda deshabilitada. He revisado la configuración proporcionada, no el texto promocional: el exportador OTLP existe, pero no está activado.
  • El entorno de ejecución es real, aunque limitado. En el modo predeterminado, las operaciones de escritura se restringen a la carpeta desde la cual se inicia el programa. Las lecturas, en cambio, no tienen restricciones; eso queda claro en la documentación. No lo ejecute desde su carpeta personal si va a realizar tareas importantes, y tampoco lo apunte a carpetas que contengan información confidencial.

Paso 2: ejecútelo como un servicio

La interfaz web es un proceso de Node que se ejecuta durante mucho tiempo. Quería que se iniciara al iniciar sesión, sin necesidad de usar la terminal y limitado únicamente al bucle de retorno (loopback). Una unidad systemd con el parámetro --user hace exactamente eso:

# ~/.config/systemd/user/dsh-web.service
[Unit]
Description=DeepSeek Harness web UI (dsh web) on 127.0.0.1:3080
After=network.target

[Service]
WorkingDirectory=%h
Environment=DSH_HOME=%h/.dsh
# Use the path from `which dsh`. systemd does not allow comments at the end of a line.
ExecStart=/usr/local/bin/dsh web --host 127.0.0.1 --port 3080
Restart=on-failure
RestartSec=3

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now dsh-web.service
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/   # 200

WorkingDirectory define la carpeta raíz del área de trabajo por defecto de la interfaz, pero esta sigue exigiendo que el usuario seleccione un área de trabajo antes de poder escribir nada. Ese es un buen valor predeterminado. La CLI también rechaza el uso de --host 0.0.0.0; los desarrolladores indican que vincular el servicio a todas las interfaces de red “aún no está soportado intencionalmente”. La interfaz web no cuenta con sistema de inicio de sesión alguno, así que estoy de acuerdo con esa decisión. Si necesita acceder a ella desde otra máquina, coloque un proxy inverso con autenticación delante, o utilice el navegador de la propia máquina mediante escritorio remoto; eso es lo que yo hago.

Paso 3: modelos en un único archivo YAML, recargados dinámicamente

~/.dsh/settings.yaml contiene el modelo predeterminado y cualquier proveedor adicional. dsh lo vuelve a leer antes de la siguiente solicitud, por lo que no es necesario reiniciar ni volver a iniciar sesión. El mío se ve así:

agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash          # or deepseek-v4-pro

llm-deepseek:
  reasoningEffort: high             # off | low | high | max

# A local OpenAI-compatible server (mine is llama.cpp-based on a GPU rig).
llm-pi-ai:
  providers:
    local-rig:
      displayName: Local GPU rig
      apiKeyEnv: LOCAL_RIG_PLACEHOLDER_KEY    # a reference, not a value
      api: openai-completions
      baseURL: http://my-gpu-rig:1234/v1      # your server's address
      defaultContextWindow: 65536
      models:
        - id: unsloth/gemma-4-26B-A4B-it-qat-GGUF/gemma-4-26B-A4B-it-qat-UD-Q4_K_XL
          name: Gemma 4 26B-A4B (rig)

Dos detalles me costaron diez minutos cada uno para resolverlos:

  • apiKeyEnv es una referencia, nunca un valor literal. dsh lo resuelve a partir de .credentials.yaml o del entorno. Incluso un servidor local sin claves necesita alguna credencial referenciada, ya que el cliente compatible con OpenAI exige un token de autenticación. Por eso, coloque cualquier valor ficticio bajo ese nombre en .credentials.yaml.
  • El ID del proveedor (local-rig en el ejemplo) es permanente una vez que las sesiones lo referencian. Para cambiarlo, debe agregar un nuevo proveedor.

Dado que este archivo constituye toda la interfaz, “cambiar dsh al modelo local” se logra con solo dos líneas de edición; cualquier script u otro agente puede hacerlo. Yo lo utilizo para enviar tareas sencillas a un modelo local gratuito y los problemas complejos al V4-Pro, sin tener que modificar nada más.

Paso 4: llámalo desde tu propio software

El paquete oficial no incluye una interfaz de usuario por terminal (TUI). Hubo plugins TUI de terceros en npm, pero en agosto tenían apenas cuatro días de existencia y sus dependencias workspace:* estaban rotas. No voy a ejecutar un paquete no revisado con acceso al shell en un servidor familiar. Por eso, al integrar dsh en mi propia aplicación de chat, utilicé lo que el paquete oficial sí ofrece:

  • Ejecutar tareas sin interfaz con una lista fija de argumentos. Mi servidor inicia dsh --profile headless "…", pasando la tarea como un único elemento en argv y sin usar el shell; por lo tanto, una tarea que contenga ; rm -rf / no representa ningún peligro. Solo ejecuta una tarea a la vez y conserva un historial breve de las respuestas finales.
  • Cambiar de modelo reescribiendo agent-default-model en el archivo settings.yaml. No se necesita reiniciar nada.
  • Incrustar la interfaz web en un iframe si así lo deseas; no envía encabezados que bloqueen el uso de iframes.

La única regla que merece ser copiada: pon todo esto detrás del inicio de sesión de administrador de tu aplicación. Una tarea sin interfaz equivale a la ejecución arbitraria de código; por eso, trata la opción “ejecutar una tarea” exactamente igual que tratarías el uso del shell.

El benchmark: 5 tareas, 3 modelos, 15/15

No se trata de un estudio científico: son cinco tareas sencillas que realmente le asignaría a un agente de programación. Cada una se ejecuta en una carpeta nueva y se verifica mediante un script: ¿existe el archivo y se ejecuta? ¿Pasan las pruebas sin tocar el archivo de tests? ¿El cambio de nombre no deja referencias al nombre anterior? El tiempo total incluye todo el proceso, incluido un prompt del sistema de unos 7.500 tokens. Los recuentos de tokens provienen del propio registro de sesiones de dsh.

TareaV4-FlashV4-ProGemma-4-26B (local, rig)
Responder “PONG” (arranque + una llamada)✅ 2,1 s✅ 2,8 s✅ 13,2 s*
Escribir y ejecutar FizzBuzz✅ 5,3 s · 2 herramientas✅ 8,4 s · 2 herramientas✅ 4,9 s · 2 herramientas
Corregir 2 errores para que las pruebas unitarias pasen (sin tocar los tests)✅ 11,7 s · 8 herramientas✅ 15,8 s · 7 herramientas✅ 10,4 s · 8 herramientas
Resumir un código de 6 módulos (menos de 150 palabras)✅ 8,9 s · 9 herramientas✅ 10,9 s · 7 herramientas✅ 12,1 s · 7 herramientas
Cambiar el nombre de una función en 3 archivos + tests; verificar que todo funciona✅ 15,1 s · 14 herramientas✅ 18,2 s · 12 herramientas✅ 12,2 s · 11 herramientas
Tiempo total43 s56 s53 s
Tokens (entrada no encontrada / lectura desde caché / salida)42,6k / 136k / 4,5k41,4k / 107k / 3,2k40,5k / 237k / 5,6k
Costo según tarifas máximas (en horas fuera de pico es la mitad)≈ $0,027≈ $0,072$0 (solo consumo eléctrico)

*Primera llamada tras cargar el modelo en el rig; las tareas posteriores muestran velocidades más altas al estar el modelo ya “caliente”. Versión 0.1.0-rc.7, 18 de agosto de 2026. Precios según la página de precios de DeepSeek ese día: Flash $0,014 / $0,44 / $1,32 por millón de tokens (lectura desde caché / no encontrado / salida); Pro $0,044 / $1,32 / $3,96. El script del benchmark era provisional y ya no existe; por eso no puedo confirmar si el control de resumen contaba las palabras correctamente.

Lo que indica la tabla:

  • El almacenamiento en caché es clave para reducir costos. Cada tarea consume unos 7.500 tokens del prompt del sistema, pero tras el primer paso casi todo se recupera desde la caché, a un costo de apenas el 3% del precio por tokens no encontrados. Las tareas multietapa resultan baratas porque el entorno mantiene ese prefijo estable.
  • V4-Pro empleó menos llamadas a herramientas para obtener el mismo resultado (12 frente a 14 en la tarea de renombrar). En este conjunto de pruebas, Flash fue más rápido y costó aproximadamente un tercio, por lo que siguió siendo mi opción predeterminada.
  • El modelo local se desempeñó bien. Gemma-4-26B (un modelo mixture-of-experts con 4 mil millones de parámetros activos, cuantizado en Q4 y ejecutado mediante llama.cpp en dos RTX 5090) superó todas las pruebas. Leyó más contexto desde la caché (237 mil tokens frente a los 136 mil de Flash), pero su tiempo total fue competitivo. Es la primera vez que un modelo local resulta una opción viable para estas tareas, y no solo una curiosidad técnica. Claro que cinco tareas sencillas no dicen nada sobre un refactoring de 40 archivos.

Regla de decisión que adopté al final: Uso V4-Flash para tareas rutinarias y cualquier cosa automatizable; V4-Pro cuando se requieren menos pasos más precisos; y el modelo local cuando el trabajo es barato de repetir y no necesita conectarse a la red.

La prueba divertida: créame un juguete

También quería ver qué hacía con un encargo creativo abierto: “crea una versión interactiva en pixel art del logotipo de este sitio. Usa JavaScript puro, debe poder incrustarse en cualquier lugar; al pasar el ratón debe ocurrir algo físico, al hacer clic algo genial; sin dependencias, pruébalo tú mismo”. Esto es lo que generó; está en funcionamiento (más tarde compitió contra dos creaciones de Kimi en el concurso de widgets de pixel art):

Pasa el ratón sobre él y luego haz clic. Los píxeles se alejan del cursor y vuelven a su posición. Un clic hace que el logotipo se fragmente en píxeles que rebotan y regresan a su forma original. También funciona con pantallas táctiles, y respeta la preferencia prefers-reduced-motion.
Cuatro fotogramas del widget de pixel art: estado inicial, píxeles apartados alrededor del cursor con un resplandor azul, una nube de píxeles cian rebotando tras un clic, y los píxeles regresando a la forma del anillo y las dos Ls
Estado inicial → repulsión al pasar el ratón → fragmentación → reensamblaje; grabado mediante Chromium sin interfaz gráfica. 61 fps, cero errores en la consola; además, los píxeles sí vuelven a su posición inicial.

¿Cómo fue el proceso?

  • Intento 1 (V4-Flash): un bucle de 10 minutos y ningún archivo generado. El encargo permitía dibujar a mano o usar generación procedimental de bitmap. Optó por dibujar a mano un bitmap de 40×40 dentro de su razonamiento, pero entró en un bucle infinito: el registro de la sesión contenía cientos de líneas con ################ y ...., hasta que el tiempo límite lo interrumpió. Eso costó unos 2 centavos. Lección: nunca permitas que un modelo dibuje píxeles en su mente.
  • Intento 2 (V4-Flash, encargo modificado a “generar rasterizado a partir de geometría, sin bitmaps”): 25 minutos y todo entregado. Requirió 100 pasos del modelo, 201 llamadas a herramientas, 172 000 tokens de salida (123 000 de ellos correspondientes a razonamientos) y 16,3 millones de tokens leídos desde caché; un coste aproximado de 49 centavos a tarifas máximas. Escribió un archivo ll-pixel-logo.js de 399 líneas con una API global y opciones mediante atributos data-; además, una página de demostración, un README, una prueba unitaria en Node para el generador de rasterizado y, sin que se le pidiera, un script Playwright que tomaba capturas del demo en tres tamaños. Alcanzó el límite de 25 minutos mientras afinaba el README; por eso el código de salida indicó “timeout” aunque el trabajo ya estaba listo. Los códigos de salida pueden ser erróneos en ambos sentidos.
  • El diseño artístico: el anillo y las dos Ls inclinadas se perciben a primera vista como el logotipo, pero son más gruesos y “Z-like” que la marca original. Emplearía unos diez minutos afinando sus constantes de distorsión antes de usarlo realmente; no lo hice, así que lo que ven es tal cual salió.
  • Para incrustarlo aquí bastó una sola línea, ya que la política de seguridad del sitio es script-src 'self' y el widget no realiza peticiones de red. El encargo pedía eso, y el modelo cumplió.
  • Un coste adicional: dsh generó los archivos con permisos 0600. Mi sistema de despliegue copió esos permisos al servidor web, lo que provocó errores 403 en el sitio público hasta que ejecuté chmod 644. Siempre corrijan los permisos de cualquier archivo extraído de un entorno dsh.

Posibles problemas

  • Se trata de una versión preliminar para desarrolladores; el README así lo indica. Instalé 0.1.0-rc.7, tres días después del rc.6. Los perfiles, las claves de configuración y la estructura de los plugins pueden cambiar. Fije la versión en cualquier automatización que utilice y ejecute nuevamente una prueba básica tras cada actualización.
  • El modo headless no muestra ningún mensaje hasta que finaliza. No se envía nada a stdout, por lo que una tarea larga parece haberse quedado colgada. Lea el registro de la sesión (~/.dsh/sessions/…/session.jsonl.zstd, un archivo JSONL comprimido con zstd) o obsérvelo en la interfaz web. El código de salida 0 significa “la ejecución finalizó”, no “la tarea tuvo éxito”; por lo tanto, verifique el resultado.
  • En el modo headless no existe el flag --model. El modelo predeterminado se obtiene de settings.yaml; cámbielo allí (el archivo se recarga en caliente) o mediante la interfaz web.
  • Los servidores locales sin autenticación requieren un credencial de marcador de posición, y los ID de proveedores son permanentes. Consulte el Paso 3.
  • La interfaz web utiliza rutas absolutas (/assets/…, /api), por lo que no puede montarla bajo una ruta secundaria detrás de su propio proxy inverso sin realizar modificaciones. Será mejor incrustarla o asignarle un hostname independiente.
  • El idioma de la interfaz se determina según su navegador. El archivo index.html incluido indica lang="zh-CN", y lo primero que aparece es un cuadro de diálogo con un “Aviso de pruebas internas”. Haga clic en “Continuar”; a partir de ese momento, para mí todo se mostró en inglés.
  • La instalación ejecuta scripts postinstall (node-pty, koffi, protobufjs); npm emite advertencias al respecto. No detecté nada malicioso, pero se compila código nativo en su directorio de instalación. Este es otro motivo para utilizar un directorio privado en lugar del sistema por defecto.
  • Versión de Node: El rc.7 requiere Node 22.19+ o 24; las versiones LTS anteriores no pueden ejecutarlo. Consulte el README de la versión que vaya a instalar.

Nota histórica: dsh junto a Reasonix

En agosto ejecuté dsh junto con Reasonix, un agente de terminal desarrollado por terceros. La distinción era sencilla: Reasonix era una interfaz TUI que abría cuando quería interactuar directamente con el agente, mientras que dsh era el nombre que utilizaban mis otros programas para referirse a él. Dejé de usar Reasonix en mi configuración el 9 de septiembre de 2026; ahora, dsh es mi agente de programación principal. Si tienes que elegir entre ambos, la diferencia clave es que dsh cuenta con un modo headless en el que una sola orden genera una única respuesta y un código de salida único, lo cual facilita su uso en scripts; en cambio, una interfaz TUI presupone la presencia de un humano frente al teclado.

¿Qué significa esto para mí?

El modo headless es la forma ideal para un agente de programación al que otros softwarees pueden llamar: un comando, una respuesta, un código de salida y un registro que se puede auditar. El uso de YAML permite que el script que realiza la llamada decida qué modelo es el más adecuado para la tarea. Si ya ejecuta un servidor de modelos local, pruebe las mismas cinco tareas. Diez centavos en créditos de API y una carpeta temporal son todo lo que se necesita para comenzar.

Relacionado: DeepSeek Everywhere (integra DeepSeek con Claude Code y un stack de agentes), Kimi K3 como agente de programación (las mismas cinco tareas, ejecutadas nuevamente con dsh en septiembre), bench-llm y su sucesor CrucibleForge (herramientas para evaluar modelos locales de forma más rigurosa que lo hice yo aquí), y Reasonix (el agente terminal que utilicé antes de dsh; ahora ya no se usa).


← Más de IA y LLM Local