Node.js SDK

The Node.js SDK lets you manage Incogniton profiles, cookies, and run full browser automation from JavaScript/TypeScript by talking to the locally running Incogniton desktop app. Everything stays on your machine—no remote tokens, no cloud roundtrips.

Requirements

Before installing and using the Node.js SDK, ensure you have the following in place:

• Incogniton account — Sign up here if you don’t already have one.
• Incogniton desktop app — Download the app and ensure it’s open and running on your machine.
• At least one browser profile created within the Incogniton app.
• Node.js 16+ installed on your machine.
• Familiarity with using async/await in JavaScript/TypeScript.

Installation

To get started with the Node.js SDK, you first need to install it. The installation process is straightforward and supports npm, yarn, and pnpm package managers.

npm install incogniton

How to Use the SDK

The Incogniton Node.js SDK provides a simple, fully async API for managing browser profiles and automating browsers. Below are common usage examples to help you get started quickly.

API Client usage example

Use the API client for profile lifecycle and cookies. The SDK is fully async—await every operation that hits the app.

import { IncognitonClient } from 'incogniton'

const client = new IncognitonClient()

// Create a profile
const created = await client.profile.add({
  profileData: {
    name: 'My Profile',
    // ...other fields
  },
})

// List profiles
const profiles = await client.profile.list()

// Get a specific profile
const profileId = 'your_profile_id'
const profile = await client.profile.get(profileId)

// Launch (starts a local, profile-bound browser)
await client.profile.launch(profileId)

// Stop when done
await client.profile.stop(profileId)

// ESM assumes "type": "module" — for CommonJS, wrap "await" in an async function.

Browser Automation usage example

Attach Playwright (or Puppeteer) to the running, profile-bound browser via CDP. This example shows Playwright, the Puppeteer variant is below.

import { IncognitonClient, IncognitonBrowser } from 'incogniton'

const client = new IncognitonClient()
const profileId = 'your-profile-id'

// Ensure the profile's browser is running
await client.profile.launch(profileId)

// Controller bound to that profile
const browser = new IncognitonBrowser({
profileId,
headless: true,
})

// Establish CDP session → Playwright Browser
const pwBrowser = await browser.startPlaywright()

const page = await pwBrowser.newPage()
await page.goto('https://example.com')
await page.screenshot({ path: 'example.png' })

// Clean shutdown (frees resources)
await browser.close(pwBrowser)

// Optionally stop the profile/browser
await client.profile.stop(profileId)

Headless mode

When you run automation in headless mode, the browser UI doesn’t open. This reduces resource consumption and speeds up execution, making it ideal for high-volume automation tasks.

import { IncognitonBrowser } from 'incogniton'

const browser = new IncognitonBrowser({
  profileId: 'your-profile-id',
  headless: true, // Enables headless mode
})

SDK Overview

The SDK is a local-first async client. It sends your commands to the Incogniton app’s Local API, which launches profile-bound browsers for automation. The SDK then connects via CDP or WebDriver so you can control pages using automation tools like Playwright, Puppeteer, or Selenium.

[Your JS/TS Script] ──(async/await)──> [Incogniton SDK]
                                      │
                                      ▼
                           Local API @ http://localhost:35000
                                      │
                         CDP / Web Driver bridge (Playwright/Puppeteer/Selenium)
                                      ▼
                [Profile-Bound Incogniton Browser (Chromium)]

IncognitonClient — Reference

Use Incogniton Client for local API actions: profiles, cookies, and starting automation-ready sessions.

Configuration:

Profile Operations (client.profile) High-level lifecycle and metadata management.

Cookie Operations (client.cookie) Manage cookies without opening a browser.

Automation Operations (client.automation) Prepare sessions and get connection endpoints.

IncognitonBrowser — Reference

Use Incogniton Browser to attach Playwright/Puppeteer/Selenium to a running, profile-bound browser. Prefer reusing a single controller per worker

Configuration:

Endpoints & Methods:

Troubleshooting & FAQs

Next Steps:

Need help? Join our community or contact support.