Instalar el agente

El agente de NORA es el programa que se instala en cada máquina donde se ejecutan los robots. Se conecta al servidor de NORA con la clave de máquina, envía latidos (heartbeat) para mantenerse en línea, recibe trabajos y ejecuta los procesos automatizados.

NORA solo es compatible con Windows y macOS.

Requisitos

• Máquina registrada en NORA. Antes de instalar el agente, crea la máquina en el panel. Al crearla se genera una clave de máquina con prefijo nora_mk_... que el agente necesita para autenticarse.
• Sistema operativo: Windows 10 o superior, o macOS 12 o superior.
• Conectividad HTTPS saliente hacia el servidor de NORA. En producción la URL de la API es https://nora-api.valisoftconsulting.com/api/v1.

HTTPS obligatorio

El agente exige https:// en NORA_API_URL. Solo se admite http:// cuando el host es localhost, 127.0.0.1 o ::1 (entornos de desarrollo). Cualquier otra URL en texto plano hace que el agente termine con error.

Cómo se conecta el agente a la máquina

El agente lee su configuración de un archivo .env ubicado junto al ejecutable (o de variables de entorno):

Variable	Descripción	Valor por defecto
NORA_API_URL	URL base de la API de NORA, con el prefijo /api/v1.	http://localhost:8000/api/v1
NORA_MACHINE_KEY	Clave de máquina (nora_mk_...). Obligatoria.	— (sin ella, el agente no arranca)

Con esos datos, el agente se autentica contra POST /api/v1/agent/auth enviando la clave de máquina. El servidor devuelve un token de acceso (JWT) que el agente usa en el resto de llamadas. A partir de ahí:

1. Envía un heartbeat cada 30 segundos a POST /api/v1/agent/heartbeat con información del sistema, para figurar en línea en el panel.
2. Sondea trabajos pendientes cada 5 segundos.
3. Refresca la configuración de máquina (resolución, modo de sesión, auto-login) desde GET /api/v1/agent/machine-config cada 60 segundos, de modo que los cambios hechos en el panel se aplican sin reinstalar el agente.

sequenceDiagram
    participant A as Agente
    participant S as NORA (API)
    A->>S: POST /agent/auth { machine_key }
    S-->>A: { access_token, machine_id, tenant_id }
    loop cada 30 s
        A->>S: POST /agent/heartbeat
    end
    loop cada 5 s
        A->>S: GET /agent/jobs/next
        S-->>A: trabajo o vacío
    end

El archivo .env se guarda con permisos restringidos al usuario actual (icacls en Windows, chmod 600 en macOS), porque contiene la clave de máquina.

Instalación en Windows

1. Descarga el agente desde el panel de NORA: entra a Machines, selecciona la máquina y descarga el paquete .zip para Windows. Incluye nora-agent.exe y un .env preconfigurado con NORA_API_URL y NORA_MACHINE_KEY.
2. Extrae el .zip en cualquier carpeta (por ejemplo, Descargas), manteniendo el .exe y el .env juntos.
3. Haz doble clic en nora-agent.exe. Como el binario no está firmado, Windows SmartScreen puede avisar: haz clic en Más información y luego en Ejecutar de todas formas.
4. El instalador integrado se ejecuta automáticamente y:
   • Copia el agente y el .env a C:\Users\<usuario>\.nora-agent\.
   • Registra una Tarea programada llamada NORA Agent (se inicia al iniciar sesión, con 30 s de retraso, y se reinicia si el proceso falla).
   • Registra una segunda tarea NORA Session Manager que se ejecuta como SYSTEM y gestiona la sesión interactiva (ver más abajo).
   • Crea un acceso directo NORA Agent en el menú Inicio.
   • Inicia el agente en segundo plano y muestra un mensaje de confirmación.

Reinstalar o actualizar

Volver a ejecutar nora-agent.exe hace una reinstalación limpia: detiene el agente anterior, elimina los artefactos previos conservando solo el .env, y vuelve a instalar. No necesitas desinstalar a mano.

Instalación en macOS

1. Descarga el paquete .zip para macOS desde el panel (Machines > máquina > descargar). Incluye el binario nora-agent-macos y el .env preconfigurado.

2. Extrae el .zip.

3. Ejecuta el binario desde la Terminal:

   chmod +x nora-agent-macos
   ./nora-agent-macos

4. Si Gatekeeper bloquea la ejecución, ve a Ajustes del Sistema > Privacidad y Seguridad y pulsa Abrir de todas formas. Como alternativa, quita la cuarentena desde la Terminal:

   xattr -cr ~/.nora-agent/nora-agent-macos

5. El instalador integrado:

   • Copia el agente y el .env a ~/.nora-agent/.
   • Crea un LaunchAgent en ~/Library/LaunchAgents/com.nora.agent.plist con RunAtLoad y KeepAlive, y lo carga con launchctl.
   • Escribe los logs en ~/Library/Logs/nora-agent.log.
   • Crea ~/Applications/NORA Agent.app para encontrarlo en Spotlight.

Arranque automático al reiniciar

El agente se ejecuta como servicio de usuario (no de sistema) porque necesita una sesión de escritorio para automatizar aplicaciones. Por eso arranca al iniciar sesión un usuario.

Sistema	Mecanismo	Arranca tras reinicio	Se reinicia si falla
Windows	Tarea programada NORA Agent (disparador al iniciar sesión, +30 s)	Al iniciar sesión	Sí (RestartOnFailure: cada 1 min, hasta 999 veces)
macOS	LaunchAgent com.nora.agent (RunAtLoad + KeepAlive)	Al iniciar sesión	Sí (launchd lo relanza)

Si tras reiniciar la red tarda en subir, el agente reintenta conectarse sin rendirse.

Modo desatendido con auto-login

En equipos que se reinician sin que nadie inicie sesión, hay que configurar el inicio de sesión automático para que el sistema entre solo a la sesión y dispare el agente.

Windows (automático desde el panel)

1. En el panel de NORA, edita la máquina y define el usuario y la contraseña de Windows del equipo.
2. El agente lee esa configuración desde GET /api/v1/agent/machine-config y aplica el auto-login automáticamente. La contraseña se guarda cifrada mediante LSA Secrets (no en texto plano en el registro).
3. Reinicia el equipo para validar: Windows inicia sesión solo, la tarea dispara y el agente conecta.

Para desactivarlo, quita el usuario de Windows de la máquina en el panel; el agente eliminará el auto-login en el siguiente refresco de configuración.

macOS (manual, una sola vez)

macOS no permite automatizar el auto-login de forma segura, así que se habilita a mano:

1. Ve a Ajustes del Sistema > Usuarios y grupos > Inicio de sesión automático y elige la cuenta del equipo.
2. Puede requerir desactivar FileVault, que bloquea el auto-login.
3. Reinicia para validar: el Mac entra solo a la sesión y el LaunchAgent arranca el agente.

Sesión RDP y resolución de pantalla

En equipos Windows desatendidos, la sesión de consola física suele quedar atascada en una resolución baja (800x600 con el adaptador de pantalla básico). Para evitarlo, NORA usa un modelo de sesión RDP de loopback (similar al de UiPath):

• La tarea NORA Session Manager se ejecuta como SYSTEM y, cuando hay un trabajo, establece una sesión interactiva a la resolución configurada mediante una conexión RDP local (FreeRDP). El robot se ejecuta dentro de esa sesión.
• La resolución, la profundidad de color, la escala (DPI) y el modo de sesión se definen en el panel y se aplican vía machine-config. Los valores se publican en las variables NORA_DISPLAY_RESOLUTION (por defecto 1920x1080), NORA_DISPLAY_DEPTH (32) y NORA_DISPLAY_SCALE (100).
• El modo de sesión puede ser rdp (sesión RDP de loopback, resolución flexible — predeterminado) o console (consola física).

Cuando ya hay una sesión RDP activa (humana o de loopback), el agente no fuerza la resolución de la pantalla, porque esa sesión ya lleva la resolución correcta. El ajuste directo de resolución solo se intenta en una consola headless sin RDP y en modo desatendido.

Nota

El modelo de sesión RDP de loopback aplica a Windows. En macOS, el agente usa la sesión de escritorio del usuario que inició sesión (atendido o por auto-login).

Verificar la versión y el estado

La versión actual del agente es 0.7.6 y se muestra en la salida del agente al arrancar, con el formato NORA Agent v0.7.6.

Para confirmar que el agente está activo:

• Panel de NORA: la máquina debe aparecer en línea unos 30 segundos después de instalar el agente.

• Windows:

  schtasks /Query /TN "NORA Agent" /V

  El estado debe ser Ready o Running.

• macOS:

  launchctl list | grep nora

  Debe aparecer com.nora.agent. Para ver el log en vivo:

  tail -f ~/Library/Logs/nora-agent.log

Solución de problemas

• La máquina no aparece en línea. Verifica que NORA_MACHINE_KEY y NORA_API_URL del .env (junto al ejecutable) sean correctos y que el equipo tenga conectividad HTTPS al servidor.
• NORA_MACHINE_KEY environment variable is required. Falta la clave de máquina en el .env o en el entorno. Añádela y vuelve a iniciar el agente.
• NORA_API_URL debe usar https://. La URL de la API no usa HTTPS (y no es localhost). Corrígela en el .env.
• SmartScreen (Windows) o Gatekeeper (macOS) bloquean el ejecutable. Es esperable porque el binario no está firmado; usa Ejecutar de todas formas / Abrir de todas formas, o xattr -cr en macOS.

Páginas relacionadas

• Autenticación de la API
• Jobs
• Arquitectura