Quickstart

Prerequisites:

Node.js version 16 or higher
An Uplink account (sign up on Uplink Console)
A mobile device with the Connect app installed, or your own app with the SDK integrated

This guide will walk you through setting up your first Uplink automation session.

Step 1: Install the JavaScript SDK

Install the Uplink SDK in your project:

npm install @uplink-code/uplink

Optional: AI Automation

For AI-powered automation with natural language instructions:

npm install @uplink-code/ai

See the AI Automation guide to learn more.

Step 2: Get your credentials

Get your API key

Navigate to Settings → API Keys in Uplink Console. Copy your project API key.

Get your project ID

In Settings → Projects, find and copy your project ID.

Keep your API key secure. Never commit it to source control or expose it in client-side code.

Step 3: Create a session

Create a session programmatically to get connection URLs for your devices:

import uplink from '@uplink-code/uplink'

const session = await uplink.session(process.env.UPLINK_API_KEY, {
  include: { ecdsa: true, ecdh: true }
})

console.log('Session created:', session.sessionId)
console.log('QR URL for Connect app:', session.qrUrl)
console.log('Session URL for custom SDK:', session.sessionUrl)

The session object contains:

sessionId: Unique identifier for this session
sessionUrl: WebSocket URL for custom SDK integration
qrUrl: URL that encodes connection info for the Connect app
keys: Optional cryptographic keys (if requested)

Step 4: Connect a device

You have two options for connecting devices to your session:

Connect App (Whitelabel)
Custom SDK Integration

Use Uplink’s whitelabel Connect app by presenting a QR code to your users:

Display QR code

Display the session.qrUrl as a QR code in your application. You can use any QR code library like qrcode or react-qr-code:

import QRCode from 'qrcode'

// Generate QR code image
const qrCodeImage = await QRCode.toDataURL(session.qrUrl)

// Display in your UI
// <img src={qrCodeImage} alt="Scan to connect" />

User scans QR code

Your user scans the QR code with their device camera. This opens the Uplink Connect app (iOS App Clip or Android instant app)

Device connects

The device automatically connects to your session as a worker

No installation required! The Connect app opens automatically via iOS App Clip or Android deeplink when users scan the QR code.

Own the complete UI experience by integrating the Uplink SDK into your own mobile app:

Add SDK to your app

Follow the mobile SDK integration guide for iOS or Android

Pass session URL to device

Deliver the session.sessionUrl to your mobile app through your own means (push notification, deep link, API call, etc.)

Connect in your app

Use the Uplink SDK in your mobile app to connect to the session URL.

With custom SDK integration, you control the entire user experience and can integrate Uplink into your existing mobile app.

Step 5: Run your first automation

Create a new JavaScript file and add the following code:

import uplink from '@uplink-code/uplink'

async function main() {
  // Create and connect to your session
  const session = await uplink.session('<project-api-key>', {
    include: { ecdsa: true, ecdh: true }
  })

  const client = await uplink.client.fromSession(session)

  console.log('Connected to Uplink!')

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

  // Navigate to a website
  await page.goto('https://example.com')
  console.log('Navigated to example.com')

  // Get the page title
  const title = await page.evaluate(() => document.title)
  console.log('Page title:', title)

  // Take a screenshot
  const screenshot = await page.screenshot()
  console.log('Screenshot captured!')

  // Clean up
  await page.close()
  await browser.close()
  await client.close()

  console.log('Done!')
}

main().catch(console.error)

Replace <project-api-key> and <project-id> with your credentials from the Console (or use environment variables as shown), then run:

node your-script.js

What’s next?

Core concepts

Learn about devices, browsers, and pages

Sessions

Understand session management and authentication

API reference

Explore the full JavaScript SDK API

Device management

Learn how to manage multiple devices

Example use cases

Once you’re comfortable with the basics, try these common automation scenarios:

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

// User logs in on their device (handles 2FA, authentication, etc.)
await page.waitForAuthentication(
  async (page) => {
    const url = await page.url()
    return url.includes('/dashboard')
  },
  { timeout: 120000 }
)

// Now automate actions in the authenticated session
await page.click('#export-button')

Extract data from a page

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

// Manual extraction
const products = await page.evaluate(() => {
  return Array.from(document.querySelectorAll('.product')).map(el => ({
    name: el.querySelector('.name').textContent,
    price: el.querySelector('.price').textContent
  }))
})
console.log(products)

// Or use AI extraction with type safety (requires @uplink-code/ai)
import { z } from 'zod'

const result = await page.extract(
  'Extract all products with name and price',
  z.object({
    products: z.array(z.object({
      name: z.string(),
      price: z.number()
    }))
  })
)
console.log(result.data.products) // Fully typed!

AI-powered form filling

// Requires: npm install @uplink-code/ai
import ai from '@uplink-code/ai'

const agent = ai.createAgent({
  provider: 'anthropic',
  options: {
    apiKey: process.env.ANTHROPIC_API_KEY
  }
})

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

const client = await uplink.client.fromSession(session, { agent })
const browser = await client.launch()
const page = await browser.newPage()

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

// Let AI fill out the form
await page.act('Fill in name with "John Doe" and email with "john@example.com"')
await page.act('Click the submit button')

Monitor network requests

await page.on('xhr', async (event) => {
  const request = event.data
  if (request.url.includes('/api/')) {
    console.log('API call:', request.method, request.url)
    if (request.response) {
      console.log('Status:', request.response.status)
    }
  }
})

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

Introduction

Fundamentals

MCP Server

Step 1: Install the JavaScript SDK

Optional: AI Automation

Step 2: Get your credentials

Step 3: Create a session

Step 4: Connect a device

Step 5: Run your first automation

What’s next?

Core concepts

Sessions

API reference

Device management

Example use cases

​Step 1: Install the JavaScript SDK

​Optional: AI Automation

​Step 2: Get your credentials

​Step 3: Create a session

​Step 4: Connect a device

​Step 5: Run your first automation

​What’s next?

Core concepts

Sessions

API reference

Device management

​Example use cases

Step 1: Install the JavaScript SDK

Optional: AI Automation

Step 2: Get your credentials

Step 3: Create a session

Step 4: Connect a device

Step 5: Run your first automation

What’s next?

Example use cases