# nan-harness — documentación Documentación para ejecutar agentes de código compatibles con NaN mediante nan-harness. - HTML: https://nan-harness.davidlms.com/docs.html - Markdown: https://nan-harness.davidlms.com/es/docs.md Ejecuta con [NaN](https://nan.builders/) los agentes de código que ya usas, mediante nan-harness. Usa `nanh ` para el uso diario y `nanh config ` solo para la configuración nativa avanzada. `nanh` es el alias corto de `nan-harness`. ## INSTALACIÓN Ejecuta esto en macOS o Linux: ``` curl --proto '=https' --tlsv1.2 -m 30 -fsSL https://github.com/DavidLMS/nan-harness/releases/latest/download/install.sh | sh ``` En Windows, desde PowerShell: ``` irm https://github.com/DavidLMS/nan-harness/releases/latest/download/install.ps1 | iex ``` Si te lo pide, abre una terminal nueva. Después comprueba la instalación: ``` nanh --version ``` El instalador proporciona `nan-harness` y `nanh`. Hay versiones para macOS, Linux y Windows. Para compilarlo desde el código fuente, consulta el [repositorio](https://github.com/DavidLMS/nan-harness). ## PRIMER USO Ve a tu proyecto y lanza el agente que ya usas: ``` nanh claude ``` Si no has definido `NAN_API_KEY`, nan-harness te pide tu API key de NaN la primera vez que la necesita. La verifica y la guarda. Después, usa el agente como siempre. Para elegir un modelo al arrancar, usa `--model`. Si el agente lo permite, también puedes usar su selector nativo de modelos: ``` nanh codex --model qwen3.6 nanh opencode --model deepseek-v4-flash ``` Pasa los argumentos del agente después de `--`; nan-harness los reenvía sin modificarlos: ``` nanh codex --model qwen3.6 -- --full-auto nanh claude -- --resume ``` ### Tu clave > Si ya tienes `NAN_API_KEY` en tu entorno, este apartado no va contigo. Esa clave manda sobre cualquier otra: nan-harness no te pedirá ninguna, no guarda nada en disco y no necesitas hacer login. Si no la tienes, nan-harness la guarda donde tu sistema guarda las contraseñas: Llavero en macOS, Administrador de credenciales en Windows, Secret Service en Linux. Si no hay ninguno disponible, usa un archivo privado y te avisa. | Comando | Para qué sirve | | --- | --- | | nanh auth login | Introducir una clave, o cambiar la que tienes. | | nanh auth status | Ver qué clave se está usando y dónde está guardada. | | nanh auth logout | Borrar la clave guardada. | La variable de entorno es útil en servidores y en CI. `nanh auth status` muestra qué credencial está activa: ``` export NAN_API_KEY="" ``` > Mantén tu clave privada. La variable de entorno nunca se copia a la configuración de un harness. ## HARNESSES `nanh ` es la forma recomendada para todos los harness compatibles. nan-harness comprueba la versión instalada, consulta el catálogo actual de NaN, prepara los bridges necesarios y supervisa el proceso sin cambiar ajustes persistentes del proveedor. `nanh config ` es una opción avanzada para los harnesses que admiten configuración nativa directa. | Comando recomendado | Harness | Configuración nativa | | --- | --- | --- | | nanh aider | [Aider](https://aider.chat/) | opcional | | nanh cline | [Cline](https://cline.bot/) | opcional | | nanh goose | [Goose](https://github.com/block/goose) | opcional | | nanh claude | [Claude Code](https://www.anthropic.com/claude-code) | no disponible | | nanh codex | [Codex](https://openai.com/codex/) | no disponible | | nanh opencode | [OpenCode](https://opencode.ai/) | opcional | | nanh qwen | [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/users/overview) | opcional | | nanh pi | [Pi](https://pi.dev/) | opcional | | nanh kimi | [Kimi Code](https://www.kimi.com/code) | opcional | | nanh openclaw | [OpenClaw](https://openclaw.ai/) | opcional | | nanh hermes | [Hermes Agent](https://hermes-agent.nousresearch.com/) | opcional | | nanh omp | [Oh My Pi](https://omp.sh/) | opcional | | nanh prime-agent | [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) | opcional | | nanh dsh | [DeepSeek Harness](https://deepseek.com/harness/en/) | opcional | | nanh fx | [fx](https://fx.sh/) | no disponible | ### Recomendado: ejecutar con nan-harness Para el uso diario, ejecuta `nanh `. Comprueba la versión instalada, descubre tus modelos actuales de NaN, utiliza la fuente de credenciales activa, prepara los bridges necesarios y supervisa el proceso. Si falta el harness, puede ofrecerte instalarlo. ``` nanh opencode ``` ### Avanzado: configuración nativa Usa `nanh config ` solo cuando otra herramienta o integración necesite arrancar un harness compatible mediante su ejecutable habitual. La configuración nativa escribe ajustes persistentes del proveedor. El posterior arranque se hace directamente con el harness, así que nan-harness deja de gestionar ese proceso. Este comando solo configura el harness; después, arráncalo con su ejecutable habitual: ``` nanh config opencode opencode ``` Claude Code, Codex y fx necesitan que nan-harness siga ejecutándose porque su conexión con NaN depende de un bridge o gateway local. Por eso no se pueden preparar para uso independiente con `nanh config`. La configuración nativa usa la API key guardada por `nanh auth login`; una clave que solo está en el entorno nunca se copia a otra aplicación. Usa `--status` para revisarla y `--refresh` después de cambiar la clave guardada o el catálogo de modelos. `--remove` elimina lo que añadió nan-harness y restaura los ajustes anteriores cuando puede hacerlo de forma segura. ## APPS DE ESCRITORIO (EXPERIMENTAL) Estas integraciones son experimentales. Las cinco apps se han probado en macOS. Las demás combinaciones de plataforma están cubiertas por pruebas automatizadas de compatibilidad. | Comando | App | Disponible en | | --- | --- | --- | | nanh zed | [Zed](https://zed.dev/) | macOS, Windows, Linux | | nanh chatgpt-desktop | [ChatGPT](https://openai.com/chatgpt/desktop/) | macOS, Windows, Linux (preview) | | nanh claude-desktop | [Claude](https://claude.ai/download) | macOS, Windows, Linux (beta) | | nanh hermes-desktop | [Hermes](https://hermes-agent.nousresearch.com/) | macOS, Windows, Linux | | nanh pen | [Pen](https://www.pen.dev/) | macOS, Windows, Linux | ### Qué pasa al lanzar una nan-harness prepara una conexión temporal con NaN, lanza la app y la limpia cuando se cierra. No sustituye la app ni te desconecta; tu login, historial y ajustes permanecen intactos. ChatGPT y Hermes usan un perfil separado. Claude, Pen y Zed restauran la configuración anterior al cerrarse. Pen y Zed reciben todos los modelos de texto disponibles en tu cuenta de NaN mediante un gateway local privado, que también proporciona el resumen final de tokens. ### Si un arranque se interrumpe Cierra la app y vuelve a lanzar el mismo comando con `--restore`. nan-harness restaura el estado registrado durante el arranque interrumpido. ### Ejecuta Hermes o Pen directamente Hermes Desktop y Pen también admiten configuración para uso directo. Después, abre la app normalmente; nan-harness deja de intervenir. Los resúmenes de uso solo funcionan al lanzar mediante `nanh`. Pen debe reiniciarse por completo para recargar un catálogo modificado: ``` nanh config hermes-desktop hermes desktop nanh config pen abre Pen normalmente ``` > Si te interesan, pruébalas y cuéntanoslo. Tu experiencia como usuario —qué funciona, qué falla, qué echas en falta— es la mejor forma de ayudar a que estas integraciones se consoliden. ## BÚSQUEDA WEB CON NAN Muchos agentes de código pueden buscar en la web. Cuando nan-harness lanza uno, comprueba si el agente ya tiene un proveedor de búsqueda reconocido —en el agente, en el proyecto o en su configuración local de búsqueda—. Solo si no encuentra ninguno añade la búsqueda web de NaN como respaldo. Tus ajustes de búsqueda existentes no se tocan. El agente lo ve como una herramienta más de búsqueda web, así que pídeselo así: "busca en la web las últimas novedades de Rust", "mira cómo ha resuelto este error otra gente" o "encuentra la documentación oficial de esa librería". La petición pasa por tu cuenta de NaN como cualquier otra llamada al modelo. ### Cambiar la selección | Flag | Qué hace | | --- | --- | | (por defecto) | Automático: añade la búsqueda de NaN solo si no hay otro proveedor reconocido configurado. | | --no-search | No añade nunca la búsqueda web de NaN en este arranque, aunque no haya otro proveedor. | | --force-search | Añade la búsqueda web de NaN aunque exista otro proveedor. | ``` nanh claude --no-search nanh cline --force-search ``` Para Pi y Prime Agent, la comprobación mira también el inventario de herramientas en tiempo de ejecución una vez cargadas las extensiones de paquetes instalados. Cualquier paquete que exponga una herramienta llamada `web_search` desactiva el respaldo de NaN por sí solo; `--force-search` da precedencia a la herramienta de NaN en su lugar. ### En la configuración nativa `nanh config ` aplica la misma política. Un `--force-search` o `--no-search` elegido queda guardado en el recibo de configuración y se conserva en posteriores `--refresh` a menos que pases un flag nuevo. `nanh config --status` muestra la política guardada y si el respaldo de NaN está activo. Para Pi, Oh My Pi y Prime Agent, la configuración nativa instala una extensión consciente del runtime en lugar de una entrada MCP de búsqueda; actualizar una configuración antigua la migra automáticamente y conserva los servidores MCP ajenos. Aider admite configuración nativa de modelos, pero no el respaldo de búsqueda web de NaN. ## OPCIONES ### Opciones del arranque recomendado | Opción | Qué hace | | --- | --- | | --model | Qué modelo usar esta vez. | | --allow-untested | Permite una versión de un harness de línea de comandos que no se puede leer, o una versión de una app de escritorio más nueva que la última probada en vivo. | | --allow-unsupported | Ejecuta una versión anterior al mínimo compatible. | ### Comandos avanzados de configuración nativa | Comando | Qué hace | | --- | --- | | nanh config | Escribe una configuración nativa reversible de NaN sin lanzar el harness. | | nanh config --status | Comprueba si su configuración gestionada está actualizada. | | nanh config --refresh | Actualiza la clave copiada, el catálogo de modelos y los valores gestionados. | | nanh config --remove | Quita la configuración gestionada y restaura valores anteriores seguros. | ### Otros comandos | Comando | Qué hace | | --- | --- | | nanh doctor | Revisa todo y te dice cómo está. | | nanh doctor | Revisa un harness en detalle. | | nanh auth login | Guarda tu clave de NaN. | | nanh auth status | Te dice qué clave se está usando. | | nanh auth logout | Borra la clave guardada y permite retirar configuraciones que contienen una copia. | | nanh config --status | Muestra todas las configuraciones nativas gestionadas por nan-harness. | | nanh config --refresh-all | Actualiza todas las configuraciones nativas gestionadas. | | nanh config --remove-all | Elimina todas las configuraciones nativas gestionadas. | | nanh update | Actualiza nan-harness a la última versión. | | nanh telemetry on\|off | Activa o desactiva la telemetría anónima. | | nanh uninstall | Elimina nan-harness y todo lo que dejó puesto. | | nanh --help | La lista completa, en tu terminal. | ## AYUDA Y PRIVACIDAD ### Solución de problemas Ejecuta `nanh doctor` para comprobar la conexión, los modelos disponibles, los harness instalados y las versiones antiguas. ``` nanh doctor ``` Ese informe se puede compartir: no incluye claves, rutas, prompts ni respuestas del modelo. El informe de un solo harness incluye la ruta del ejecutable, así que revísalo antes de compartirlo. ``` nanh doctor claude ``` ### Avisos de versión Cada versión de nan-harness se prueba con versiones concretas de cada harness. Si la tuya es más nueva que la última probada, nan-harness avisa y continúa. Las versiones anteriores al mínimo requieren `--allow-unsupported`; si no se puede leer el número de versión, requiere `--allow-untested`. ### Telemetría Apagada mientras no la enciendas. Si la activas, nan-harness puede enviar informes sanitizados de fallos de la CLI y los bridges, además de un evento mínimo de uso con un identificador aleatorio de instalación, su versión, el harness, la operación, el transporte, la familia del sistema operativo, la arquitectura y el entorno de destino. Nunca envía prompts, respuestas del modelo, argumentos, rutas, credenciales, nombres de usuario ni nombres de equipo. Un diagnóstico específico de un modelo puede incluir su identificador de NaN. Como en cualquier petición HTTPS, la infraestructura receptora puede observar los metadatos de red habituales. ``` nanh telemetry on nanh telemetry off ``` Nos sirve para saber qué harnesses necesitan atención. Al apagarla se detienen los eventos de uso y el envío automático de errores. Un error interactivo aún puede ofrecer un informe anónimo de un solo uso. ### Desinstalar Pide confirmación, deshace todas las configuraciones que dejó en tus agentes, borra tu clave guardada y se quita de en medio. Si cambiaste a mano alguna de esas configuraciones, se detiene en vez de pisarte el trabajo. ``` nanh uninstall ```