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는 명시적으로 활성화해야 합니다.
요청과 응답 크기는 제한됩니다.
명령에는 timeout이 있습니다.
원격 탐색에는 도메인 허용 정책이 적용됩니다.
워크스페이스 도구는 로컬에 선언된 이름 있는 도구여야 합니다.
워커 명령은 임의의 스크립트 정의가 아니라 선언된 워커 풀을 대상으로 합니다.
인증 정보 값은 노출되지 않습니다.
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 오류 코드에 더해 워크스페이스 없음, 도메인 차단, 승인 필요, timeout, 충돌, 요청 크기 초과, 결과 크기 초과 같은 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 통합을 사용하세요.