How It Works

BrowserWorker bridges your automation tools (n8n, cURL, Python, etc.) with real Chrome browsers running anywhere in the world.

Architecture

┌─────────────┐     POST /v1/      ┌──────────────┐
│  Your App   │ ──────────────────► │  API Server  │
│  n8n/cURL   │ ◄────────────────── │              │
└─────────────┘     JSON Response   └──────┬───────┘
                                           │
                                    Real-time messaging
                                           │
                                    ┌──────┴───────┐
                                    │   Chrome      │
                                    │   Extension   │
                                    │   (Worker)    │
                                    └──────────────┘

Components

API Server (api.browserworker.app)

• Receives HTTP requests with browser automation actions
• Authenticates requests via Bearer tokens
• Selects an available worker (or a specific one)
• Dispatches tasks to workers in real-time
• Waits for results and returns them synchronously

Chrome Extension (Worker)

• Installed on any Chrome browser
• Listens for tasks from the API server in real-time
• Executes actions in real browser tabs (clicks, typing, screenshots, etc.)
• Reports results back to the server

Dashboard (my.browserworker.app)

• Manage your account and workers
• View worker status (online/offline/busy)
• Access API keys and bearer tokens
• Test API calls with the built-in API Playground

Request Lifecycle

1. You send a POST request to https://api.browserworker.app/v1/ with your actions
2. Server authenticates your bearer token
3. Server selects a worker — either auto-selects an available one or targets a specific workerId
4. Server claims the worker atomically (prevents race conditions with concurrent requests)
5. Server dispatches the task to the selected worker in real-time
6. Extension picks up the task instantly
7. Extension executes each action sequentially in the browser
8. Extension reports the result back to the server
9. Server returns the response to you

The entire flow is synchronous from your perspective — you send a request and get back a response with the results, just like Puppeteer or Playwright.

Worker Status

Status	Meaning
online	Available and ready for tasks
busy	Currently executing a task
reserve	Reserved by an active session
offline	Not connected (extension closed or disconnected)

Workers send a heartbeat every 60 seconds. If a worker misses heartbeats for 2 minutes, it's automatically marked as offline.