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

Log in to Uplink Console to get your API credentials.
1

Get your API key

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

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, {
  projectId: process.env.UPLINK_PROJECT_ID,
  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:
Use Uplink’s whitelabel Connect app by presenting a QR code to your users:
1

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" />
2

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)
3

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.

​
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>', {
    projectId: '<project-id>',
    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 & auth

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')

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!

// 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>', {
  projectId: '<project-id>',
  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')

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')