Claude Browser Use With Residential Proxies: A Practical Guide

Quick Answer

To use a residential proxy with Claude Browser Use, configure the proxy on the browser that your application runs for Anthropic's browser_toolset_20260801. Claude decides which browser member to call, your executor performs that action in Playwright, and Playwright sends the website traffic through a Proxidize Residential Proxy.

The proxy belongs on Playwright, not in the prompt and not automatically on the Anthropic API client:

That is only the connection pattern. browser_toolset_20260801 is a client toolset, so Anthropic does not provide or operate the browser for this request. Your application still needs an executor that handles every enabled member call, returns valid tool_result blocks, tracks tabs, validates destinations and limits actions. The complete read-focused implementation below adds those pieces.

For a coherent task that visits several related pages, start with a Sticky residential access point and keep one browser context for the task. Rotate between independent tasks, users or markets. A Random access point can be useful for independent observations, but rotating in the middle of a browser session can create an inconsistent combination of IP, cookies and site-side session state.

Responsible-use note: Use browser agents and proxies only for lawful, authorized work. Follow applicable laws, privacy requirements, website terms, access controls and reasonable request rates. A proxy changes the network route; it does not grant permission to access data or guarantee that a website will accept a request.

Methodology: Anthropic's Browser Use, client-toolset, tool-result, model and security documentation was checked on August 28, 2026. Proxidize product details were checked against current first-party Residential Proxy and AI Agent pages, and Playwright proxy behavior was checked against its current documentation. The exact example was live-tested that day with anthropic 1.2.0, Playwright 1.62.0, Claude Sonnet 5, a Proxidize Residential access point, and the allowlisted IANA Example Domains page. The proxied preflight and complete tool loop passed; the same redacted exit fingerprint appeared across five fresh Chromium launches. No country, city or ISP result was tested or is claimed.

Key Takeaways

• Claude Browser Use does not host the browser. browser_toolset_20260801 supplies Anthropic-defined member schemas, while your application executes every call in a browser it controls.
• Proxy the browser, not the prompt. Put the Proxidize server and credentials in Playwright's proxy configuration. Describing a country or proxy in natural language does not change the network route.
• The Claude API connection is separate. Proxying Chromium does not automatically proxy requests from the Anthropic SDK, Claude Web Search or Claude Web Fetch.
• Sticky is the safer default for multi-page work. Preserve one exit, browser context and cookie jar for one coherent task, then rotate at a clean task boundary.
• Geo-targeting is more than an IP. Align the proxy location with locale, time zone, cookies, account settings and the target's own localization rules, then verify what the destination actually shows.
• Expose only the member tools you implement. Browser Use includes 27 members by default and four optional members. Disable unimplemented or unnecessary members in configs.
• Treat every webpage as untrusted. Enforce domain and network policy in code, isolate the browser and require human approval for consequential actions.
• Bound the entire loop. Limit model rounds, browser actions, tabs, navigation retries, timeouts, response text, concurrent browsers and per-target traffic.

What Is Claude Browser Use?

Claude Browser Use is Anthropic's first browser-specific client toolset for the Messages API. One {"type": "browser_toolset_20260801"} entry gives a compatible Claude model trained-in browser member tools for navigation, page reading, screenshots, pointer and keyboard input, forms and tabs.

The toolset entry takes no name and requires no beta header. Do not add strict: true, which client toolsets do not support. Member calls use their own name plus toolset_name: "browser"; member results must echo that toolset name.

Claude can work from both webpage structure and pixels. Members such as read_page, find and form_input can use element references, while screenshot, pointer and scrolling members use viewport coordinates. That makes Browser Use a closer fit than full desktop control when the workflow stays inside webpages.

The execution boundary is the important part: Claude emits a structured tool_use block, but your application performs the operation. The destination website therefore sees the network identity of your browser executor. That is the point where a residential proxy fits.

Do not confuse three similarly named products

This guide is about the first option. If you mean the separate open-source Browser Use project, see How to Use Residential Proxies with Browser Use for AI Agents.

Browser Use vs. Computer Use

Use Browser Use for website research, browser QA, public catalog checks and other browser-contained workflows. Use Computer Use when the same task must cross native applications, file dialogs or a full desktop.

What Is Actually Being Proxied?

Only the network-aware component configured with Proxidize uses the residential route.

This separation gives you a useful debugging rule: a successful Claude response does not prove the website request used Proxidize, and a successful browser proxy preflight does not prove that the Claude API or a hosted search tool used the same route.

Never put proxy credentials in a system prompt, user message, tool description, page URL, screenshot, trace or tool_result. Playwright can receive the server, username and password as separate fields without exposing them to Claude.

Why Pair Claude Browser Use With Residential Proxies?

A browser agent sometimes needs to inspect lawful public content as it appears from a residential network or selected market. Common examples include:

• Comparing public prices, availability or promotions between countries.
• Reviewing localized search results, landing pages or storefronts.
• Collecting fresh public evidence for market research or a retrieval workflow.
• Testing localized language, currency and regional website behavior.
• Monitoring public listings for brand-protection work.
• Verifying browser experiences from a selected country, city or ISP.

Proxidize Residential Proxies provide real residential IPs across 195+ countries, country/city/ISP targeting, rotating and sticky sessions, and HTTP(S) and SOCKS5 access. Standard proxy credentials work with Playwright, so the browser executor does not need a proprietary proxy SDK.

Residential proxies are usually a better fit than mobile proxies when the workload needs broad international coverage, many residential exits or global data collection. Proxidize Mobile Proxies are the narrower choice when a workflow specifically needs a real US 4G/5G carrier route, mobile-carrier targeting or a dedicated SIM-based exit.

A residential proxy is not necessary for every Claude agent. If the agent reads local files, calls your own APIs, uses an approved first-party feed or gets the required result from Anthropic-hosted Web Search or Web Fetch, a browser and proxy may add cost and operational work without improving the outcome.

Want to test this architecture?Create a Proxidize Residential Proxy access point and use the generated server, username and password in the environment variables below. For the broader commercial use case, see AI Agent Proxies for Reliable Web Access.

Prerequisites

You need:

1. Python 3.10 or later.
2. An Anthropic API key with access to a Browser Use-compatible model.
3. An active Proxidize Residential Proxy plan and completed account requirements.
4. A dashboard-generated HTTP access point with separate server, username and password values.
5. A fixed list of public domains your workflow is authorized to visit.
6. A dedicated container or virtual machine for the browser executor in production.

Create a virtual environment and install the versions used for this draft's runtime validation:

anthropic 1.2.0 and Playwright 1.62.0 were the current Anthropic SDK and Playwright PyPI releases checked for this guide. claude-sonnet-5 is a current Claude model ID that supports browser_toolset_20260801. Pin and retest these dependencies together when updating the implementation.

Create a local .env file:

Add .env to .gitignore:

Use the exact endpoint and credentials generated for your access point. The proxy server may use an http:// URL even though Chromium visits https:// targets: for an HTTP proxy, the browser uses an HTTP CONNECT tunnel for the HTTPS destination.

The example treats ALLOWED_DOMAINS as the browser's complete HTTPS egress allowlist, including document, API and static-resource hosts. A production page may need reviewed CDN or first-party API hosts in addition to its visible hostname. Add only the exact hosts the task needs; do not replace the list with a wildcard.

The main example uses an HTTP access point because Playwright documents separate username/password authentication for HTTP(S) proxies. Proxidize also supports SOCKS5, but test browser and authentication compatibility in your exact runtime before changing the protocol.

Configure the Residential Access Point

Choose the access-point policy before starting the browser:

If an existing access point uses Random mode, that is valid for independent observations, but do not describe it as a tested Sticky endpoint. For this article's multi-page example, create or select a Sticky access point before the publication test.

Do not infer rotation behavior from one or two repeated IP checks. A Random route can still return the same exit because of connection reuse, pool selection or a short observation window. Validate Sticky continuity with several fresh browser connections, and validate Random behavior over a representative workload without promising a new IP on every page action unless that is the configured and observed policy.

Complete Python Example

The following example implements a bounded, read-focused Browser Use executor with Playwright. It enables only nine members:

• navigate
• get_page_text
• screenshot
• scroll
• wait
• new_tab
• list_tabs
• switch_tab
• close_tab

The other 22 members are disabled explicitly. This is deliberate: a research agent that only needs to read approved public pages does not need click, typing, form, upload, JavaScript or diagnostic capabilities. If you later add an action, implement its semantics and approval policy before enabling its member in configs.

Save the code as claude_browser_proxy.py:

Run it with a read-only task:

The code prints only a short one-way fingerprint from the preflight, never the raw exit IP. Treat even that fingerprint as operational metadata: keep it out of public logs if your policy does not require it.

How the Example Works

The implementation separates four responsibilities that are easy to blur together:

1. It advertises only implemented Browser Use members

Anthropic's toolset enables 27 members by default. If an executor implements only a few of them but sends the unmodified toolset, Claude can validly request a member the application cannot execute.

The example defines all 31 names, keeps nine read-focused members enabled and sends {"enabled": false} for the other 22. Optional javascript_exec, file_upload, read_console and read_network remain off. Disabling a member removes it from what Claude sees, although the dispatcher still rejects an unexpected call defensively.

This is also a security boundary. A prompt-injected page cannot induce a form submission or file upload through a tool Claude was never offered.

2. It puts Proxidize on Chromium

The proxy object is passed when Playwright launches Chromium. Every browser context and page created by that browser therefore uses the configured route. The Claude API client remains separate and never receives the proxy password.

The preflight opens an IP-check page inside Chromium, parses the returned IP locally and logs only a SHA-256-derived fingerprint. A requests, HTTPX or shell check outside the browser would test that other client, not the browser Claude controls.

The preflight proves that the browser could authenticate and reach the internet through the configured proxy at that moment. It does not, by itself, prove:

• That a selected country or city matches the intended market.
• That every later request receives the same exit.
• That Random mode will rotate on every action.
• That a particular target will accept the traffic.

Those claims require separate tests.

3. It runs Anthropic batch actions sequentially

Claude may return several Browser Use member calls in one assistant turn. Those calls are a batch action, not permission to run browser mutations in parallel. The second operation may depend on the result of the first.

process_browser_batch() therefore executes calls in order. After the first error, it returns an error for that call and answers every remaining call with Anthropic's required halt message:

Every result echoes toolset_name: "browser". Successful tab-management members return exactly one browser_state block, as required by the Browser Use contract.

4. It tracks browser state without treating it as trusted

The application assigns stable IDs such as tab-1, records which tab is active and returns the complete tab inventory after navigation or tab operations. Before titles and URLs reach Claude, the example removes control characters, credentials, query strings and fragments and caps their length.

That matters because a tab title and URL are page-controlled input. A malicious title is not safer than malicious body text merely because it appears in a structured browser_state block.

5. It enforces limits outside the prompt

The system message tells Claude to stay read-only, but the application also enforces that policy mechanically:

• Exact hostname allowlist.
• The same allowlist on page subresources, not only top-level navigation.
• HTTPS-only destination URLs on the default port.
• No credentials in destination URLs.
• DNS rejection when an approved name resolves to a non-public address.
• Main-document redirect revalidation through Playwright routing.
• A maximum of 24 browser actions, eight model rounds and three tabs.
• A 30-second navigation timeout and two bounded retries.
• A 30,000-character page-text limit.
• tool_choice={"type": "any"} until an approved page has been visited and inspected, followed by auto so Claude can return its answer.
• A runtime evidence gate that refuses a final answer until at least one approved page has been both visited and inspected.
• Deterministic rejection of final-answer URLs the browser never observed.

The evidence gate also matters when Claude believes it already knows a familiar page and tries to answer without using the browser. Anthropic's any tool choice requires a tool call without trying to name an individual toolset member, which toolsets do not support. The runtime still verifies that the call produced approved browser evidence, while the round limit keeps correction bounded. The code-level controls remain authoritative even if a page tells Claude to ignore the original task.

Sticky vs. Rotating Sessions for Claude Browser Use

The right unit of stickiness is normally a work item, not a model turn or individual click.

Why Sticky is usually right for a multi-page task

A browser session carries more identity than its IP address. It also carries cookies, local storage, cache, TLS connections, language, time zone and sometimes an authenticated account. If the IP changes halfway through the task while those other signals stay constant, the website sees an identity discontinuity.

Keep these together for one coherent task:

Rotate when a new independent task begins. If a Sticky exit becomes unavailable, either recreate the entire work item from a known checkpoint or explicitly reset the browser context and site state. Quietly changing only the IP can produce misleading data.

For a deeper treatment of session leases, recovery and rotation boundaries, read Proxy Sessions for AI Agents.

Geo-Targeting Without False Confidence

Selecting a residential country, city or ISP is necessary for localized browsing, but it is not sufficient to guarantee a particular page result.

A destination may also consider:

• Browser locale and Accept-Language.
• Time zone.
• Cookies and previous location choices.
• Account country, billing region or saved address.
• GPS/browser geolocation permission.
• URL path, domain or currency parameter.
• Inventory and experimentation rules controlled by the website.

Use this sequence for a geo-dependent run:

1. Configure the required country, city or ISP in the Proxidize dashboard or Session Builder.
2. Create fresh credentials or a session for that policy.
3. Start a fresh browser context with a compatible locale and time zone.
4. Check the target-visible IP and location from inside that browser.
5. Confirm the target itself shows the expected market, currency, language or inventory.
6. Record the intended location and redacted observed evidence in the job log.

Do not grant browser geolocation permission automatically. An IP in one city and a GPS coordinate in another is worse than leaving geolocation unavailable. If a legitimate QA workflow needs a coordinate, set it deliberately, keep it aligned with the proxy market and scope the permission to an approved origin.

For publication testing, two independent geo services should agree on the exit country before the article says country targeting passed. Even then, describe exactly what was tested; a country result does not validate city or ISP targeting.

Retries, 403s, 429s and Proxy Rotation

Retries should answer a specific failure mode, not serve as an automatic attempt to evade a website's controls.

The example retries only timeouts, 429 and a small set of transient 5xx statuses. It keeps the same browser and proxy session during those retries. A 403 is returned as evidence instead of triggering automatic identity changes.

When a site persistently refuses automated access, a licensed API, data feed, manual process or revised collection plan is often the correct answer. Residential proxies help provide reliable network access; they are not permission to defeat access controls.

Control Concurrency at Every Layer

Proxidize Residential Proxies support high concurrency, but a provider-side connection allowance is not a target-side rate limit and not a safe worker count.

Control at least these layers:

A simple browser-worker gate looks like this:

That semaphore limits whole browser tasks. Add a separate per-host limiter inside the navigation layer when several tasks can reach the same destination. Do not share one mutable page, tab inventory or cookie jar between concurrent agents.

For independent work items, the clean default is one BrowserExecutor and browser context per task. At higher scale, a supervised browser pool can reuse browser processes while issuing isolated contexts, but each context still needs a clear proxy/session lease and lifecycle.

Control Bandwidth and Browser Cost

Residential plans bill by transferred data, and browser pages can load far more than the text Claude needs. Images, video, fonts, trackers, repeated screenshots and long-running contexts all add cost.

Reduce unnecessary traffic without breaking the page:

• Prefer get_page_text for text-heavy pages and screenshots only when visual layout matters.
• Use viewport screenshots instead of full-page screenshots unless the task requires the whole page.
• Keep the viewport stable so Claude's coordinate assumptions remain valid.
• Block autoplay video and other known-heavy resource classes only after testing the target.
• Cache approved static resources inside the browser context where appropriate.
• Cap tabs, rounds, action count, page text and task duration.
• Record bytes per job, target and market in operational telemetry.
• End the browser context promptly when the task completes.

Blocking every image is tempting, but it can change responsive layouts or hide information the task needs. Treat resource blocking as a tested optimization, not a universal default.

Browser Use vs. Web Search, Web Fetch and a Custom HTTP Tool

Choose the lightest tool that can complete the job reliably.

Do not start Chromium when a permitted HTTP request can retrieve the same public data. Browser Use earns its operational cost when rendering, cookies, tabs, visual state or browser interaction materially affects the result.

If you need the underlying Playwright proxy patterns in Python and Node.js without Claude's tool loop, see How to Use a Proxy With Playwright. If you would rather run remote browser infrastructure, compare the best cloud browsers for AI agents.

Where MCP Fits

MCP is optional for this integration. The local Playwright browser carries target-site traffic; MCP does not replace that data path.

A Proxidize MCP server can give an approved agent a control-plane interface for inspecting or managing account resources. Anthropic also offers an MCP connector for Claude API tool use. Keep those responsibilities separate:

Use least-privilege MCP permissions and require approval for mutations. Store the Proxidize API token in a protected environment variable or secret manager, never in the article, prompt or browser page. Rotate any token that has been exposed through chat, logs or another uncontrolled channel.

See the Proxidize MCP server, the Proxidize MCP package and What Is MCP? for current setup and protocol details. A successful MCP connection proves the control-plane integration works; it does not prove Browser Use traffic traversed the residential proxy.

Security and Prompt-Injection Controls

Browser agents process adversarial input by design: any visited page can contain text, accessibility labels, images, titles or URLs intended to redirect the model. A system prompt helps, but it is not the security boundary.

Use layered controls:

1. Run the browser and executor in a dedicated container or virtual machine with minimal privileges.
2. Use a fresh browser profile with no personal cookies, saved passwords, extensions or cloud accounts.
3. Block access to loopback, link-local, private and cloud-metadata networks at the container or network layer.
4. Enforce an exact destination allowlist in the executor and revalidate every redirect.
5. Keep page content inside tool_result blocks; never promote it into system instructions.
6. Return visible or accessibility-derived content rather than unfiltered raw HTML with hidden text.
7. Keep javascript_exec and file_upload disabled unless the task genuinely requires them.
8. Redact credentials, signed URLs and sensitive headers from browser state, console and network output.
9. Require a human approval immediately before purchases, messages, account changes, consent acceptance or other consequential actions.
10. Log policy decisions and redacted action metadata outside the model context for later review.

The example's application-level DNS check is useful defense in depth, but it is not a complete network sandbox. DNS rebinding, compromised allowlisted origins and browser-level vulnerabilities require outbound firewall rules, container isolation, patching and monitoring beyond a Python URL function.

Extending the executor to clicks and forms

Anthropic Browser Use supports read_page and find, which return element references such as ref_2. If you add them, your executor must map each reference to an underlying node, scope it to one tab and keep it stable until navigation or a material DOM change. A stale or unknown reference must return an error that asks Claude to read the page again.

Then add click or form members one at a time. Validate coordinate bounds, confirm the target element is still present and visible, check the destination again after navigation and put consequential operations behind an application-level approval gate. Enabling form_input in configs before implementing those controls only increases risk.

Troubleshooting

When debugging the proxy itself, start with the dashboard-generated cURL command, then test a minimal Playwright page, then test the Browser Use loop. That isolates the proxy, browser and model layers instead of changing all three at once.

Production Checklist

Before deploying Claude Browser Use with residential proxies:

• Use fresh Anthropic and Proxidize credentials stored in a secret manager.
• Put the proxy on the actual Playwright browser executor.
• Confirm the access point is Sticky or Random by deliberate configuration, not inference.
• Verify the exit inside the browser without exposing a raw IP publicly.
• Verify country/city/ISP claims against the intended configuration and target-visible result.
• Enable only Browser Use members the executor fully implements.
• Apply exact domain, scheme, port, redirect and private-network policy.
• Isolate the browser from sensitive files, credentials and internal services.
• Keep page-derived content inside untrusted tool results.
• Bound rounds, actions, tabs, retries, timeouts, text and screenshots.
• Limit whole-task and per-host concurrency separately.
• Keep one browser context and proxy session per coherent task.
• Require human approval for consequential actions.
• Validate that final citations came from successfully visited pages.
• Record redacted telemetry for failures, bandwidth and session behavior.
• Review laws, contracts, privacy obligations and website terms for the workflow.

Common Mistakes

Putting the proxy in the prompt

“Use a German residential proxy” is an instruction, not network configuration. Claude cannot change Chromium's route unless your executor exposes and authorizes a control for that purpose. Configure the access point before the run and pass it to Playwright.

Assuming Claude hosts Browser Use

Browser Use is an Anthropic-defined client toolset. Your application supplies the browser, member implementations, isolation, network policy and action loop. If you need hosted infrastructure, choose a managed browser separately.

Leaving every default member enabled

The unmodified toolset exposes 27 members. If your executor handles nine, disable the other 18 default-enabled members as well as keeping the four optional members off. Otherwise Claude can request operations your code cannot safely execute.

Rotating on every error

A timeout, target 500, invalid selector, policy rejection and 403 have different causes. Treating every failure as an IP problem wastes bandwidth, damages session coherence and can conceal a bug in the executor.

Sharing one context across concurrent agents

Tabs, active focus, cookies, references and page state are mutable. Two agents controlling the same context can invalidate each other's assumptions even if the proxy accepts the traffic. Isolate work items.

Logging full URLs and secrets

Signed URLs, query parameters, proxy usernames, API keys and raw IPs can leak through ordinary debug output. Redact before logging, and never make protected logs part of a tool_result.

Build a Safer Claude Browser Agent

Claude Browser Use and residential proxies solve different parts of the same system. Claude supplies browser-aware planning, your executor supplies controlled Playwright actions, and Proxidize supplies the residential network route. The integration is reliable when those responsibilities remain explicit.

Start with a read-only member subset, an exact domain allowlist and one Sticky session per work item. Add interaction only when the task requires it, and put consequential actions behind deterministic policy and human approval.

Explore Proxidize Residential Proxies, review the AI Agent Proxies use case, or compare the best proxies for AI agents before choosing the session and browser architecture for your workload.