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.

Runnable Node.js examples built on this SDK: incogniton-automation-examples.

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

Incogniton Client Usage Examples

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 examples (Incogniton Client)

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 (Incogniton Browser)

Attach your preferred automation tool (e.g Playwright) 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'

// Controller bound to that profile. startPlaywright() launches the profile itself:
// do not call client.profile.launch() first (launching an open profile fails).
const browser = new IncognitonBrowser({
profileId,
headless: true,
})

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

// Use the profile's persistent default context. pwBrowser.newPage() would create a
// fresh, empty context without the profile's cookies and storage.
const page = await pwBrowser.contexts()[0].newPage()
await page.goto('https://example.com')
await page.screenshot({ path: 'example.png' })
await page.close()

// Graceful stop: lets Chrome flush cookies/storage before the app stops the profile
// (client.profile.stop() terminates the browser process).
const cdp = await pwBrowser.newBrowserCDPSession()
await cdp.send('Browser.close').catch(() => {})
await browser.close(pwBrowser)

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 Reference

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.