Skip to main content
The Client class is your main entry point for Uplink automation. It manages the WebSocket connection to the Uplink relay server and provides methods for device and browser management.

​
Connection

Connects to an Uplink session via WebSocket. 
uplink.client.connect(url: string | URL): Promise<Client>
Parameters:
  • url: WebSocket URL in the format wss://relay.uplink.build/session/<jwt>
Returns: Promise<Client> - Connected client instance Example: 
import uplink from '@uplink-code/uplink'

const client = await uplink.client.connect('wss://relay.uplink.build/session/<jwt>')
console.log('Connected to Uplink')

​
Browser operations

​
client.launch()

Launches a new browser on a device. If no device address is provided, uses the first available device. 
client.launch(address?: Address): Promise<Browser>
Parameters:
  • address (optional): Device address to launch browser on
Returns: Promise<Browser> - New browser instance Example: 
// Launch on first available device
const browser = await client.launch()

// Launch on specific device
const browser = await client.launch('device-123')

​
client.connect()

Connects to an existing browser by its handle. 
client.connect(handle: string, address?: Address): Promise<Browser>
Parameters:
  • handle: Browser handle identifier
  • address (optional): Device address where browser is running
Returns: Promise<Browser> - Connected browser instance Example: 
const browser = await client.connect('browser-handle-123')

​
client.browsers()

Lists all browsers on a device. 
client.browsers(address?: Address): Promise<Browser[]>
Parameters:
  • address (optional): Device address to query. If not provided, queries first available device.
Returns: Promise<Browser[]> - Array of browser instances Example: 
const browsers = await client.browsers()
console.log(`${browsers.length} browsers running`)

for (const browser of browsers) {
  console.log('Browser:', browser.handle)
}

​
Device operations

​
client.workers()

Returns list of currently connected devices. 
client.workers(): ClientWorker[]
Returns: ClientWorker[] - Array of connected devices Example: 
const devices = client.workers()

console.log(`${devices.length} devices connected`)
devices.forEach(device => {
  console.log('Device address:', device.address)
})

​
client.worker()

Waits for a device to connect and returns it. 
client.worker(address?: Address): Promise<ClientWorker>
Parameters:
  • address (optional): Specific device address to wait for
Returns: Promise<ClientWorker> - Connected device Example: 
// Wait for any device
const device = await client.worker()

// Wait for specific device
const device = await client.worker('device-123')

​
client.terminate()

Terminates a device connection. 
client.terminate(address?: Address): Promise<void>
Parameters:
  • address (optional): Device address to terminate. If not provided, terminates first available device.
Returns: Promise<void> Example: 
await client.terminate('device-123')
Terminating a device closes all browsers running on that device and disconnects it from the session.

​
Connection management

​
client.close()

Closes the client connection and cleans up resources. 
client.close(): Promise<void>
Returns: Promise<void> Example: 
await client.close()
Always call close() when done to properly clean up WebSocket connections and resources.

​
Events

The client emits events for device connection lifecycle.

​
worker-connected

Emitted when a new device connects to the session. 
client.on(event: 'worker-connected', handler: (device: ClientWorker) => void)
Example: 
client.on('worker-connected', (device) => {
  console.log('New device connected:', device.address)
})

​
worker-disconnected

Emitted when a device disconnects from the session. 
client.on(event: 'worker-disconnected', handler: (device: ClientWorker) => void)
Example: 
client.on('worker-disconnected', (device) => {
  console.log('Device disconnected:', device.address)
})

​
Types

​
Address

Device identifier type: 
type Address = string

​
Complete example

import uplink from '@uplink-code/uplink'

async function main() {
  // Connect to session
  const client = await uplink.client.connect('wss://relay.uplink.build/session/<jwt>')

  // Listen for device events
  client.on('worker-connected', (device) => {
    console.log('Device joined:', device.address)
  })

  client.on('worker-disconnected', (device) => {
    console.log('Device left:', device.address)
  })

  // Wait for a device
  const device = await client.worker()
  console.log('Using device:', device.address)

  // Launch browser
  const browser = await client.launch()
  const page = await browser.newPage()

  await page.goto('https://example.com')
  console.log('Page loaded')

  // Cleanup
  await page.close()
  await browser.close()
  await client.close()
}

main().catch(console.error)

ClientWorker

Device-specific operations

Browser

Browser management

Core concepts

Architecture overview

Sessions

Session management