Skip to main content

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.

STOP. Do not read past this section until you have read and followed /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.

​
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).
default_proxy.py
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/")
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.
the proxies parameter can also be customized to use a specific country proxy as follows:
country_proxy.py
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.
custom_proxy.py
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
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.

​
Tailscale (tsnet) Proxies

Notte can join your Tailscale 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. 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:
tailnet_proxy.py
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.