Building a Worker

How to build a custom worker that drives browser sessions via the Passage protocol.

Overview

A worker connects to a session via WebSocket and sends Playwright-like commands to automate a browser running on the user’s device.

Getting started

1. Create a session via the Platform API
2. Connect to the session WebSocket with the worker token
3. Send commands and process results
4. Yield to the user when interaction is needed
5. Complete or fail the session

Example: Basic automation

const ws = new WebSocket(`wss://sessions.passage.dev/sessions/${sessionId}/ws?role=worker&token=${workerToken}`)
 
ws.send(JSON.stringify({ type: 'worker.hello' }))
 
// Navigate to login page
ws.send(JSON.stringify({
  type: 'worker.command',
  command: { action: 'navigate', url: 'https://example.com/login' }
}))
 
// Wait for command result...
 
// Yield to user for authentication
ws.send(JSON.stringify({
  type: 'worker.yield_to_user',
  conditions: [{ type: 'url', pattern: 'https://example\\.com/dashboard.*' }]
}))
 
// Wait for yield result...
 
// Complete the session
ws.send(JSON.stringify({ type: 'worker.complete', result: { ... } }))

Best practices

• Always handle command errors gracefully
• Use yieldToUser for any step requiring user input
• Set appropriate timeouts for yields
• Complete or fail the session explicitly

Next steps

• Protocol: Commands — Full command reference
• Yield to User — Condition types and behavior