Uplink’s architecture revolves around four core concepts: Clients, Devices (Workers), Browsers, and Pages. Understanding how these components work together is essential for effective automation.
Architecture overview
Client
The Client is your main entry point for Uplink automation. It manages the WebSocket connection to the Uplink relay server and provides methods for launching browsers and managing devices.
import uplink from '@uplink-code/uplink'
const client = await uplink.client.connect('wss://relay.uplink.build/session/<jwt>')
- Maintaining the WebSocket connection to the session
- Managing device connections
- Launching and connecting to browsers
- Emitting device connection events
A single Client can manage multiple devices simultaneously, making it easy to run parallel automation across different mobile devices.
Devices (Workers)
A Device (also called a Worker) represents a physical mobile device connected to your session. Each device can host multiple browser instances.
// Wait for a device to connect
const device = await client.worker()
// Get all connected devices
const devices = client.workers()
// Get device information
const info = await device.getDeviceInfo()
// { deviceModel, platform, platformVersion, deviceType }
- Each device has a unique address for identification
- Devices can be iOS or Android
- Multiple browsers can run on a single device
- Devices connect through either the SDK or Connect app
Device lifecycle events
client.on('worker-connected', (device) => {
console.log('New device:', device.address)
})
client.on('worker-disconnected', (device) => {
console.log('Device disconnected:', device.address)
})
Browsers
A Browser represents a browser instance running on a device. Each browser can have multiple pages (tabs) open simultaneously.
// Launch a new browser
const browser = await client.launch()
// Or launch on a specific device
const browser = await device.launch()
// Connect to an existing browser
const browser = await client.connect('browser-handle')
// List all browsers on a device
const browsers = await client.browsers()
- Each browser runs in its own isolated context
- Browsers persist until explicitly closed
- You can reconnect to browsers by their handle
- Multiple browsers can run on the same device
Pages
A Page represents a browser tab or window. This is where most of your automation happens—navigation, interaction, JavaScript execution, and more.
// Create a new page
const page = await browser.newPage()
// Navigate and interact
await page.goto('https://example.com')
await page.click('#button')
const title = await page.evaluate(() => document.title)
// List all pages in a browser
const pages = await browser.pages()
- Pages are isolated from each other
- Each page has its own JavaScript context
- Pages can be shown/hidden independently
- Event listeners can be attached to monitor page activity
Hierarchy and relationships
The hierarchy of Uplink components:
Client
└─ Device (Worker)
└─ Browser
└─ Page
- You can access browsers from either the Client or Device level
- Pages are always accessed through their parent Browser
- Device connections are managed at the Client level
Sessions
A Session is the WebSocket connection that ties everything together. Sessions are authenticated using JWT tokens and provide the communication channel between your code and the devices.
// Session URL format
wss://relay.uplink.build/session/<jwt-token>
- Tokens are generated from your Uplink Console
- Sessions can have permission scopes and expiration times
- Multiple devices can connect to a single session
- Sessions persist until the connection is closed
Common patterns
Single device automation
const client = await uplink.client.connect('wss://...')
const browser = await client.launch() // Uses first available device
const page = await browser.newPage()
await page.goto('https://example.com')
Multi-device automation
const client = await uplink.client.connect('wss://...')
client.on('worker-connected', async (device) => {
const browser = await device.launch()
const page = await browser.newPage()
await page.goto('https://example.com')
})
Managing multiple pages
const browser = await client.launch()
const page1 = await browser.newPage()
const page2 = await browser.newPage()
await page1.goto('https://example.com')
await page2.goto('https://google.com')
// Switch between pages
await page1.show() // Bring to foreground
await page2.show() // Switch to page2
Next steps
