Core Concepts

Architecture

How the pieces fit together.

Overview

CLIENTSDK / CLITypeScriptprompts · streams eventsDASHBOARDWeb Appaccount · billing · devicesPOST /queryWS eventsREST APIRunner APIPOST /queryWS /run/eventsPOST /run/cancelplans steps via LLMstreams eventsauth · billing · devicesWeb PushWS eventsEXTENSIONChromeWXT + Svelte 5executes automation

Components

SDK / CLI (client-side)

Your entry point. TypeScript SDK and CLI. Sends a prompt to the runner, then listens for events via WebSocket. Handles auth, streaming, and cancellation.

Runner API (server-side)

The server that orchestrates automations. Responsibilities:

  • Receives queries, creates Run records
  • Sends web push notifications to wake up the target Chrome extension
  • Manages WebSocket connections for event streaming
  • Plans automation steps via LLM

Chrome Extension

Built with WXT (Svelte 5). Runs on the user’s machine. When it receives a push notification:

  1. Opens a browser tab and executes the automation steps
  2. Streams events back to the runner via WebSocket

Web App (dashboard)

Provides account management, API key generation, run history, device management, and billing.

Data flow for a single run

  1. POST /query → runner creates a Run record in the database
  2. Runner sends web push to the device’s extension
  3. Extension wakes up, connects to runner via WebSocket
  4. Runner sends the prompt to the LLM → gets a plan (steps to execute)
  5. Extension executes each step in Chrome, reports progress
  6. Runner forwards progress events to the client
  7. On completion, runner stores the result and sends the terminal event

Auth flow

  1. User signs up on the web app (magic link or OAuth)
  2. Generates an API key from the dashboard
  3. SDK/CLI uses the API key as Bearer token
  4. Runner validates the key, resolves the user, checks budget
  5. Extension is paired to the user’s account via device registration