API de operações remotas

A API de operações remotas permite que uma interface de navegador externa, aplicativo Flutter, orquestrador ou cliente de rede privada inspecione e controle um nó Guida em execução. Ela é separada do MCP e da API do painel operacional somente leitura.

As operações remotas ficam desativadas por padrão. Quando habilitadas, o Guida expõe um plano de controle JSON-RPC limitado em /api/ops/*. Guida Complete e Guida Node podem expor Remote Ops: Complete mantém a experiência completa de desktop/operador, enquanto Node é o executor headed avançado para automação remota de navegador e espaço de trabalho.

Remote Ops também é a base para futuras superfícies de controle de navegador ou desktop.

Modelo de segurança

A API de operações remotas usa um canal confiável. O Guida decide se a superfície está habilitada e se uma operação solicitada é localmente segura; sua rede decide quem consegue alcançá-la.

O Guida não autentica clientes de operações remotas no MVP. Proteja o canal com ACLs do NetBird, regras do firewall do Windows, política de proxy reverso, túneis localhost, mTLS ou controle externo equivalente.

O Guida ainda aplica controles locais de segurança:

Operações remotas precisam ser habilitadas explicitamente.
Tamanhos de solicitação e resposta são limitados.
Comandos têm timeouts.
Navegação remota usa a política de lista de domínios permitidos.
Ferramentas do espaço de trabalho devem ser ferramentas nomeadas declaradas localmente.
Comandos de processos de trabalho miram grupos declarados, não definições arbitrárias de script.
Valores de credenciais não são expostos.
Chamadas de operações remotas podem ser auditadas no registro operacional.

Pontos de extremidade

Ponto de extremidade	Finalidade
`GET /api/ops/health`	Saúde leve das operações remotas e identidade do nó
`GET /api/ops/schema`	Contrato Remote Ops legível por máquina para clientes
`POST /api/ops/rpc`	Ponto de extremidade de comandos JSON-RPC 2.0
`GET /api/ops/events`	Fluxo SSE para dicas de status, invalidação, processo de trabalho, fila, registro, tarefa e auditoria
`GET /api/ops/metrics`	Métricas compatíveis com Prometheus para pequenas implantações
`GET /api/ops/remote-view/{sessionId}/stream`	Fluxo WebSocket para uma sessão de visualização remota

O fluxo de eventos envia dicas, não estado durável. Clientes devem recarregar estado focado por RPC ou leituras do painel quando um evento importar.

Configurações

Abra Settings e habilite Remote Operations API.

Configuração	Significado
Enable Remote Operations API	Inicia a superfície de controle JSON-RPC por canal confiável
Audit Remote Operations Calls	Registra cada chamada RPC de operações remotas no registro operacional
Port	Porta usada quando as operações remotas estão habilitadas
Bind address	Loopback por padrão; use um endereço de interface privada NetBird/VPN para controle remoto

Faça bind em loopback para clientes locais ou em uma interface privada para uso via NetBird/LAN. Não exponha operações remotas diretamente à internet pública.

Solicitação JSON-RPC

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

Respostas comuns de erro usam códigos JSON-RPC padrão mais códigos específicos do Guida para espaço de trabalho indisponível, domínio bloqueado, aprovação exigida, tempo limite, conflito, conteúdo grande demais e resultado grande demais.

Grupos de métodos

Grupo	Métodos representativos
Sistema e painel	`system.health`, `system.capabilities`, `system.compatibility.check`, `dashboard.status`, `dashboard.snapshot`, `dashboard.failures`, `dashboard.attention`
Telemetria e auditoria	`telemetry.metrics.get`, `telemetry.events.recent`, `telemetry.events.summary`, `audit.entries.list`, `audit.entries.get`, `audit.summary`
Espaço de trabalho e fluxos	`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`
Processos de trabalho e tarefas	`workers.listPools`, `workers.startPool`, `workers.stopPool`, `workers.pause`, `workers.resume`, `workers.runOne`, `tasks.list`, `tasks.get`, `tasks.cancel`
Ferramentas	`tools.list`, `tools.run`
Filas	`queues.list`, `queues.count`, `queues.items.list`, `queues.enqueue`, `queues.deadLetters.list`, `queues.deadLetters.retry`
Registro de rastreabilidade	`ledger.runs.list`, `ledger.run.get`, `ledger.run.counts`, `ledger.run.reconcile`, `ledger.items.list`
Armazenamento e pesquisa	`store.collections`, `store.documents.list`, `store.documents.get`, `search.collections`, `search.query`
Navegador e página	`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`
Capturas de tela e visualização remota	`screenshots.viewport`, `screenshots.fullPage`, `browser.remoteView.start`, `browser.remoteView.stop`, `browser.remoteView.status`

Limites operacionais

Operações remotas podem iniciar grupos declarados de processos de trabalho, executar ferramentas nomeadas do espaço de trabalho, navegar guias, inspecionar filas, inspecionar estado do registro, ler arquivos limitados do espaço de trabalho, recarregar a configuração do runtime do espaço de trabalho, recuperar trabalho ativo de fluxos, inspecionar resultados capturados e transmitir conteúdo de guias. Essa superfície não deve ser tratada como MCP bruto pela rede.

Use Guida Complete quando quiser o app desktop local completo, servidor MCP, painéis, configurações e ferramentas de operador. Use Guida Node quando quiser especificamente um executor remoto headed controlado por um canal privado confiável.

Para monitoramento sem controle, use a API do painel operacional. Para estruturas de teste automatizadas determinísticas, use Modo de automação. Para acesso de ferramentas de IA a partir de um cliente local, use Integração MCP.

Próximos passos

Visualização remota - transmita e, opcionalmente, controle uma guia do navegador Guida
API do painel operacional - pontos de extremidade de monitoramento somente leitura
Modo de automação - inicie o Guida para estruturas de teste
Integração MCP - acesso local de ferramentas de IA com aprovação e auditoria