API Remote Ops

L’API Remote Ops permet à une interface web externe, une application Flutter, un orchestrateur ou un client de réseau privé d’inspecter et de contrôler un nœud Guida en cours d’exécution. Elle est distincte de MCP et de l’API du tableau de bord opérationnel en lecture seule.

Remote Ops est désactivée par défaut. Lorsqu’elle est activée, Guida expose un plan de contrôle JSON-RPC borné sous /api/ops/*. Guida Complete et Guida Node peuvent l’exposer : Complete conserve l’expérience desktop/opérateur complète, tandis que Node est l’exécuteur headed avancé pour l’automatisation distante du navigateur et de l’espace de travail.

Remote Ops est aussi la base des futures surfaces de contrôle navigateur ou desktop.

Modèle de sécurité

Remote Ops est une API sur canal de confiance. Guida décide si la surface est activée et si une opération demandée est localement sûre ; votre réseau décide qui peut l’atteindre.

Guida n’authentifie pas les clients Remote Ops dans le MVP. Sécurisez le canal avec des ACL NetBird, des règles du pare-feu Windows, une stratégie de reverse proxy, des tunnels localhost, mTLS ou un contrôle externe équivalent.

Guida applique tout de même des contrôles locaux :

Remote Ops doit être activée explicitement.
Les tailles de requête et de réponse sont bornées.
Les commandes ont des délais d’expiration.
La navigation distante utilise la politique de liste de domaines autorisés.
Les outils d’espace de travail doivent être des outils nommés déclarés localement.
Les commandes de processus de travail ciblent des pools déclarés, pas des définitions de scripts arbitraires.
Les valeurs des identifiants d’accès ne sont pas exposées.
Les appels Remote Ops peuvent être journalisés dans le registre de traçabilité opérationnel.

Endpoints

Endpoint	Usage
`GET /api/ops/health`	Santé légère de Remote Ops et identité du nœud
`GET /api/ops/schema`	Contrat Remote Ops lisible par machine pour les clients
`POST /api/ops/rpc`	Endpoint de commande JSON-RPC 2.0
`GET /api/ops/events`	Flux SSE pour indices d’état, d’invalidation, de processus, de files, de registre, de tâches et de traçabilité
`GET /api/ops/metrics`	Métriques compatibles Prometheus pour petits déploiements
`GET /api/ops/remote-view/{sessionId}/stream`	Flux WebSocket pour une session Remote View

Le flux d’événements envoie des indices, pas un état durable. Les clients doivent recharger l’état ciblé via RPC ou lectures du tableau de bord lorsqu’un événement compte.

Paramètres

Ouvrez Settings et activez Remote Operations API.

Paramètre	Signification
Enable Remote Operations API	Démarre la surface de contrôle JSON-RPC sur canal de confiance
Audit Remote Operations Calls	Enregistre chaque appel RPC Remote Ops dans le registre de traçabilité opérationnel
Port	Port utilisé lorsque Remote Ops est activée
Bind address	Adresse de bouclage par défaut ; utilisez une adresse d’interface privée NetBird/VPN pour le contrôle distant

Liez Remote Ops à l’interface de bouclage pour les clients locaux, ou à une interface privée pour NetBird ou un LAN. N’exposez pas Remote Ops directement sur l’internet public.

Requête JSON-RPC

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

Les réponses d’erreur courantes utilisent les codes d’erreur JSON-RPC standard, plus des codes propres à Guida pour espace de travail indisponible, domaine bloqué, autorisation requise, délai expiré, conflit, charge utile trop grande et résultat trop grand.

Groupes de méthodes

Groupe	Méthodes représentatives
Système et tableau de bord	`system.health`, `system.capabilities`, `system.compatibility.check`, `dashboard.status`, `dashboard.snapshot`, `dashboard.failures`, `dashboard.attention`
Télémétrie et traçabilité	`telemetry.metrics.get`, `telemetry.events.recent`, `telemetry.events.summary`, `audit.entries.list`, `audit.entries.get`, `audit.summary`
Espace de travail et flux	`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`
Processus et tâches	`workers.listPools`, `workers.startPool`, `workers.stopPool`, `workers.pause`, `workers.resume`, `workers.runOne`, `tasks.list`, `tasks.get`, `tasks.cancel`
Outils	`tools.list`, `tools.run`
Files	`queues.list`, `queues.count`, `queues.items.list`, `queues.enqueue`, `queues.deadLetters.list`, `queues.deadLetters.retry`
Registre de traçabilité des flux	`ledger.runs.list`, `ledger.run.get`, `ledger.run.counts`, `ledger.run.reconcile`, `ledger.items.list`
Stockage et recherche	`store.collections`, `store.documents.list`, `store.documents.get`, `search.collections`, `search.query`
Navigateur et page	`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`
Captures d’écran et Remote View	`screenshots.viewport`, `screenshots.fullPage`, `browser.remoteView.start`, `browser.remoteView.stop`, `browser.remoteView.status`

Limites opérationnelles

Remote Ops peut démarrer des pools de processus déclarés, exécuter des outils d’espace de travail nommés, naviguer dans des onglets, inspecter des files, inspecter l’état du registre, lire des fichiers bornés d’espace de travail, recharger la configuration du runtime de l’espace de travail, récupérer du travail actif de workflow, inspecter des résultats capturés et diffuser le contenu d’un onglet. Elle ne doit pas être traitée comme du MCP brut exposé sur le réseau.

Utilisez Guida Complete lorsque vous voulez l’app desktop locale complète, le serveur MCP, les panneaux, les paramètres et les outils opérateur. Utilisez Guida Node lorsque vous voulez précisément un exécuteur distant headed contrôlé par un canal privé de confiance.

Pour la supervision sans contrôle, utilisez l’API du tableau de bord opérationnel. Pour des harnais de test automatisés déterministes, utilisez le mode d’automatisation. Pour l’accès aux outils IA depuis un client local, utilisez l’intégration MCP.

Étapes suivantes

Remote View — diffuser et éventuellement contrôler un onglet de navigateur Guida
API du tableau de bord opérationnel — endpoints de supervision en lecture seule
Mode d’automatisation — lancer Guida pour des harnais de test
Intégration MCP — accès local aux outils IA avec autorisation et traçabilité