> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Anti-Detection Playbook

> How to avoid CAPTCHAs and bot detection in Notte Sessions

<Tip>
  STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).

  Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.

  Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.

  Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.

  SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
</Tip>

### Resolving Bot Detection Issues

Bot detection is a common challenge for web agents. This guide provides strategies to bypass these detection mechanisms using Notte's stealth configuration options.

Common Bot Detection Challenges:

* Accessing e-commerce sites with anti-bot measures
* Scraping content from news or social media platforms
* Interacting with banking or financial websites
* Accessing sites with geographic restrictions

### Stealth Configuration Strategies

#### 1. Proxy Configuration

Proxies are one of the most effective ways to bypass bot detection. Different proxy configurations can help you appear as legitimate traffic from various locations.

#### Using Default Proxies

Enable Notte's built-in residential proxies for better anonymity:

{/* @sniptest testers/sessions/default_proxy.py */}

```python default_proxy.py theme={null}
from notte_sdk import NotteClient

client = NotteClient()

# Start a session with built-in proxies
with client.Session(proxies=True) as session:
    _ = session.observe(url="https://www.notte.cc/")
```

#### Country-Specific Proxies

For sites with geographic restrictions, use proxies from specific countries:

{/* @sniptest testers/sessions/country_proxy.py */}

```python country_proxy.py theme={null}
from notte_sdk.types import NotteProxy

proxies = NotteProxy.from_country("fr")
```

### 2. Browser Type Selection

Different browsers have varying levels of detection resistance. Experiment with different browser types for your specific use case:

{/* @sniptest testers/guides/browser_type_selection.py */}

```python browser_type_selection.py theme={null}
from typing import Literal

from notte_sdk import NotteClient

client = NotteClient()

# Try different browser types
BrowserType = Literal["chromium", "chrome"]
browsers: list[BrowserType] = ["chromium", "chrome"]
for browser in browsers:
    with client.Session(browser_type=browser, proxies=True, solve_captchas=True) as session:
        result = session.observe(url="https://example.com")
        print(f"Success with {browser}")
```

<Tip>
  `chromium` is the default browser type but is the most easily detected.
</Tip>

### 3. CAPTCHA Solving

Enable automatic CAPTCHA solving for sites that use these challenges:

{/* @sniptest testers/sessions/solve_captchas.py */}

```python solve_captchas.py theme={null}
from notte_sdk import NotteClient

client = NotteClient()
with client.Session(solve_captchas=True, open_viewer=True) as session:
    # Navigate to a page with a CAPTCHA
    agent = client.Agent(session=session, max_steps=5)
    resp = agent.run(
        task=("Try to solve the CAPTCHA using internal tools. If you fail, try to solve it manually."),
        url="https://www.google.com/recaptcha/api2/demo",
    )
```

<Warning>
  Not all CAPTCHA types are supported. Some complex CAPTCHAs may still require manual intervention.
</Warning>

## Complete Stealth Configuration Example

Here's a comprehensive example combining all stealth techniques:

{/* @sniptest testers/sessions/stealth_configuration.py */}

```python stealth_configuration.py theme={null}
from notte_sdk import NotteClient

client = NotteClient()

# Example stealth configuration
# this is just one possible configuration, with an obvious fingerprint
# rotating those values will raise your chances
with client.Session(
    solve_captchas=True,
    proxies="us",
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    viewport_width=1920,
    viewport_height=1080,
) as session:
    result = session.observe(url="https://example.com")
    print("Success with fallback configuration")
```

## Troubleshooting Tips

1. **Start Simple**. Begin with basic configurations and gradually add complexity:
   * Try `proxies=True` first
   * Add `solve_captchas=True` if needed
   * Experiment with different `browser_type` values
   * Add custom `user_agent` if still detected
2. **Test Incrementally**. Test each configuration change individually to identify what works:
3. **Monitor for Patterns**. Keep track of which configurations work for different types of sites:
   * E-commerce sites often respond well to residential proxies
   * Social media sites may require specific user agents
   * Banking sites may need country-specific proxies

## Best Practices

1. **Rotate Configurations**: Don't rely on a single configuration: it makes it easier to track you
2. **Monitor Success Rates**: Verify which configurations work best for different site types
3. **Respect Rate Limits**: Implement delays between requests to avoid triggering rate limiting
4. **Keep Configurations Updated**: Bot detection methods evolve, so regularly test and update your configurations