Proxies

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

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

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const session = client.Session({
  proxies: true,
});
await session.use(async () => {
  await session.execute({ type: 'goto', url: 'https://www.notte.cc/' });
  await 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 support@notte.com.

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

from notte_sdk.types import NotteProxy

proxies = NotteProxy.from_country("fr")

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

const proxies: NotteProxy = { type: 'notte', 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, 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

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:

In your tailnet policy file, add tag:notte to tagOwners.
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.
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.

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.

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Overview

Configuration Options

Built-in Proxies

Custom Proxies

Tailscale (tsnet) Proxies

Option 1: Connect Tailscale in the console

Option 2: Pass the OAuth credentials in code

Exit nodes

Usage Measurement

​Overview

​Configuration Options

​Built-in Proxies

​Custom Proxies

​Tailscale (tsnet) Proxies

​Option 1: Connect Tailscale in the console

​Option 2: Pass the OAuth credentials in code

​Exit nodes

​Usage Measurement

Overview

Configuration Options

Built-in Proxies

Custom Proxies

Tailscale (tsnet) Proxies

Option 1: Connect Tailscale in the console

Option 2: Pass the OAuth credentials in code

Exit nodes

Usage Measurement