> ## 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.

# Proxies

> Route your automation traffic with precision & control

<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>

## Overview

Notte offers a flexible proxy system, enabling you to control how your automation traffic is routed across the internet. Whether you need anonymity, geolocation control, or improved reliability, Notte makes it easy to integrate proxies into your workflows.

## Configuration Options

With Notte, you can:

* Use built-in proxies: Effortlessly route traffic through our managed residential proxies
* Bring your own proxies: Use custom HTTP/HTTPS proxies for greater control over network routing
* Combine multiple proxies: Set custom routing rules to direct traffic through different proxies based on domain or location

Proxies are configured when creating a session through the API or SDK.

## Built-in Proxies

Use Notte's built-in proxies to route traffic through managed, residential proxies. This is the simplest option and requires very little setup.

Setting `proxies=True` will make a best-effort attempt to use a US-based proxy. If nearby US proxies are unavailable, we may route through nearby countries (like Canada).

{/* @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/")
```

<Warning>
  `ERR_TUNNEL_CONNECTION_FAILED` indicates either a temporary proxy hiccup or a site unsupported by our built-in proxies. Please try again or email [support@notte.com](mailto:support@notte.com).
</Warning>

the `proxies` parameter can also be customized to use a specific country proxy as follows:

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

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

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

## Custom Proxies

Notte supports custom proxy configurations, allowing you to route traffic through your own HTTP or HTTPS proxies. This is useful if you need to enforce specific network routing rules, comply with security policies, or optimize performance with a preferred proxy provider.

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

```python custom_proxy.py theme={null}
from notte_sdk import NotteClient
from notte_sdk.types import ExternalProxy, NotteProxy

client = NotteClient()

# Configure custom proxy settings
proxy_settings = ExternalProxy(
    server="http://your-proxy-server:port",
    username="your-username",
    password="your-password",
)

# Start a session with custom proxy
proxies: list[NotteProxy | ExternalProxy] = [proxy_settings]
with client.Session(proxies=proxies) as session:
    # use your session
    pass
```

<Warning>
  Notte validates proxy connections at session creation time. If we are unable to connect to the specified proxy, an error will be thrown. Ensure that your proxy server is accessible and the provided credentials are correct before creating a session. We also do not support all proxy providers.
</Warning>

## Tailscale (tsnet) Proxies

Notte can join your [Tailscale](https://tailscale.com) tailnet directly from within a cloud session, letting the browser reach any private service exposed on your tailnet (internal dashboards, staging environments, MagicDNS hosts) without exposing them to the public internet.

Authentication uses [Tailscale OAuth client credentials](https://tailscale.com/kb/1215/oauth-clients). In your Tailscale admin console:

1. Under **Settings → Trust credentials**, create an OAuth client with write access to the `auth_keys` scope and tag it with `tag:notte`.
2. In the **Access controls** tab, grant `tag:notte` access to the resources you want to reach from the session.

Pass the client ID and secret when creating the session:

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

```python tailnet_proxy.py theme={null}
from notte_sdk import NotteClient
from notte_sdk.types import ProxySettings, TailnetProxy

client = NotteClient()

# Configure a Tailscale tsnet proxy using OAuth client credentials
tailnet_proxy = TailnetProxy(
    oauth_client_id="your-tailscale-oauth-client-id",
    oauth_client_secret="your-tailscale-oauth-client-secret",
)

# Start a session routed through your tailnet
proxies: list[ProxySettings] = [tailnet_proxy]
with client.Session(proxies=proxies) as session:
    _ = session.execute(type="goto", url="https://grafana.your-tailnet.ts.net/")
    _ = session.observe().screenshot.bytes()
```

Once the session is created, you can navigate to any hostname reachable on your tailnet — for example a MagicDNS name like `https://grafana.your-tailnet.ts.net/`.

## Usage Measurement

Proxy usage is measured by the total amount of data transferred through the proxy. This includes:

* Webpage content, downloads, and media files
* HTTP headers, authentication data, and encryption overhead
* Any requests and responses routed through the proxy

Since all traffic must pass through the proxy server before reaching its final destination, every interaction contributes to your total bandwidth usage.