Remote Ops API

La Remote Ops API permette a un’interfaccia browser esterna, un’app Flutter, un orchestratore o un client su rete privata di ispezionare e controllare un nodo Guida in esecuzione. È separata da MCP e dall’API della dashboard operativa in sola lettura.

Remote Ops è disabilitata per impostazione predefinita. Quando viene abilitata, Guida espone un piano di controllo JSON-RPC limitato sotto /api/ops/*. Guida Complete e Guida Node possono entrambe esporla: Complete mantiene l’esperienza desktop/operatore completa, mentre Node è l’esecutore headed avanzato per automazione remota di browser e spazio di lavoro.

Remote Ops è anche la base per future superfici di controllo browser o desktop.

Modello di sicurezza

Remote Ops è un’API per canali fidati. Guida decide se la superficie è abilitata e se l’operazione richiesta è sicura localmente; la rete decide chi può raggiungerla.

Guida non autentica i client Remote Ops nell’MVP. Proteggi il canale con ACL NetBird, regole di Windows Firewall, policy di reverse proxy, tunnel localhost, mTLS o un controllo esterno equivalente.

Guida applica comunque controlli locali:

Remote Ops deve essere abilitata esplicitamente.
Dimensioni di richieste e risposte sono limitate.
I comandi hanno timeout.
La navigazione remota usa la policy dei domini autorizzati.
Gli strumenti dello spazio di lavoro devono essere strumenti nominati e dichiarati localmente.
I comandi sui processi di lavoro puntano a pool dichiarati, non a definizioni arbitrarie di script.
I valori delle credenziali di accesso non vengono esposti.
Le chiamate Remote Ops possono essere registrate nel registro di tracciabilità operativo.

Endpoint

Endpoint	Scopo
`GET /api/ops/health`	Stato leggero di Remote Ops e identità del nodo
`GET /api/ops/schema`	Contratto Remote Ops leggibile dalle macchine per i client
`POST /api/ops/rpc`	Endpoint di comando JSON-RPC 2.0
`GET /api/ops/events`	Stream SSE per stato, invalidazioni, processi di lavoro, code, registro, attività e audit
`GET /api/ops/metrics`	Metriche compatibili con Prometheus per distribuzioni piccole
`GET /api/ops/remote-view/{sessionId}/stream`	Stream WebSocket per una sessione Remote View

Lo stream eventi invia indizi, non stato persistente. I client dovrebbero ricaricare lo stato mirato tramite RPC o letture dashboard quando un evento è rilevante.

Impostazioni

Apri Settings e abilita Remote Operations API.

Impostazione	Significato
Enable Remote Operations API	Avvia il piano di controllo JSON-RPC su canale fidato
Audit Remote Operations Calls	Registra ogni chiamata RPC Remote Ops nel registro di tracciabilità operativo
Port	Porta usata quando Remote Ops è abilitata
Bind address	Loopback per impostazione predefinita; usa un indirizzo privato NetBird/VPN per il controllo remoto

Usa il bind su loopback per client locali, oppure un’interfaccia privata per NetBird/LAN. Non esporre Remote Ops direttamente a Internet pubblico.

Richiesta JSON-RPC

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

Le risposte di errore comuni usano codici standard JSON-RPC più codici specifici di Guida per spazio di lavoro non disponibile, dominio bloccato, autorizzazione richiesta, timeout, conflitto, richiesta troppo grande e risultato troppo grande.

Gruppi di metodi

Gruppo	Metodi rappresentativi
Sistema e dashboard	`system.health`, `system.capabilities`, `system.compatibility.check`, `dashboard.status`, `dashboard.snapshot`, `dashboard.failures`, `dashboard.attention`
Telemetria e registro	`telemetry.metrics.get`, `telemetry.events.recent`, `telemetry.events.summary`, `audit.entries.list`, `audit.entries.get`, `audit.summary`
Spazio di lavoro e flussi	`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`
Processi di lavoro e attività	`workers.listPools`, `workers.startPool`, `workers.stopPool`, `workers.pause`, `workers.resume`, `workers.runOne`, `tasks.list`, `tasks.get`, `tasks.cancel`
Strumenti	`tools.list`, `tools.run`
Code	`queues.list`, `queues.count`, `queues.items.list`, `queues.enqueue`, `queues.deadLetters.list`, `queues.deadLetters.retry`
Registro di tracciabilità dei flussi di lavoro	`ledger.runs.list`, `ledger.run.get`, `ledger.run.counts`, `ledger.run.reconcile`, `ledger.items.list`
Archiviazione e ricerca	`store.collections`, `store.documents.list`, `store.documents.get`, `search.collections`, `search.query`
Browser e pagina	`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`
Screenshot e Remote View	`screenshots.viewport`, `screenshots.fullPage`, `browser.remoteView.start`, `browser.remoteView.stop`, `browser.remoteView.status`

Confini operativi

Remote Ops può avviare pool di processi di lavoro dichiarati, eseguire strumenti dello spazio di lavoro nominati, navigare schede, ispezionare code, ispezionare il registro, leggere file limitati dello spazio di lavoro, ricaricare la configurazione dell’ambiente di esecuzione dello spazio di lavoro, recuperare lavoro attivo dei flussi di lavoro, ispezionare risultati catturati e trasmettere il contenuto delle schede. Non va trattata come MCP grezzo esposto sulla rete.

Usa Guida Complete quando vuoi l’app desktop locale completa, il server MCP, pannelli, impostazioni e strumenti operatore. Usa Guida Node quando vuoi specificamente un esecutore remoto headed controllato tramite un canale privato fidato.

Per monitoraggio senza controllo, usa l’API della dashboard operativa. Per sistemi di test automatizzati deterministici, usa la Modalità di automazione. Per accesso da strumenti IA locali, usa l’Integrazione MCP.

Passi successivi

Remote View - trasmetti e, se abilitato, controlla una scheda browser di Guida
API della dashboard operativa - endpoint di monitoraggio in sola lettura
Modalità di automazione - avvia Guida per sistemi di test
Integrazione MCP - accesso locale per strumenti IA con autorizzazione e registro