DocsProxy Managementbrowser_set_proxy

browser_set_proxy

Use browser_set_proxy when you need to route traffic through proxies or Tor for per-session IP isolation. It is part of Owl Browser's Proxy Management toolset and runs inside a self-hosted, source-level stealth engine, so every call inherits the same undetectable browser fingerprint as the rest of your automation — no separate anti-detect setup required.

Usage Example

123456789101112

import asyncio

from owl_browser import OwlBrowser, RemoteConfig

# Async usage

async with OwlBrowser(config) as browser:

context = await browser.create_context()

context_id = context["context_id"]

await browser.set_proxy(

context_id=context_id,

type="http"

)

Parameters

Required

context_idstringrequired

The unique identifier of the browser context (e.g., 'ctx_000001')

typeenum

httphttpssocks4socks5+3 more

required

Proxy protocol type: 'http' (HTTP proxy), 'https' (HTTPS proxy), 'socks4' (SOCKS4), 'socks5' (SOCKS5 with local DNS), 'socks5h' (SOCKS5 with remote DNS - most private), 'gae' (private app proxy), 'owl_tunnel' (Owl residential tunnel - set proxy_id instead of host/port)

Optional

hoststring

Proxy server hostname or IP address. Examples: '127.0.0.1', 'proxy.example.com', 'localhost'. Required for all types EXCEPT 'owl_tunnel' (which uses proxy_id)

portinteger

Proxy server port number. Common ports: 8080 (HTTP), 3128 (Squid), 9050/9150 (Tor), 1080 (SOCKS). Required for all types EXCEPT 'owl_tunnel' (which uses proxy_id)

proxy_idstring

Owl Tunnel proxy identity (32-hex, the 'proxy-XXXX' target) when type='owl_tunnel'. Selects which paired residential sidecar to exit through

usernamestring

Username for proxy authentication. Only required if the proxy server requires credentials

passwordstring

Password for proxy authentication. Only required if the proxy server requires credentials

spoof_timezoneboolean

Automatically spoof browser timezone to match proxy location (detected via IP geolocation). Applied to the live context immediately. Default: true

timezone_overridestring

Manually set timezone instead of auto-detection. IANA format like 'America/New_York', 'Europe/London'. Takes precedence over spoof_timezone. Applied to the live context immediately

ca_cert_pathstring

Path to custom CA certificate file (.pem, .crt, .cer) for SSL interception proxies. Required when using Charles Proxy, mitmproxy, or similar HTTPS inspection tools

ca_key_pathstring

Path to CA private key file for GAE/private app proxy MITM. Required for generating per-domain certificates when using 'gae' proxy type

trust_custom_caboolean

Trust the custom CA certificate for SSL interception. Enable when using Charles Proxy, mitmproxy, or similar tools that intercept HTTPS traffic. Default: false

is_torboolean

Explicitly mark this proxy as a Tor connection. Enables circuit isolation so each context gets a unique exit node IP. Auto-detected if proxy is localhost:9050 or localhost:9150 with socks5/socks5h

tor_control_portinteger

Tor control port for circuit isolation. Used to send SIGNAL NEWNYM to get a new exit node. Default: auto-detect (tries 9051 then 9151). Set to -1 to disable circuit isolation

tor_control_passwordstring

Password for Tor control port authentication. Leave empty to use cookie authentication (default) or no auth

Response

Returns a JSON object with the operation result.

{
  "success": true,
  "result": <value>
}

Frequently Asked Questions

What does browser_set_proxy do?

Configure proxy settings for the browser context after creation. Supports HTTP, HTTPS, SOCKS4, SOCKS5, and SOCKS5H proxies with optional authentication. Includes stealth features to prevent proxy detection. It belongs to Owl Browser's Proxy Management category and is available through the REST API, the Python SDK (browser.set_proxy()), the Node.js SDK, and the MCP server.

What parameters does browser_set_proxy accept?

browser_set_proxy accepts 2 required parameters (context_id, type) and 13 optional parameters. All parameters are sent as JSON in a POST request to /api/execute/browser_set_proxy.

Is browser_set_proxy detectable by anti-bot systems like Cloudflare or DataDome?

No. browser_set_proxy executes inside Owl Browser's Chromium engine, which applies fingerprint spoofing at the C++ source level rather than through JavaScript patches. Every tool call shares the same consistent, human-like fingerprint, so anti-bot systems such as Cloudflare, DataDome, and Akamai see an ordinary browser.

Related Tools

browser_get_proxy_status

Get the current proxy configuration and connection status. Returns proxy type, host, port, and whether stealth features are enabled.

browser_connect_proxy

Enable and connect the configured proxy for the browser context. Traffic will start routing through the proxy after this call.

browser_disconnect_proxy

Disable the proxy and revert to direct connection. Useful for comparing behavior with and without proxy, or troubleshooting connection issues.

browser_create_context

Create a new isolated browser context with its own cookies, storage, and optional proxy configuration. Each context acts as an independent browser session. Use this to create multiple isolated browsing sessions, configure proxy/Tor connections, load browser profiles with saved fingerprints, and enable/disable LLM features. Returns a context_id to use with other browser tools.

browser_navigate

Navigate the browser to a specified URL. This is a non-blocking operation that starts navigation and returns immediately. Use browser_wait_for_network_idle or browser_wait_for_selector to wait for the page to fully load. Supports HTTP, HTTPS, file, and data URLs. When wait_until is set (load, networkidle, fullscroll, domcontentloaded) and the page declares WebMCP tools, the response includes a webmcp_tools array containing the full tool definitions (name, description, inputSchema). Use browser_webmcp_call_tool to execute any of these tools directly.

browser_observe

Agent-native page observation. Returns the compacted OwlMark render (text-only structural view of the page), a handle table of interactive elements with stable tokens, page metadata, and a token estimate. Pass a handle token (e.g. 'b3') or 'pm:N' to browser_click/browser_type. Requires the context to be created with render_mode 'agent' or 'both'. ~20-100x fewer tokens than a screenshot for AI agent page understanding.

Browse the full Owl Browser API reference or get started with the Python SDK and Node.js SDK.