API Remote Ops

La API Remote Ops permite que una interfaz de navegador externa, una aplicación Flutter, un orquestador o un cliente de red privada inspeccione y controle un nodo Guida en ejecución. Está separada de MCP y de la API del panel operativo en sola lectura.

Remote Ops está deshabilitado por defecto. Cuando se habilita, Guida expone un plano de control JSON-RPC limitado bajo /api/ops/*. Guida Complete y Guida Node pueden exponerlo: Complete conserva la experiencia completa de escritorio/operador, mientras que Node es el ejecutor headed avanzado para automatización remota de navegador y espacio de trabajo.

Remote Ops también es la base para futuras superficies de control de navegador o escritorio.

Modelo de seguridad

Remote Ops es una API de canal de confianza. Guida decide si la superficie está habilitada y si una operación solicitada es localmente segura; su red decide quién puede alcanzarla.

Guida no autentica clientes Remote Ops en el MVP. Proteja el canal con ACL de NetBird, reglas del firewall de Windows, política de proxy inverso, túneles localhost, mTLS o un control externo equivalente.

Guida sigue aplicando controles locales de seguridad:

Remote Ops debe habilitarse explícitamente.
Los tamaños de solicitud y respuesta están limitados.
Los comandos tienen tiempos de espera.
La navegación remota usa la política de dominios autorizados.
Las herramientas del espacio de trabajo deben ser herramientas nombradas declaradas localmente.
Los comandos de procesos de trabajo apuntan a pools declarados, no a definiciones arbitrarias de script.
Los valores secretos no se exponen.
Las llamadas Remote Ops pueden registrarse en el registro de trazabilidad operativo.

Endpoints

Endpoint	Propósito
`GET /api/ops/health`	Salud ligera de Remote Ops e identidad del nodo
`GET /api/ops/schema`	Contrato Remote Ops legible por máquina para clientes
`POST /api/ops/rpc`	Endpoint de comandos JSON-RPC 2.0
`GET /api/ops/events`	Flujo SSE para pistas de estado, invalidación, procesos, colas, registro, tareas y trazabilidad
`GET /api/ops/metrics`	Métricas compatibles con Prometheus para despliegues pequeños
`GET /api/ops/remote-view/{sessionId}/stream`	Flujo WebSocket para una sesión Remote View

El flujo de eventos envía pistas, no estado duradero. Los clientes deben recargar el estado enfocado mediante RPC o lecturas del panel cuando un evento importe.

Configuración

Abra Settings y habilite Remote Operations API.

Ajuste	Significado
Enable Remote Operations API	Inicia la superficie de control JSON-RPC por canal de confianza
Audit Remote Operations Calls	Registra cada llamada RPC Remote Ops en el registro de trazabilidad operativo
Port	Puerto usado cuando Remote Ops está habilitado
Bind address	Loopback por defecto; use una dirección de interfaz privada NetBird/VPN para control remoto

Enlace a loopback para clientes locales, o a una interfaz privada para uso NetBird/LAN. No exponga Remote Ops directamente a internet público.

Solicitud JSON-RPC

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "workers.startPool",
  "params": {
    "queueName": "careers_fetch"
  }
}

Las respuestas de error comunes usan códigos de error JSON-RPC estándar más códigos específicos de Guida para espacio de trabajo no disponible, dominio bloqueado, autorización requerida, tiempo de espera, conflicto, contenido sobredimensionado y resultado sobredimensionado.

Grupos de métodos

Grupo	Métodos representativos
Sistema y panel	`system.health`, `system.capabilities`, `system.compatibility.check`, `dashboard.status`, `dashboard.snapshot`, `dashboard.failures`, `dashboard.attention`
Telemetría y trazabilidad	`telemetry.metrics.get`, `telemetry.events.recent`, `telemetry.events.summary`, `audit.entries.list`, `audit.entries.get`, `audit.summary`
Espacio de trabajo y flujos	`workspace.info`, `workspace.files.tree`, `workspace.files.read`, `workspace.files.search`, `workspace.files.diff`, `workspace.files.write`, `workspace.files.context`, `workspace.runtime.reload`, `workflows.list`, `workflows.active.controlRoom.get`, `workflows.active.recovery.plan`, `workflows.active.recovery.preview`, `workflows.active.recovery.execute`
Procesos de trabajo y tareas	`workers.listPools`, `workers.startPool`, `workers.stopPool`, `workers.pause`, `workers.resume`, `workers.runOne`, `tasks.list`, `tasks.get`, `tasks.cancel`
Herramientas	`tools.list`, `tools.run`
Colas	`queues.list`, `queues.count`, `queues.items.list`, `queues.enqueue`, `queues.deadLetters.list`, `queues.deadLetters.retry`
Workflow Ledger	`ledger.runs.list`, `ledger.run.get`, `ledger.run.counts`, `ledger.run.reconcile`, `ledger.items.list`
Almacén y búsqueda	`store.collections`, `store.documents.list`, `store.documents.get`, `search.collections`, `search.query`
Navegador y página	`browser.tabs.list`, `browser.tabs.create`, `browser.tabs.activate`, `browser.navigate`, `browser.viewport.get`, `browser.viewport.set`, `page.content.extract`, `page.elements.list`, `page.waitForDomStable`
Capturas y Remote View	`screenshots.viewport`, `screenshots.fullPage`, `browser.remoteView.start`, `browser.remoteView.stop`, `browser.remoteView.status`

Límites operativos

Remote Ops puede iniciar pools de procesos declarados, ejecutar herramientas nombradas del espacio de trabajo, navegar pestañas, inspeccionar colas, inspeccionar estado del registro, leer archivos acotados del espacio de trabajo, recargar la configuración del runtime del espacio de trabajo, recuperar trabajo activo de flujos de trabajo, inspeccionar resultados capturados y transmitir contenido de pestañas. No debe tratarse como MCP bruto sobre la red.

Use Guida Complete cuando quiera la app local completa de escritorio, servidor MCP, paneles, ajustes y herramientas de operador. Use Guida Node cuando quiera específicamente un ejecutor remoto headed controlado por un canal privado de confianza.

Para monitorización sin control, use la API del panel operativo. Para bancos de pruebas automatizados deterministas, use Modo de automatización. Para acceso de herramientas de IA desde un cliente local, use Integración MCP.

Siguientes pasos

Remote View - transmitir y opcionalmente controlar una pestaña de navegador de Guida
API del panel operativo - endpoints de monitorización en sola lectura
Modo de automatización - iniciar Guida para bancos de pruebas
Integración MCP - acceso local de herramientas de IA con autorización y trazabilidad