Skip to content
Guida

Remote Ops API

The Remote Ops API lets an external browser UI, Flutter app, orchestrator, or private-network client inspect and control a running Guida node. It is separate from MCP and from the read-only Operational Dashboard API.

Remote Ops is disabled by default. When enabled, Guida exposes a bounded JSON-RPC control plane under /api/ops/*. Guida Complete and Guida Node can both expose it: Complete keeps the full desktop/operator experience, while Node is the advanced headed executor for remote browser and workspace automation.

Remote Ops is also the foundation for future browser or desktop control surfaces.

Safety model

Section titled “Safety model”

Remote Ops is a trusted-channel API. Guida decides whether the surface is enabled and whether a requested operation is locally safe; your network decides who can reach it.

Guida does not authenticate Remote Ops clients in the MVP. Secure the channel with NetBird ACLs, Windows firewall rules, reverse proxy policy, localhost tunnels, mTLS, or an equivalent external control.

Guida still applies local safety controls:

  • Remote Ops must be explicitly enabled.
  • Request and response sizes are bounded.
  • Commands have timeouts.
  • Remote navigation uses domain whitelist policy.
  • Workspace tools must be named tools declared locally.
  • Worker commands target declared worker pools rather than arbitrary script definitions.
  • Secret values are not exposed.
  • Remote Ops calls can be audited in the operational audit trail.

Endpoints

Section titled “Endpoints”
EndpointPurpose
GET /api/ops/healthLightweight Remote Ops health and node identity
GET /api/ops/schemaMachine-readable Remote Ops contract for clients
POST /api/ops/rpcJSON-RPC 2.0 command endpoint
GET /api/ops/eventsSSE stream for status, invalidation, worker, queue, ledger, task, and audit hints
GET /api/ops/metricsPrometheus-compatible small-deployment metrics
GET /api/ops/remote-view/{sessionId}/streamWebSocket stream for a Remote View session

The event stream sends hints, not durable state. Clients should reload focused state through RPC or dashboard reads when an event matters.

Settings

Section titled “Settings”

Open Settings and enable Remote Operations API.

SettingMeaning
Enable Remote Operations APIStarts the trusted-channel JSON-RPC control surface
Audit Remote Operations CallsRecords each Remote Ops RPC call in the operational audit trail
PortPort used when Remote Ops is enabled
Bind addressLoopback by default; use a private NetBird/VPN interface address for remote control

Bind to loopback for local clients, or to a private interface for NetBird/LAN use. Do not expose Remote Ops directly to the public internet.

JSON-RPC request

Section titled “JSON-RPC request”
{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "workers.startPool",
  "params": {
    "queueName": "careers_fetch"
  }
}

Common error responses use standard JSON-RPC error codes plus Guida-specific codes for workspace unavailable, domain blocked, approval required, timeout, conflict, oversized payload, and oversized result.

Method groups

Section titled “Method groups”
GroupRepresentative methods
System and dashboardsystem.health, system.capabilities, system.compatibility.check, dashboard.status, dashboard.snapshot, dashboard.failures, dashboard.attention
Telemetry and audittelemetry.metrics.get, telemetry.events.recent, telemetry.events.summary, audit.entries.list, audit.entries.get, audit.summary
Workspace and workflowsworkspace.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 and tasksworkers.listPools, workers.startPool, workers.stopPool, workers.pause, workers.resume, workers.runOne, worker.results.list, worker.results.get, tasks.list, tasks.get, tasks.result.get, tasks.cancel
Toolstools.list, tools.trust.evaluate, tools.run
Queuesqueues.list, queues.count, queues.items.list, queues.enqueue, queues.deadLetters.list, queues.deadLetters.retry
Workflow Ledgerledger.runs.list, ledger.run.get, ledger.run.counts, ledger.run.reconcile, ledger.items.list
Store and searchstore.collections, store.documents.list, store.documents.get, search.collections, search.query
Browser and pagebrowser.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 and Remote Viewscreenshots.viewport, screenshots.fullPage, browser.remoteView.start, browser.remoteView.stop, browser.remoteView.status

Operational boundaries

Section titled “Operational boundaries”

Remote Ops can start declared worker pools, run named workspace tools, navigate tabs, inspect queues, inspect ledger state, read bounded workspace files, reload workspace runtime configuration, recover active workflow work, inspect captured results, and stream tab contents. It should not be treated as raw MCP over the network.

Use Guida Complete when you want the full local desktop app, MCP server, panes, settings, and operator tools. Use Guida Node when you specifically want a headed remote executor controlled over a trusted private channel.

For monitoring without control, use the Operational Dashboard API. For deterministic automated test harnesses, use Automation Mode. For AI tool access from a local client, use MCP Integration.

Next steps

Section titled “Next steps”