Skip to main content
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

Uplink Architecture Diagram

​
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 session = await uplink.session('<project-api-key>', {
  projectId: '<project-id>',
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)
Key responsibilities:
  • 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. 
// Get all connected workers
const workers = client.workers()

// Or listen for workers as they connect
client.on('worker-connected', (worker) => {
  console.log('Worker connected:', worker.address)
})

// Get device information from a worker
const worker = workers[0]
const info = await worker.getDeviceInfo()
// { deviceModel, platform, platformVersion, deviceType }
Device characteristics:
  • 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()
Browser characteristics:
  • 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()
Page characteristics:
  • 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
Navigation rules:
  • 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 authenticated connection that ties everything together. Sessions are created programmatically using your API key and provide the communication channel between your code and the devices. 
// Session creation
const session = await uplink.session('<project-api-key>', {
  projectId: '<project-id>',
  include: { ecdsa: true, ecdh: true }
})
Session properties:
  • Created using API keys from your Uplink Console
  • Scoped to specific projects for organization
  • Multiple devices can connect to a single session
  • Sessions persist until the client connection is closed

​
Common patterns

​
Single device automation

const session = await uplink.session('<project-api-key>', {
  projectId: '<project-id>',
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)
const browser = await client.launch()  // Uses first available device
const page = await browser.newPage()

await page.goto('https://example.com')

​
Multi-device automation

const session = await uplink.session('<project-api-key>', {
  projectId: '<project-id>',
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)

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

Sessions & auth

Learn about session management

Device management

Managing multiple devices

Page API

Explore page automation methods

Client API

Full Client API reference