> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uplink.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with Uplink mobile automation in minutes

<Info>
  **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
</Info>

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:

```bash theme={null}
npm install @uplink-code/uplink
```

### Optional: AI Automation

For AI-powered automation with natural language instructions:

```bash theme={null}
npm install @uplink-code/ai
```

See the [AI Automation guide](/api-reference/ai/overview) to learn more.

## Step 2: Get your credentials

Log in to Uplink Console to get your API credentials.

<Steps>
  <Step title="Get your API key">
    Navigate to **Settings** → **API Keys** in Uplink Console. Copy your project API key.
  </Step>

  <Step title="Get your project ID">
    In **Settings** → **Projects**, find and copy your project ID.
  </Step>
</Steps>

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

## Step 3: Create a session

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

```typescript theme={null}
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:

<Tabs>
  <Tab title="Connect App (Whitelabel)">
    Use Uplink's whitelabel Connect app by presenting a QR code to your users:

    <Steps>
      <Step title="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`:

        ```typescript theme={null}
        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" />
        ```
      </Step>

      <Step title="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)
      </Step>

      <Step title="Device connects">
        The device automatically connects to your session as a worker
      </Step>
    </Steps>

    <Note>
      **No installation required!** The Connect app opens automatically via iOS App Clip or Android deeplink when users scan the QR code.
    </Note>
  </Tab>

  <Tab title="Custom SDK Integration">
    Own the complete UI experience by integrating the Uplink SDK into your own mobile app:

    <Steps>
      <Step title="Add SDK to your app">
        Follow the mobile SDK integration guide for [iOS](https://docs.uplink.build) or [Android](https://docs.uplink.build)
      </Step>

      <Step title="Pass session URL to device">
        Deliver the `session.sessionUrl` to your mobile app through your own means (push notification, deep link, API call, etc.)
      </Step>

      <Step title="Connect in your app">
        Use the Uplink SDK in your mobile app to connect to the session URL.
      </Step>
    </Steps>

    <Tip>
      With custom SDK integration, you control the entire user experience and can integrate Uplink into your existing mobile app.
    </Tip>
  </Tab>
</Tabs>

## Step 5: Run your first automation

Create a new JavaScript file and add the following code:

```typescript theme={null}
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:

```bash theme={null}
node your-script.js
```

## What's next?

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book" href="/fundamentals/core-concepts">
    Learn about devices, browsers, and pages
  </Card>

  <Card title="Sessions" icon="key" href="/sessions">
    Understand session management and authentication
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/overview">
    Explore the full JavaScript SDK API
  </Card>

  <Card title="Device management" icon="mobile" href="/fundamentals/device-management">
    Learn how to manage multiple devices
  </Card>
</CardGroup>

## Example use cases

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

<AccordionGroup>
  <Accordion title="Wait for user login, then automate" icon="right-to-bracket">
    ```typescript theme={null}
    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')
    ```
  </Accordion>

  <Accordion title="Extract data from a page" icon="table">
    ```typescript theme={null}
    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!
    ```
  </Accordion>

  <Accordion title="AI-powered form filling" icon="robot">
    ```typescript theme={null}
    // 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')
    ```
  </Accordion>

  <Accordion title="Monitor network requests" icon="network-wired">
    ```typescript theme={null}
    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')
    ```
  </Accordion>
</AccordionGroup>