Remote Ops API

Remote Ops API は、外部ツールが Guida ノードをリモートから調査・制御するための JSON-RPC 面です。MCP および読み取り専用の Operational Dashboard API とは別の機能です。

Remote Ops は既定で無効です。有効にすると、Guida は /api/ops/* 配下に限定された JSON-RPC 制御プレーンを公開します。Guida Complete と Guida Node はどちらも Remote Ops を公開できます。Complete は完全なデスクトップ/オペレーター体験を保持し、Node はリモートのブラウザーおよびワークスペース自動化向けの高度な headed executor です。

Remote Ops は将来のブラウザーまたはデスクトップ制御サーフェスの基盤にもなります。

MCP ではありません

Remote Ops API は MCP ではありません。MCP はローカル AI ツール向けの承認付き操作面です。Remote Ops は、プライベートネットワーク内の運用ツールや制御面から Guida ノードを扱うための別 API です。

セキュリティモデル

Remote Ops は信頼済みチャネル用の API です。Guida はそのサーフェスが有効かどうか、要求された操作がローカルで安全かどうかを判断します。誰が到達できるかはネットワーク側で決めます。

MVP の Remote Ops API は、Guida 自体でクライアント認証を実装しません。NetBird ACL、Windows ファイアウォール規則、reverse proxy ポリシー、localhost tunnel、mTLS、または同等の外部制御で通信路を保護してください。

Guida はローカルの安全制御も適用します。

Remote Ops は明示的に有効化する必要があります。
要求と応答のサイズには上限があります。
コマンドにはタイムアウトがあります。
リモートナビゲーションにはドメイン許可ポリシーが適用されます。
ワークスペースツールはローカルで宣言された名前付きツールである必要があります。
ワーカーコマンドは任意のスクリプト定義ではなく、宣言済みワーカープールを対象にします。
認証情報の値は公開されません。
Remote Ops 呼び出しは運用監査履歴に記録できます。

エンドポイント

エンドポイント	目的
`GET /api/ops/health`	Remote Ops の軽量ヘルスとノード識別情報
`GET /api/ops/schema`	クライアント向けの機械可読 Remote Ops 契約
`POST /api/ops/rpc`	JSON-RPC 2.0 コマンドエンドポイント
`GET /api/ops/events`	状態、無効化、ワーカー、キュー、ledger、タスク、監査ヒントの SSE ストリーム
`GET /api/ops/metrics`	小規模デプロイ向け Prometheus 互換メトリクス
`GET /api/ops/remote-view/{sessionId}/stream`	Remote View セッション用 WebSocket ストリーム

イベントストリームはヒントを送るもので、永続状態ではありません。重要なイベントを受けたクライアントは、RPC または Dashboard の読み取りで対象状態を再取得してください。

JSON-RPC 要求

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

一般的なエラー応答には、標準 JSON-RPC エラーコードに加えて、ワークスペース未使用、ドメインブロック、承認必須、タイムアウト、競合、要求サイズ超過、結果サイズ超過などの Guida 固有コードが含まれます。

メソッドグループ

グループ	代表的なメソッド
System と Dashboard	`system.health`, `system.capabilities`, `system.compatibility.check`, `dashboard.status`, `dashboard.snapshot`, `dashboard.failures`, `dashboard.attention`
Telemetry と audit	`telemetry.metrics.get`, `telemetry.events.recent`, `telemetry.events.summary`, `audit.entries.list`, `audit.entries.get`, `audit.summary`
Workspace と 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`
Workers と tasks	`workers.listPools`, `workers.startPool`, `workers.stopPool`, `workers.pause`, `workers.resume`, `workers.runOne`, `tasks.list`, `tasks.get`, `tasks.cancel`
Tools	`tools.list`, `tools.trust.evaluate`, `tools.run`
Queues	`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 と search	`store.collections`, `store.documents.list`, `store.documents.get`, `search.collections`, `search.query`
Browser と 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`
Screenshots と Remote View	`screenshots.viewport`, `screenshots.fullPage`, `browser.remoteView.start`, `browser.remoteView.stop`, `browser.remoteView.status`

運用上の境界

Remote Ops は、宣言済みワーカープールの開始、名前付きワークスペースツールの実行、タブのナビゲーション、キューの検査、ledger 状態の確認、制限付きワークスペースファイルの読み取り、ワークスペースランタイム設定の再読み込み、アクティブなワークフロー作業の復旧、取得済み結果の検査、タブ内容のストリーミングができます。ネットワーク越しの raw MCP として扱わないでください。

完全なローカルデスクトップアプリ、MCP サーバー、ペイン、設定、オペレーターツールが必要な場合は Guida Complete を使います。信頼済みのプライベートチャネルから制御する headed リモート executor が必要な場合は Guida Node を使います。

Operational Dashboard API との違い

Operational Dashboard API は読み取り専用の監視 API です。Remote Ops API は制御 API です。監視だけが目的なら Operational Dashboard API を使い、遠隔操作が必要な場合だけ Remote Ops を有効化します。決定的なテストハーネスには Automation Mode を使い、ローカル AI ツール連携には MCP 連携を使います。