Home

Getting Started

Install the SDK, configure your API key, and launch your first stealth browser session in under 5 minutes.

Prerequisites

  • Node.js 18+ or Bun 1.0+
  • A SessionKit API key (get one free)
  • Playwright or Puppeteer (for browser control)

Installation

npm install @sessionkit/sdk

pnpm add @sessionkit/sdk

bun add @sessionkit/sdk

Configuration

Set your API key as an environment variable:

export SESSIONKIT_API_KEY=sk_live_abc123...

Or pass it directly when initializing the client:

import { SessionKit } from '@sessionkit/sdk'

const sk = new SessionKit({
  apiKey: 'sk_live_abc123...',
  baseUrl: 'https://api.sessionkit.dev', // optional, defaults to production
})

Security Note: Never commit API keys to version control. Use environment variables or a secrets manager.

Launch Your First Session

import { SessionKit } from '@sessionkit/sdk'
import { chromium } from 'playwright'

const sk = new SessionKit({ apiKey: process.env.SESSIONKIT_API_KEY })

async function main() {
  // Create a stealth session with a US residential proxy
  const session = await sk.sessions.create({
    proxy: {
      type: 'residential',
      country: 'US',
      sticky: true,
    },
    stealth: 'max',
    fingerprint: 'auto',
    timeout: 300, // 5 minutes
  })

  console.log(`✓ Session created: ${session.id}`)
  console.log(`  CDP URL: ${session.cdpUrl}`)
  console.log(`  Proxy: ${session.proxy.type} (${session.proxy.country})`)
  console.log(`  Expires: ${session.expiresAt}`)

  // Connect Playwright to the remote browser
  const browser = await chromium.connectOverCDP(session.cdpUrl)
  const context = browser.contexts()[0]
  const page = context.pages()[0] || await context.newPage()

  // Navigate and interact
  await page.goto('https://httpbin.org/ip')
  const content = await page.textContent('body')
  console.log(`\n✓ Page content:\n${content}`)

  // Clean up
  await browser.close()
  await sk.sessions.destroy(session.id)
  console.log(`\n✓ Session destroyed`)
}

main().catch(console.error)

What Happens Under the Hood

When you call sessions.create():

  1. Proxy allocation — A proxy is assigned from the requested pool (residential/datacenter/ISP)
  2. Fingerprint generation — A realistic browser fingerprint is generated (or loaded from a profile)
  3. Browser launch — A Chromium instance starts with stealth patches applied
  4. CDP exposure — The Chrome DevTools Protocol endpoint is exposed via a secure WebSocket URL
  5. Health monitoring — The session is monitored for crashes and auto-recovered if needed
sequenceDiagram
    participant App as Your App
    participant API as SessionKit API
    participant PM as Proxy Manager
    participant FP as Fingerprint Engine
    participant BP as Browser Pool

    App->>API: POST /v1/sessions
    API->>PM: Allocate proxy
    PM-->>API: proxy config
    API->>FP: Generate fingerprint
    FP-->>API: fingerprint config
    API->>BP: Launch browser
    BP-->>API: CDP URL
    API-->>App: { id, cdpUrl, proxy, fingerprint }

Next Steps