Agente Local

Instalación del Agente Local (CLI/Docker o Desktop) — variables de entorno, protocolo y drivers.

El Agente Local (valwisp-agent) es un bridge Node.js/TypeScript que corre dentro de la red del ISP y expone routers/OLTs con IP privada al backend cloud de Valwisp. Se conecta con una WebSocket saliente (Socket.io, path /agent-ws) — no requiere puertos abiertos ni VPN, funciona detrás de NAT.

Opción 1 — App de escritorio (recomendada)

Pensada para un técnico sin experiencia en CLI:

Descarga el instalador desde el dashboard (Red → Agente Local, o directamente GET /agent/downloads en la API) — Windows (NSIS), macOS (DMG) o Linux (AppImage).
Instala normalmente.
Abre la app e inicia sesión con el email/contraseña de Valwisp del tenant — la app obtiene el token del agente automáticamente, no hace falta copiarlo a mano.
Queda corriendo en la bandeja del sistema, con auto-arranque activado por defecto.

El core de comandos que ejecuta el Desktop es el mismo que el CLI: se sincroniza en cada build vía apps/valwisp-agent-desktop/scripts/sync-agent-core.js, que copia types.ts, logger.ts, command-executor.ts y los drivers desde apps/valwisp-agent/src/ — cualquier fix de lógica de comandos se hace una sola vez, en el CLI.

Opción 2 — CLI / Docker (para servidores)

Para correrlo en un servidor Linux dentro de la LAN del ISP:

docker run -d --network host --restart always \
  -e AGENT_TOKEN=xxx \
  -e CLOUD_URL=wss://api.valwisp.com \
  --name valwisp-agent valwisp/agent

--network host es obligatorio — sin eso el contenedor no puede alcanzar los routers de la LAN.

Variables de entorno

Variable	Requerida	Descripción
`AGENT_TOKEN`	Sí	Se genera desde Dashboard → Red → Agente Local. El proceso no arranca sin este valor.
`CLOUD_URL`	No	Default `wss://api.valwisp.com`. Fuera de `localhost`, debe ser `wss://` (si no, el agente emite un warning de seguridad — las credenciales de los routers viajarían sin cifrar).
`AGENT_NAME`	No	Default: hostname del equipo.
`LOG_LEVEL`	No	`debug` \| `info` \| `warn` \| `error`.
`COMMAND_TIMEOUT`	No	ms, default `30000`.
`HEARTBEAT_INTERVAL`	No	ms, default `30000`.

Protocolo

Dirección	Eventos
Agente → Cloud	`agent:auth`, `agent:heartbeat`, `agent:result` / `agent:command-result`
Cloud → Agente	`agent:auth-ok`, `agent:auth-fail`, `agent:command`, `agent:config-update`

Al conectar, el agente envía agent:auth con el token, nombre, versión, hostname y arquitectura. Si el token es inválido (code === 'INVALID_TOKEN'), el agente se apaga solo; si el fallo es transitorio (rate-limit), reintenta con la reconexión automática de Socket.io (backoff de 2s hasta 30s). El heartbeat reporta uptime, memoria, CPU, dispositivos conectados y comandos pendientes.

Drivers disponibles

routeros.driver.ts — MikroTik RouterOS API (puerto 8728, soporta TLS self-signed).
snmp.driver.ts — SNMP v1/v2c/v3 para OLTs y radios AirOS antiguos.
network.driver.ts — ping, tcpCheck (verificación sin credenciales), traceroute y discoveryScan (escaneo de subred, máximo /22). Usa execFile (no shell) con validación estricta de host para evitar inyección de comandos.

Verificación

Una vez conectado, en Dashboard → Red → Agente Local debe verse el estado "conectado" con el último heartbeat reciente. Si un router de esa red no responde a pesar de eso, prueba primero con la conectividad TCP simple (network.driver.ts) antes de sospechar de las credenciales RouterOS.