Instalación de Hermes AI en Windows: Desktop, PowerShell y WSL2

Hermes Agent es compatible con Windows 10 y Windows 11. Los usuarios pueden elegir entre tres escenarios de despliegue: ejecución nativa mediante PowerShell, la aplicación gráfica Hermes Desktop o un entorno WSL2. La elección de la opción adecuada depende de las herramientas de compilación que utilices, los requisitos del terminal y la arquitectura del sistema de archivos.

Elección de la ruta de instalación: entorno nativo frente a WSL2

Antes de comenzar la instalación, es fundamental determinar el contexto de ejecución de tus tareas:

• PowerShell nativo y Hermes Desktop comparten la misma estructura de datos: el código fuente y el entorno virtual se ubican en %LOCALAPPDATA%\hermes\hermes-agent, mientras que la configuración del usuario, el historial de sesiones y las habilidades (skills) se almacenan en %LOCALAPPDATA%\hermes. La interfaz gráfica de escritorio y la consola CLI son intercambiables y operan exactamente sobre el mismo estado.
• WSL2 aísla el entorno dentro de una máquina virtual Linux y almacena la configuración de forma independiente en ~/.hermes.

Ejemplos de selección de arquitectura

1. Proyectos centrados en Windows (PowerShell / .NET / utilidades del sistema): si automatizas flujos de trabajo en el host, ejecutas pasarelas en segundo plano para Telegram o Discord mediante el Programador de tareas de Windows y operas con archivos locales en NTFS, elige PowerShell nativo o Hermes Desktop.
2. Proyectos con stack de Linux (Docker, Make, scripts POSIX): si tu agente necesita compilar binarios de Linux, interactuar con sockets UNIX o gestionar sesiones a través del terminal integrado en el panel de control web (dashboard), despliega el agente en WSL2. En compilaciones nativas de Windows, el panel web admite métricas y configuración, pero la pestaña del terminal integrado /chat requiere una PTY de POSIX y solo está disponible en WSL2.

---

Opción 1: Instalación nativa mediante PowerShell

El instalador nativo no requiere privilegios de administrador y configura automáticamente el gestor de paquetes uv, un entorno de ejecución aislado de Python 3.11, Node.js para las herramientas del navegador y PortableGit. No es necesario instalar Python de manera global en tu sistema.

Abre una consola estándar de PowerShell y ejecuta:

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

El script añade %LOCALAPPDATA%\hermes\bin a la variable de entorno PATH del usuario actual. Una vez que finalice el script, cierra la ventana de la consola y abre una nueva sesión de terminal para aplicar el PATH actualizado. Para consultar los parámetros avanzados del script, revisa la guía oficial de Windows Native.

---

Opción 2: Cliente gráfico Hermes Desktop

Hermes Desktop proporciona una interfaz con ventanas que incluye una barra lateral de sesiones, un grafo visual de habilidades, soporte para pestañas y gestión de agentes en paralelo.

1. Descarga el instalador desde la página de documentación de Hermes Desktop.
2. Ejecuta el archivo de instalación descargado. En el primer inicio, la aplicación activará automáticamente el script de configuración de dependencias dentro de %LOCALAPPDATA%\hermes.

Si ya has configurado el agente mediante PowerShell, la aplicación de escritorio reconocerá de inmediato las claves de API existentes y las conversaciones guardadas.

---

Opción 3: Instalación dentro de WSL2

WSL2 proporciona un entorno estándar de Linux (sistema de archivos ext4, señales POSIX y soporte para PTY).

Paso 1. Preparar WSL2

En una consola de PowerShell con privilegios de administrador (Ejecutar como administrador), ejecuta:

wsl --install

Reinicia tu ordenador si el sistema lo solicita; a continuación, configura tu nombre de usuario y contraseña de Linux. Después, verifica la versión de tu distribución:

wsl --list --verbose

Asegúrate de que la columna VERSION muestre el valor 2 para la distribución seleccionada (Ubuntu por defecto).

Paso 2. Desplegar Hermes Agent

Abre tu terminal de Ubuntu y ejecuta el comando de instalación de acuerdo con la guía de inicio rápido de WSL2:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc

Importante: guarda tus repositorios de trabajo y archivos de proyecto dentro del sistema de archivos de Linux (por ejemplo, ~/projects/), en lugar de en una unidad montada de Windows (/mnt/c/). Las llamadas a archivos entre sistemas a través del protocolo 9P pueden provocar un rendimiento de E/S más lento y operaciones de git poco fluidas.

---

Verificación del entorno y primera ejecución

El diagnóstico y la ejecución deben realizarse en el terminal correspondiente a cada entorno: utiliza PowerShell para la instalación nativa y Hermes Desktop, y recurre al terminal de Ubuntu para WSL2.

Para la instalación nativa y Hermes Desktop, abre una nueva sesión de PowerShell y ejecuta:

Get-Command hermes
hermes --version
hermes doctor

Para la instalación en WSL2, abre el terminal de Ubuntu y realiza el diagnóstico:

command -v hermes
hermes --version
hermes doctor

El comando hermes doctor analiza la resolución correcta de las rutas para git, el motor de navegación Chromium y las dependencias auxiliares.

Antes de iniciar una sesión de chat, configura tu proveedor de modelos: si aún no está configurado, ejecuta primero hermes setup y selecciona tu proveedor (en PowerShell para el entorno nativo o en el terminal de Ubuntu para WSL2).

Una vez configurado, inicia una conversación estándar en el terminal correspondiente y pruébala con una tarea que no requiera escritura de archivos; ten en cuenta que hermes chat no aplica aislamiento de permisos:

hermes chat

Como primera petición, envía una instrucción que no requiera escritura en disco (por ejemplo, solicitar la explicación de un concepto de arquitectura). El resultado esperado es una inicialización correcta del proveedor de modelos configurado y una salida de texto en streaming fluida y sin errores de codificación.

Para consultar los detalles de configuración opcional de modelos, revisa la documentación de BetterToken.

---

Solución de problemas frecuentes

Síntoma observado	Causa	Solución
hermes: The term 'hermes' is not recognized	La sesión activa de la consola no ha recargado el User PATH actualizado.	Reinicia la ventana de PowerShell o invoca el archivo binario directamente: & "$env:LOCALAPPDATA\hermes\bin\hermes.exe".
La pestaña /chat en el panel web muestra un banner de error	Windows nativo carece del mecanismo de sistema POSIX PTY.	La gestión de sesiones y tareas funciona de forma nativa, pero para el terminal web en /chat, ejecuta el agente dentro de WSL2.
WinError 193: %1 is not a valid Win32 application	Intento de invocar un script directamente sin el contenedor .cmd.	En Windows, ejecuta las herramientas de Node y npm indicando explícitamente su extensión (por ejemplo, npx.cmd).
Signos de interrogación (?) en lugar de caracteres Unicode en la CLI	Host de consola desactualizado sin soporte para CP 65001.	Utiliza Windows Terminal. Asegúrate de que la variable de entorno HERMES_DISABLE_WINDOWS_UTF8 no esté establecida en 1.
Alta latencia al ejecutar git status dentro de WSL2	El directorio de trabajo del proyecto se encuentra en la ruta /mnt/c/....	Traslada el repositorio de trabajo al directorio personal de la distribución Linux (~/code/...) para aprovechar el rendimiento nativo de ext4.