Remote Ops API

Die Remote Ops API erlaubt externen Browseroberflächen, Flutter-Apps, Orchestratoren oder privaten Netzwerkclients, einen laufenden Guida-Knoten zu inspizieren und zu steuern. Sie ist getrennt von MCP und von der schreibgeschützten Betriebsdashboard-API.

Remote Ops ist standardmäßig deaktiviert. Nach Aktivierung stellt Guida eine begrenzte JSON-RPC-Steuerung unter /api/ops/* bereit. Guida Complete und Guida Node können Remote Ops beide bereitstellen: Complete behält die vollständige Desktop-/Bedienerfahrung, während Node der fortgeschrittene headed Executor für Remote-Browser- und Arbeitsbereichsautomatisierung ist.

Remote Ops ist außerdem die Grundlage für künftige Browser- oder Desktop-Steuerungsoberflächen.

Sicherheitsmodell

Remote Ops ist eine Trusted-Channel-API. Guida entscheidet, ob die Oberfläche aktiv ist und ob eine angefragte Operation lokal zulässig ist; Ihr Netzwerk entscheidet, wer sie erreichen kann.

Guida authentifiziert Remote-Ops-Clients im MVP nicht selbst. Sichern Sie den Kanal mit NetBird-ACLs, Windows-Firewall-Regeln, Reverse-Proxy-Richtlinien, Localhost-Tunneln, mTLS oder einer vergleichbaren externen Kontrolle.

Lokale Schutzmechanismen bleiben aktiv:

Remote Ops muss explizit aktiviert werden.
Anfrage- und Antwortgrößen sind begrenzt.
Befehle haben Timeouts.
Remote-Navigation verwendet die Domainrichtlinie.
Arbeitsbereichswerkzeuge müssen lokal deklarierte Werkzeuge sein.
Worker-Befehle zielen auf deklarierte Worker-Pools.
Zugangsdatenwerte werden nicht offengelegt.
Remote-Ops-Aufrufe können im operativen Nachverfolgungsprotokoll auditiert werden.

Endpunkte

Endpunkt	Zweck
`GET /api/ops/health`	Leichte Health- und Knotenidentität
`GET /api/ops/schema`	Maschinenlesbarer Remote-Ops-Vertrag für Clients
`POST /api/ops/rpc`	JSON-RPC-2.0-Befehlsendpunkt
`GET /api/ops/events`	SSE-Stream für Status-, Invalidierungs-, Worker-, Queue-, Ledger-, Task- und Audit-Hinweise
`GET /api/ops/metrics`	Prometheus-kompatible Metriken für kleine Bereitstellungen
`GET /api/ops/remote-view/{sessionId}/stream`	WebSocket-Stream für eine Remote-View-Sitzung

Der Event-Stream sendet Hinweise, keinen dauerhaften Zustand. Clients sollten fokussierten Zustand bei Bedarf per RPC oder Dashboard-Lesung neu laden.

Einstellungen

Öffnen Sie Settings und aktivieren Sie Remote Operations API.

Einstellung	Bedeutung
Enable Remote Operations API	Startet die JSON-RPC-Steuerungsoberfläche
Audit Remote Operations Calls	Protokolliert Remote-Ops-Aufrufe im operativen Nachverfolgungsprotokoll
Port	Port bei aktivierter Remote-Ops-API
Bind address	Standardmäßig Loopback; für Remote-Steuerung private NetBird/VPN-Adresse verwenden

Setzen Sie die Bind-Adresse nicht direkt ins öffentliche Internet.

JSON-RPC

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

Fehlerantworten nutzen Standard-JSON-RPC-Codes plus Guida-spezifische Codes, etwa für fehlenden Arbeitsbereich, blockierte Domain, erforderliche Freigabe, Timeout, Konflikt oder zu große Payloads.

Methodengruppen

Gruppe	Repräsentative Methoden
System und Dashboard	`system.health`, `system.capabilities`, `system.compatibility.check`, `dashboard.status`, `dashboard.snapshot`, `dashboard.failures`, `dashboard.attention`
Telemetrie und Audit	`telemetry.metrics.get`, `telemetry.events.recent`, `telemetry.events.summary`, `audit.entries.list`, `audit.entries.get`, `audit.summary`
Arbeitsbereich und Workflows	`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`
Worker und Tasks	`workers.listPools`, `workers.startPool`, `workers.stopPool`, `workers.pause`, `workers.resume`, `workers.runOne`, `tasks.list`, `tasks.get`, `tasks.cancel`
Werkzeuge	`tools.list`, `tools.run`
Warteschlangen	`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`
Store und Suche	`store.collections`, `store.documents.list`, `store.documents.get`, `search.collections`, `search.query`
Browser und Seite	`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`
Screenshots und Remote View	`screenshots.viewport`, `screenshots.fullPage`, `browser.remoteView.start`, `browser.remoteView.stop`, `browser.remoteView.status`

Grenzen

Remote Ops kann deklarierte Worker-Pools starten, benannte Arbeitsbereichswerkzeuge ausführen, Tabs navigieren, Warteschlangen prüfen, Ledger-Zustand lesen, begrenzte Arbeitsbereichsdateien lesen, die Arbeitsbereichslaufzeit neu laden, aktive Workflow-Arbeit wiederherstellen, erfasste Ergebnisse prüfen und Tab-Inhalte streamen. Es ist kein MCP über das Netzwerk.

Verwenden Sie Guida Complete, wenn Sie die vollständige lokale Desktop-App, den MCP-Server, Paneele, Einstellungen und Bedienwerkzeuge möchten. Verwenden Sie Guida Node, wenn Sie gezielt einen headed Remote-Executor über einen vertrauenswürdigen privaten Kanal steuern möchten.

Für Monitoring ohne Steuerung verwenden Sie die Betriebsdashboard-API. Für deterministische Test-Harnesses verwenden Sie den Automatisierungsmodus. Für lokalen KI-Werkzeugzugriff verwenden Sie MCP.