Stealth Mode

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Notte sessions include built-in stealth features to help your automations avoid detection by anti-bot systems.

Built-in Stealth Features

All Notte sessions automatically include:

Coherent browser fingerprint - A realistic, recent Chrome desktop fingerprint (user agent, platform, screen, and graphics hardware) that stays internally consistent
Location matching - Timezone, locale, and geolocation follow the session’s proxy exit IP
Residential proxies - On by default (proxies=True). See Proxies
Captcha solving - On by default (solve_captchas=True). See CAPTCHA Solving

Basic Usage

Stealth features are enabled by default. Simply create a session:

from notte_sdk import NotteClient

client = NotteClient()

# The session is automatically stopped when the context manager is exited
with client.Session(idle_timeout_minutes=2) as session:
    status = session.status()
    print(status)

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// The session is automatically stopped when the callback exits.
await client.Session({ idle_timeout_minutes: 2 }).use(async (session) => {
  const status = await session.status();
  console.log(status);
});

Proxy Location

Residential proxies are on by default and exit in the US. Pick a country to match your target site; the fingerprint’s timezone and locale follow it:

from notte_sdk import NotteClient
from notte_sdk.types import NotteProxy, ProxySettings

client = NotteClient()

# Shorthand: pass a country code
session = client.Session(proxies="fr")

# Equivalent explicit form
proxies: list[ProxySettings] = [NotteProxy.from_country("fr")]
session = client.Session(proxies=proxies)

import { NotteClient, type NotteProxy } from 'notte-sdk';

const client = new NotteClient();

// Route the session through a French residential proxy
const proxies: NotteProxy[] = [{ type: 'notte', country: 'fr' }];
const session = client.Session({ proxies });

Advanced Stealth

For sites with sophisticated bot detection, advanced_stealth=True runs the session in Notte’s highest-fidelity browser environment. It is available to approved workspaces; contact hello@notte.cc to enable it.

from notte_sdk import NotteClient

client = NotteClient()

# Advanced Stealth requires approval for your workspace.
with client.Session(advanced_stealth=True, open_viewer=True) as session:
    page = session.page
    page.goto("https://example.com")

Custom User Agents

Keep the generated user agent unless the target requires a specific override. A custom user_agent replaces one part of Notte’s fingerprint and can make it inconsistent with the browser version, platform, or other properties. Test the complete fingerprint before using an override in production.

Stealth Best Practices

1. Use Realistic Behavior

Avoid patterns that look automated:

realistic_behavior.py

import random
import time

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    page = session.page
    page.goto("https://example.com")

    # Bad: Instant actions
    page.click("button")
    page.fill("input", "text")

    # Good: Human-like delays
    page.click("button")
    time.sleep(random.uniform(0.5, 1.5))
    page.fill("input", "text")

2. Rotate Proxies

Use different proxies for different sessions:

rotate_proxies.py

from notte_sdk import NotteClient

client = NotteClient()

# Session 1 with US proxy
with client.Session(proxies="us") as session:
    # automation
    pass

# Session 2 with UK proxy
with client.Session(proxies="gb") as session:
    # automation
    pass

3. Match Viewport to Real Devices

Use common screen resolutions:

from notte_sdk import NotteClient

client = NotteClient()

# Desktop
with client.Session(viewport_width=1920, viewport_height=1080) as desktop:
    pass

# Laptop
with client.Session(viewport_width=1366, viewport_height=768) as session:
    pass

import { NotteClient } from "notte-sdk";

const client = new NotteClient();

// Desktop
const desktop = client.Session({ viewport_width: 1920, viewport_height: 1080 });
await desktop.use(async () => {});

// Laptop
const session = client.Session({ viewport_width: 1366, viewport_height: 768 });
await session.use(async () => {});

4. Combine Multiple Techniques

Layer stealth features for best results:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    proxies=True,
    viewport_width=1920,
    viewport_height=1080,
) as session:
    # Maximum stealth configuration
    pass

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const session = client.Session({
  proxies: true,
  viewport_width: 1920,
  viewport_height: 1080,
});
await session.use(async () => {
  // Maximum stealth configuration
});

Testing Stealth

Test your stealth configuration against detection services: Use a fresh session to compare bot.sannysoft.com, areyouheadless, or Fingerprint. Inspect the browser fingerprint and keep a screenshot or recording of the result. A detector result alone does not guarantee access to your target site.

What Stealth Can’t Do

Stealth features help avoid detection, but they cannot:

❌ Bypass login rate limits (use delays between attempts)
❌ Avoid behavioral analysis (act like a human)
❌ Bypass IP-based blocking (use proxy rotation)
❌ Solve all captchas automatically (use captcha solving)

Stealth + Captcha Solving

Combine stealth with automatic captcha solving for comprehensive protection: Both options are enabled by default. See CAPTCHA Solving for supported challenges and waiting behavior.

Next Steps

Proxies

Configure residential proxies

CAPTCHA Solving

Automatically solve captchas

Session Configuration

All session configuration options

Browser Profiles

Reuse logged-in browser state

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Stealth Mode

Built-in Stealth Features

Basic Usage

Proxy Location

Advanced Stealth

Custom User Agents

Stealth Best Practices

1. Use Realistic Behavior

2. Rotate Proxies

3. Match Viewport to Real Devices

4. Combine Multiple Techniques

Testing Stealth

What Stealth Can’t Do

Stealth + Captcha Solving

Next Steps

Proxies

CAPTCHA Solving

Session Configuration

Browser Profiles

​Built-in Stealth Features

​Basic Usage

​Proxy Location

​Advanced Stealth

​Custom User Agents

​Stealth Best Practices

​1. Use Realistic Behavior

​2. Rotate Proxies

​3. Match Viewport to Real Devices

​4. Combine Multiple Techniques

​Testing Stealth

​What Stealth Can’t Do

​Stealth + Captcha Solving

​Next Steps

Proxies

CAPTCHA Solving

Session Configuration

Browser Profiles

Built-in Stealth Features

Basic Usage

Proxy Location

Advanced Stealth

Custom User Agents

Stealth Best Practices

1. Use Realistic Behavior

2. Rotate Proxies

3. Match Viewport to Real Devices

4. Combine Multiple Techniques

Testing Stealth

What Stealth Can’t Do

Stealth + Captcha Solving

Next Steps