Proxies

Route your automation traffic with precision & control

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.

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
• Reach private services: Route the session through your Tailscale tailnet

Each session uses a single proxy.

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.

Built-in proxies are on by default (proxies=True) and exit in the US unless you pick a country. Set proxies=False to disable them.

default_proxy.py

from notte_sdk import NotteClient

client = NotteClient()

# Start a session with built-in proxies
with client.Session(proxies=True) as session:
    result = session.execute(type="goto", url="https://www.notte.cc/")
    observation = session.observe()

ERR_TUNNEL_CONNECTION_FAILED indicates either a temporary proxy hiccup or a site unsupported by our built-in proxies. Please try again or email [e-mail].

To exit from a specific country, pass its two-letter code, or an explicit NotteProxy:

country_proxy.py

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)

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

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[ProxySettings] = [proxy_settings]
with client.Session(proxies=proxies) as session:
    # use your session
    pass

Ensure that your proxy server is reachable from the internet and the provided credentials are correct before creating a session. We 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. In your tailnet policy file, add tag:notte to tagOwners.
2. Under Settings → Trust credentials, create an OAuth client with write access to the auth_keys scope and tag it with tag:notte only. Tailscale requires every auth key the client creates to carry exactly the client’s tags, so any other tag on the client makes Notte’s sessions fail to join.
3. In the Access controls tab, grant tag:notte access to the resources you want to reach from the session.

You can then give Notte the client in one of two ways.

Option 1: Connect Tailscale in the console

Open Settings → Integrations in the Notte console and add the OAuth client ID and secret. Notte checks them with Tailscale before saving and stores the secret encrypted. Each workspace has one Tailscale connection, and only workspace admins can add or remove it.

Sessions in that workspace then use it without any credentials in your code:

tailnet_proxy_console.py

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

client = NotteClient()

# No credentials: uses the Tailscale OAuth client connected to your workspace
tailnet_proxy = TailnetProxy()

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

Option 2: Pass the OAuth credentials in code

Pass the client ID and secret when creating the session. This works without a console connection, and credentials passed here take precedence over it:

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:
    result = session.execute(type="goto", url="https://grafana.your-tailnet.ts.net/")
    screenshot = session.observe().screenshot.bytes()

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

Exit nodes

By default only tailnet addresses go through your tailnet, and public sites are reached from Notte’s network. Set exit_node to send the session’s public traffic out through one of your own devices instead, such as your laptop, so sites see your connection’s IP address. It works with both options, for example TailnetProxy(exit_node="my-laptop").

Name the device by hostname, MagicDNS name, or Tailscale IP. It must be advertised and approved as an exit node, and your policy must let tag:notte reach autogroup:internet. If the device is offline or not usable as an exit node, the session fails to start rather than falling back to Notte’s network.

Fixed egress IP

If a site needs to see the same IP address on every session, for example because it allowlists your IP, run an exit node on a machine with a fixed public IP and point exit_node at it. All of the session’s public traffic then leaves from that address.

Usage Measurement

Proxy usage is measured by the total amount of data transferred through the proxy, for both built-in and custom proxies. 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.

Billing

Proxy bandwidth is billed on every session that uses a proxy, whether it is a built-in Notte proxy or your own custom proxy (type: "external"). Sessions without a proxy are not billed for bandwidth.

Proxy	Rate
Built-in proxies	$10 per GB
Custom proxies (Startup plan)	$3 per GB (30% of the proxy rate), on top of what your proxy provider charges

Bandwidth is counted as request plus response bytes, rounded up to the next MB per session.

For a custom proxy, the full bandwidth is first recorded as a Proxy charge at $10 per GB. When the session closes, a BYO Proxy Credit refunds 70% of it on the Startup plan, so the net fee is 30%. The credit is final, and both lines appear in your usage and billing view.

Enterprise plans can have custom terms. See pricing or contact us for custom terms.