Skip to content
Guida

Automation Mode

Automation mode is for automated test harnesses that need to launch Guida, attach to WebView2 through CDP, open a workspace, create tabs, wait for readiness, and shut the app down deterministically.

It is separate from the Operational Dashboard API and Remote Ops API. Dashboard endpoints are read-only monitoring endpoints. Remote Ops is an explicitly enabled trusted-channel control API for live nodes. Automation endpoints are for deterministic test harnesses and are available only when Guida is launched with --automation.

Launch switches

Section titled “Launch switches”

Automation-only switches are accepted only when --automation is present.

SwitchPurpose
--automationEnables automation mode
--workspace <path>Opens a workspace at startup
--webview-user-data-dir <path>Uses a specific WebView2 profile directory
--cdp-port <port>Exposes WebView2 Chrome DevTools Protocol on the given port
--dashboard-host <address>Overrides the embedded server bind address
--dashboard-port <port>Overrides the embedded server port
--automation-token <token>Sets the token required by /api/automation/* requests

If no WebView2 user-data directory is supplied, Guida creates an isolated temporary automation profile. If no automation token is supplied, Guida generates one and writes it to the Console.

Example:

Terminal window
Guida.exe --automation `
  --workspace C:\dev\btbrowser-workspace `
  --webview-user-data-dir C:\temp\guida-webview `
  --cdp-port 9222 `
  --dashboard-host 127.0.0.1 `
  --dashboard-port 9315 `
  --automation-token test-token

CDP passthrough

Section titled “CDP passthrough”

Use --cdp-port when a Playwright-style harness needs to connect to the underlying WebView2 browser through Chrome DevTools Protocol.

CDP gives the harness browser-level inspection and automation. The Guida automation API covers Guida-specific operations such as opening workspaces, creating Guida tabs, activating tabs, waiting for readiness, and shutting down the app.

Authentication

Section titled “Authentication”

Automation endpoints require either header form:

X-Guida-Automation-Token: test-token

or:

Authorization: Bearer test-token

When automation mode is disabled, /api/automation/* endpoints return 404. When automation mode is enabled but the token is missing or wrong, requests are rejected.

Endpoints

Section titled “Endpoints”

All endpoints are under /api/automation.

EndpointPurpose
GET /api/automation/statusReturns workspace, active workflow, active tab, and tab count
GET /api/automation/sessionOpens an SSE heartbeat stream for harness lifecycle checks
POST /api/automation/workspaceOpens a workspace from { "path": "..." }
GET /api/automation/tabsLists Guida tabs visible to the harness
POST /api/automation/tabsCreates a tab from { "name": "...", "url": "...", "activate": true, "waitForLoad": true }
POST /api/automation/tabs/{tabId}/activateActivates an existing tab
GET /api/automation/tabs/active/readyWaits for the active tab to be ready; supports timeoutMs
POST /api/automation/shutdownRequests Guida shutdown

Typical harness flow

Section titled “Typical harness flow”
  1. Launch Guida with --automation, a dashboard port, and a known automation token.
  2. Call GET /api/automation/status until Guida is reachable.
  3. Open a workspace if one was not supplied at launch.
  4. Create or activate a Guida tab.
  5. Wait for GET /api/automation/tabs/active/ready.
  6. Connect the browser harness to the CDP port when browser-level automation is needed.
  7. Call POST /api/automation/shutdown during teardown.

Safety notes

Section titled “Safety notes”

Keep automation mode local or inside a trusted test environment. Unlike the dashboard API, automation endpoints can open workspaces, create and activate tabs, and shut Guida down.

Remote private-network access without control should use the read-only Operational Dashboard API instead. Remote private-network control for operator tools should use Remote Ops API, not Automation Mode.

Next steps

Section titled “Next steps”