DeepSeek Harness: tu propio proveedor a través de JoinGonka Gateway

El harness es todo lo que rodea al modelo en el trabajo agéntico: el ciclo «petición → llamada a herramienta → resultado → siguiente paso», las herramientas para archivos y terminal, los permisos y confirmaciones, el registro de sesión, la compresión de contexto. DeepSeek Harness lo arma a partir de plugins: la arquitectura «everything is a plugin» se apoya en el framework Cordis, y cualquier nodo —desde una herramienta hasta el adaptador de modelo— se reemplaza sin tocar el núcleo. El código es abierto bajo licencia MIT.

No hace falta instalar nada: basta con Node.js (las líneas 22 desde 22.19 o 24 y posteriores):

npx @deepseek-ai/dsh web

El comando levanta una Web UI en http://127.0.0.1:3080 y la abre en el navegador; al ejecutarse por SSH, la dirección solo se imprime en la terminal. El flag --no-open inicia el servidor sin navegador y --port cambia el puerto. El directorio desde el que se lanza dsh pasa a ser el de trabajo por defecto, pero la interfaz solo iniciará sesión tras elegir explícitamente un workspace.

La capa de modelos consta de dos adaptadores. El directo va a la API oficial del proveedor. El multiproveedor —dsh-llm-pi-ai— se apoya en la librería pi-ai, la misma que sustenta al agente de terminal Pi; a través de él se conectan tanto los proveedores integrados del catálogo como cualquier endpoint propio. Por eso los nombres de los campos en la configuración —api, contextWindow, maxTokens— coinciden con los que ya conoces de Pi.

Sobre la madurez. El README del proyecto arranca con una advertencia: developer preview, iteraciones rápidas, cambios que rompen. Un documento aparte, SAFETY.md, aclara que no se hizo auditoría de seguridad y que el agente ejecuta comandos generados por el modelo. La conclusión práctica es simple: ejecuta dsh en un contenedor, una máquina virtual o bajo una cuenta aparte, y mantén copias de seguridad de todo lo que pueda alcanzar.

Paso 1: la clave. Regístrate en gate.joingonka.ai/register: tras confirmar tu dirección recibirás 3M tokens gratuitos en tu cuenta. En el panel, abre la sección «Claves API» y crea una clave con el prefijo jg-. Conviene crear una clave aparte para el harness: así su tráfico aparecerá en las estadísticas en una línea propia.

Paso 2: la primera pantalla. Tras el aviso de estado de prueba (botón Continue), dsh te pedirá que introduzcas la clave de la API oficial («Add an API key to get started»). No es obligatoria: pulsa Configure later.

Paso 3: el proveedor. Abre Settings → Models y elige Add a custom provider. Campos del formulario:

Paso 4: los modelos. En el bloque Models pulsa Fetch available models: dsh pedirá la lista al gateway y abrirá la ventana «Choose models to add». En nuestra prueba aparecieron los tres modelos de la red —MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 y zai-org/GLM-5.3-Flash— y tras Add selected el harness asignó a cada uno la ventana de contexto y el límite de respuesta según los datos del gateway. Solo queda pulsar Create provider.

Paso 5: elegir el modelo. Cierra los ajustes, pulsa Choose workspace y añade el directorio del proyecto. Los modelos del nuevo proveedor aparecerán en el selector; el elegido pasa a ser el modelo predeterminado para las nuevas sesiones.

dsh guarda la clave aparte de los ajustes: en el archivo ~/.dsh/.credentials.yaml, con permisos solo para el propietario. En settings.yaml solo queda el nombre de la referencia a ella: en nuestra prueba JOINGONKA_API_KEY, según el identificador del proveedor.

Qué protocolo elegir. El gateway habla los tres; lo que cambia es la dirección base y algunas comodidades adicionales:

Un proveedor en dsh habla un solo protocolo, así que un segundo protocolo requiere un segundo proveedor con otro Provider ID. Para el trabajo diario basta con la primera opción; en nuestra prueba el bucle agéntico con llamadas a herramientas funcionó con las tres.

El formulario Models escribe en un documento YAML normal — $DSH_HOME/settings.yaml, por defecto ~/.dsh/settings.yaml. Se puede editar directamente: el botón Open configuration file en la cabecera de ajustes abre el archivo, y los adaptadores lo releen en la siguiente petición — no hace falta reiniciar. La versión completa para la red Gonka:

# ~/.dsh/settings.yaml
llm-pi-ai:
  providers:
    joingonka:
      displayName: JoinGonka Gateway
      apiKeyEnv: JOINGONKA_API_KEY
      api: openai-completions
      baseURL: https://gate.joingonka.ai/v1
      models:
        - id: deepseek-ai/DeepSeek-V4-Flash-0731
          name: DeepSeek V4 Flash
          contextWindow: 380000
          maxTokens: 32768
        - id: zai-org/GLM-5.3-Flash
          name: GLM-5.3 Flash
          contextWindow: 390000
          maxTokens: 8192
          reasoningEfforts:
            off: low
            high: high
        - id: MiniMaxAI/MiniMax-M2.7
          name: MiniMax M2.7
          contextWindow: 200000
          maxTokens: 8192
agent-default-model:
  provider: joingonka
  model: deepseek-ai/DeepSeek-V4-Flash-0731

Lo importante aquí:

• apiKeyEnv — no es la clave, sino el nombre de la referencia a ella. dsh busca el valor en este orden: la variable de entorno en el momento del arranque, luego .credentials.yaml (donde escribe el formulario), luego .env en el directorio de ejecución, luego ~/.dsh/.env. Si configuras el harness sin navegador, basta con una línea JOINGONKA_API_KEY=jg-your-key en ~/.dsh/.env con permisos 600. Una variable exportada después del arranque no la verá un proceso ya en marcha.
• Define contextWindow y maxTokens de forma explícita. A un modelo del que dsh no sabe nada le asigna 262 144 y 32 768 tokens — lo que no se corresponde con los límites reales. El maxTokens definido se convierte además en el límite de respuesta por defecto para cada petición.
• reasoningEfforts — los niveles de razonamiento para el menú Effort. Un modelo añadido a mano no tiene niveles, y el menú no aparece para él. En GLM-5.3 Flash el interruptor es binario: el valor low desactiva el razonamiento, cualquier otro lo deja completo. Por eso al nivel off se le asigna low, y high se pasa tal cual. En nuestra prueba con off no hubo bloques de razonamiento en absoluto, con high volvieron.
• agent-default-model — el modelo para los agentes nuevos, incluido el modo headless. Lo mismo hace la selección de modelo en la interfaz; aquí también se puede añadir reasoningEffort.

Los interruptores compat que la documentación de dsh recomienda para gateways estrictos (supportsDeveloperRole: false, maxTokensField: max_tokens) aquí no harán falta: JoinGonka Gateway acepta tanto el rol developer como el campo max_completion_tokens.

El instalador npx @joingonka/setup no configura este harness: toda la conexión se reduce al formulario de la sección anterior o al fragmento YAML de arriba.

La forma más rápida de comprobar la conexión es una ejecución única desde el directorio con el código. Coloca cerca un archivo pequeño con un error evidente y pídele que lo encuentre:

cd /path/to/project
npx @deepseek-ai/dsh --profile headless "Read calc.py and tell me in one sentence whether it has a bug."

La respuesta final se imprime en stdout, y el razonamiento va a stderr con la marca dsh: reasoning:. El agente debe llamar por su cuenta a la herramienta de lectura de archivos y responder con fundamento: en nuestra ejecución, cada uno de los tres modelos de la red señaló la línea errónea. Eso significa que el ciclo completo «petición → llamada a la herramienta → resultado → respuesta» se arma correctamente a través de la pasarela.

La segunda mitad de la comprobación está del lado de la pasarela. En el panel abre «Uso»: ahí se ven las peticiones por horas y por días, el desglose por modelos y por claves. Si apareció una fila con la clave del arnés y una marca de tiempo reciente de la última petición, el tráfico realmente está pasando por la pasarela.

Si algo salió mal, el diagnóstico normalmente se lee directamente en el mensaje:

El precio es el mismo para todos los modelos de la red, por lo que la elección depende del comportamiento, no del presupuesto. A continuación se presentan los límites y cómo se comportaron los modelos en nuestra ejecución dsh en la misma tarea: leer un archivo y encontrar un error en él.

La recomendación predeterminada es DeepSeek V4 Flash: el trabajo de los agentes alcanza rápidamente el límite del volumen de contexto y la longitud de edición, y aquí hay un margen para ambos parámetros. Cuando la tarea requiera pensar en una lógica compleja, cambie a GLM-5.3 Flash y mantenga el nivel de razonamiento en high; para ediciones rápidas, el mismo proveedor lo ofrece con el nivel off. MiniMax M2.7 es una opción equilibrada para tareas cortas, cuando el proceso de razonamiento visible no interfiere. El modelo se cambia en el selector de la interfaz o mediante la línea model en el bloque agent-default-model.

La composición de la red se determina mediante la votación de los participantes y cambia con el tiempo; la lista actual junto con los límites siempre se obtiene mediante GET https://gate.joingonka.ai/v1/models, que es el mismo comando que utiliza el botón Fetch available models.

Las herramientas de agentes consumen tokens de manera diferente a un chat: por cada frase que envías, el harness añade un prompt del sistema y las descripciones de todas las herramientas, y luego lleva a cabo un diálogo de múltiples pasos con el modelo. En nuestra ejecución, la tarea "leer un archivo y encontrar el error" tomó de dos a tres pasos y entre 14 y 22 mil tokens, siendo casi todo ello entrada: cerca de siete mil tokens se consumen en cada paso incluso antes de tu pregunta. Es un precio normal a pagar por la autonomía, y es precisamente por eso que el precio por token es decisivo.

A través de JoinGonka Gateway, los tokens cuestan $0.0069 por millón en la entrada y $0.021 por millón en la salida; el precio es el mismo para todos los modelos de la red y se carga en esta página desde una fuente en tiempo real. Orden de magnitud de precios para septiembre de 2026:

El pago se realiza según el consumo real, sin suscripción y sin cuotas por número de solicitudes; el saldo y el consumo diario se pueden ver en el panel de control.

Versión. Mientras el proyecto esté en estado de developer preview, después de cada actualización verifica que el proveedor esté activo y, para garantizar la reproducibilidad, fija la versión directamente en el comando: npx @deepseek-ai/[email protected] web.

Permisos. Las nuevas sesiones funcionan por defecto en modo Workspace Write: escritura dentro del directorio de trabajo; la interfaz solicita confirmación para operaciones que excedan la política. El modo se puede cambiar en Settings → General.

Reintentos. Ante un error de red puntual, dsh repite la solicitud automáticamente —hasta cinco veces según la documentación—, por lo que un breve pico de carga en la red suele pasar desapercibido.

Privacidad. La puerta de enlace (gateway) no almacena el contenido de los prompts ni de las respuestas: en las estadísticas solo quedan los agregados de consumo. El agente lee los archivos del proyecto localmente, en tu propia máquina.

Si necesitas trabajar con imágenes —capturas de pantalla de la interfaz, diagramas en fotos—, inicia un segundo proveedor con un modelo capaz de visión: dsh mantiene múltiples proveedores simultáneamente, y los modelos de la red Gonka son textuales.

DeepSeek Harness no es el único agente que publica el laboratorio desarrollador de modelos: Z.ai, autores de GLM, tienen el entorno ZCode, y MiniMax tiene el terminal MiniMax Code. Ambos se conectan a la misma puerta de enlace con la misma clave.