Python SDK
The Python SDK lets you manage Incogniton profiles, cookies, and run full browser automation from Python 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 Python 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.
- Python 3.8+ installed on your machine.
The SDK requires the Incogniton desktop app to be running locally. API calls will not work if the app is closed.
Installation
To get started with the Python SDK, install it with your preferred tool. We show pip, pipenv, and poetry.
Install Python SDK
pip install incogniton
How to Use the SDK
The Incogniton Python 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.
All SDK calls run locally on your machine — No API tokens or extra authentication required.
SDK Usage Examples
Use the API client for profile lifecycle and cookies. The SDK is async—await every operation that talks to the app.
A. Automate with Playwright
Attach Playwright (or Selenium) to the running, profile-bound browser via CDP/WebDriver. This example shows Playwright.
Browser Automation with Playwright
import asyncio
from incogniton import IncognitonClient, IncognitonBrowser
async def main():
client = IncognitonClient()
profile_id = "your-profile-id"
# Ensure the profile's browser is running
await client.profile.launch(profile_id)
# Controller bound to that profile
browser = IncognitonBrowser(client, profile_id=profile_id, headless=True)
# Establish CDP session → Playwright Browser
pw_browser = await browser.start_playwright()
page = await pw_browser.new_page()
await page.goto("https://example.com")
await page.screenshot(path="example.png")
# Clean shutdown (frees resources)
await browser.close(pw_browser)
# Optionally stop the profile/browser
await client.profile.stop(profile_id)
if **name** == "**main**":
asyncio.run(main())
B. Switch Proxies
Update a profile’s proxy and relaunch to apply.
Switch proxy
import asyncio
from incogniton import IncognitonClient
async def main():
client = IncognitonClient()
pid = "your-profile-id"
await client.profile.switch_proxy(pid, {
"type": "http", "host": "proxy.example.com", "port": 8080,
"username": "user", "password": "pass"
})
await client.profile.stop(pid)
await client.profile.launch(pid)
if __name__ == "__main__":
asyncio.run(main())
C. Get Profile Information
Read one profile, list all, and check status.
Get profile info
import asyncio
from incogniton import IncognitonClient
async def main():
client = IncognitonClient()
pid = "your-profile-id"
profile = await client.profile.get(pid)
print(profile.get("name"), profile.get("id"))
all_profiles = await client.profile.list()
print("Total:", len(all_profiles))
status = await client.profile.get_status(pid)
print("Status:", status)
if __name__ == "__main__":
asyncio.run(main())
D. Browser Automation usage example
Attach Playwright (or Selenium) to the running, profile-bound browser via CDP/WebDriver. This example shows Playwright.
Browser Automation Example
import asyncio
from incogniton import IncognitonBrowser
async def main():
profile_id = "your-profile-id"
browser = IncognitonBrowser(profile_id=profile_id, headless=True)
pw_browser = await browser.start_playwright()
page = await pw_browser.new_page()
await page.goto("https://example.com")
await page.screenshot(path="example.png")
print("Screenshot saved as example.png")
await browser.close(pw_browser)
if __name__ == "__main__":
asyncio.run(main())
Headless mode
Headless mode avoids rendering a visible UI, which reduces CPU/GPU usage and speeds up high-volume tasks.
Run in headless mode
from incogniton import IncognitonBrowser
browser = IncognitonBrowser(client, profile_id="your-profile-id", headless=True)
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 or Selenium.
[Your Python Script] ──(async/await)──> [Incogniton SDK]
│
▼
Local API @ http://localhost:35000
│
CDP / WebDriver bridge (Playwright/Selenium)
▼
[Profile-Bound Incogniton Browser (Chromium)]
All operations are async. Chain actions with await to keep
control flow predictable and to surface errors promptly.
IncognitonClient — Reference
Use Incogniton Client for local API actions: profiles, cookies, and starting automation-ready sessions.
Configuration:
| Option | Purpose |
|---|---|
base_url | Local API address (default http://localhost:35000). |
port | Convenience override for the local API port. |
timeout | Request timeout for client calls (if supported). |
Profile Operations (client.profile)
High-level lifecycle and metadata management.
| Method | What it does |
|---|---|
client.profile.list() | List all browser profiles. |
client.profile.get(profile_id) | Get a specific profile by ID. |
client.profile.add(create_request) | Create a new profile. |
client.profile.update(profile_id, request) | Update an existing profile. |
client.profile.switch_proxy(profile_id, proxy) | Update a profile’s proxy settings. |
client.profile.launch(profile_id) | Launch the profile locally (starts the browser). |
client.profile.launch_force_local(profile_id) | Launch using only local data. |
client.profile.launch_force_cloud(profile_id) | Launch with a fresh cloud sync. |
client.profile.get_status(profile_id) | Check current profile status/readiness. |
client.profile.stop(profile_id) | Stop the running profile/browser. |
client.profile.delete(profile_id) | Delete a profile. |
Cookie Operations (client.cookie)
Manage cookies without opening a browser.
| Method | What it does |
|---|---|
client.cookie.get(profile_id) | Get all cookies for a profile. |
client.cookie.add(profile_id, cookies) | Add cookies to a profile. |
client.cookie.delete(profile_id) | Delete all cookies for a profile. |
Automation Operations (client.automation)
Prepare sessions and get connection endpoints.
| Method | What it does |
|---|---|
client.automation.launch_puppeteer(profile_id) | Launch for Puppeteer; returns a DevTools URL. |
client.automation.launch_puppeteer_custom(profile_id, custom_args) | Same, with extra Chromium flags. |
client.automation.launch_selenium(profile_id) | Launch for Selenium; returns a WebDriver URL. |
client.automation.launch_selenium_custom(profile_id, custom_args) | Same, with custom ChromeOptions/flags. |
Note: In all method signatures above, profile_id
refers to the profile_id, the unique identifier for your Incogniton browser
profile.
IncognitonBrowser — Reference
Use Incogniton Browser to attach Playwright/Selenium to a running, profile-bound browser. Prefer reusing a single controller per worker.
Configuration:
| Option | Purpose |
|---|---|
profile_id | Which Incogniton profile to launch/attach. |
headless | Run without a visible window (default False). |
custom_args | Extra Chromium flags (e.g. --no-sandbox). |
launch_timeout | Max time to wait for readiness (ms). |
Methods:
| Method | What it does |
|---|---|
browser.start_playwright() | Return a connected Playwright Browser (CDP). |
browser.start_selenium() | Return a connected Selenium WebDriver. |
browser.close(instance) | Close a single Playwright/Selenium instance. |
browser.close_all([instances...]) | Close multiple Playwright instances in parallel. |
Troubleshooting & FAQs
Manage fingerprinted, proxy-aware Chromium profiles on your machine and automate them with Playwright or Selenium. Typical uses include scraping, QA tests, and data collection where consistent browser identity and isolation matter.
Choose Playwright for modern, async-first automation, rich waiting primitives, and fast parallelism. Choose Selenium if your tooling, infrastructure, or team standards already rely on WebDriver. Both attach to the same profile-bound browser launched by Incogniton.
Yes. You can read, add, and delete cookies on a profile directly through the SDK. This is useful for restoring authenticated sessions or wiping state between test runs.
Run headless for CI to reduce resource usage and improve stability; switch to headed locally for debugging. In containers or restricted environments, ensure shared memory and sandboxing settings are compatible, and preinstall browsers if your pipeline requires it.
Common causes include the Incogniton app being closed, firewall rules blocking localhost, or an overridden port/base URL that doesn’t match your app settings. Confirm the app is running on the same machine and that local networking is permitted.
Stop and relaunch the profile, then try forcing a local or cloud launch (See API Reference) if sync is slow. Check status for hints (e.g., launching, running, stopped). Ensuring only one automation session attaches at a time also helps avoid contention.
Yes. Launch separate profiles and attach distinct automation sessions, then coordinate them with asyncio. Be mindful of machine resources (CPU/RAM/network) and apply backpressure or concurrency limits to keep runs stable.
Next Steps:
How-to Guides
Step-by-step guides for common automation and integration tasks.
Node.js SDK
Prefer JavaScript/TypeScript? Use the same capabilities with async/await and Playwright/Puppeteer.
Need help? Join our community or contact support.