PAC-Like Request Callback

Use standard PAC routing plus BotBrowser’s trusted request callback for enterprise network policy workflows.

Prerequisites

• BotBrowser ENT Tier3 license for trusted request callback workflows.
• BotBrowser binary with a valid profile loaded via --bot-profile.
• A trusted PAC source that you control, such as a local file or controlled loopback service.

Quick Start

Configure PAC through the standard --proxy-pac-url flag:

chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --proxy-pac-url=file:///absolute/path/to/proxy.pac \
  --user-data-dir="$(mktemp -d)"

For local development, a controlled loopback PAC server is also supported:

chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --proxy-pac-url=http://127.0.0.1:8080/proxy.pac \
  --user-data-dir="$(mktemp -d)"

Standard PAC Routing

Standard PAC scripts continue to use the normal FindProxyForURL(url, host) function:

function FindProxyForURL(url, host) {
  if (dnsDomainIs(host, "example.internal")) {
    return "DIRECT";
  }
  return "SOCKS5 proxy.example.com:1080";
}

Use standard PAC routing when you only need proxy selection by URL or hostname.

BotBrowser Request Callback

Approved ENT Tier3 profiles can also define a BotBrowser callback in the same trusted PAC script:

function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (method === "POST" && dnsDomainIs(host, "api.example.test")) {
    return "CAPTURE; CAPTURE_FILE /var/botbrowser/captures/api.jsonl; CAPTURE_TAG api-post; CONTINUE";
  }
  if (shExpMatch(url, "https://media.example.test/*")) {
    return "SOCKS5 media-proxy.example.net:1080";
  }
  if (dnsDomainIs(host, "static.example.test")) {
    return "HTTPS static-proxy.example.net:8443";
  }
  return "CONTINUE";
}

This callback is BotBrowser-specific. It does not replace standard PAC routing. FindProxyForURL(url, host) continues to handle normal proxy selection. When the BotBrowser callback returns CONTINUE or no valid routing result, routing falls back to standard PAC behavior. When it returns a valid standard PAC route, that route applies to the current request.

Use this workflow when request policy should stay in the browser network path. CDP-level request interception can interrupt HTTP/2 connection and stream continuity in some automation workflows. A trusted PAC callback keeps policy decisions with PAC routing, helping selected requests continue, stop, capture, or use different PAC routes without pausing every request in the automation layer.

Return values can be combined with semicolons:

Capture records are written only when CAPTURE and CAPTURE_FILE <path> are returned together. CAPTURE_FILE <path> without CAPTURE does not write a capture record. BLOCK can be used by itself. CAPTURE; CAPTURE_FILE <path>; BLOCK writes the capture record and then blocks the request.

Trusted Sources

The request callback is available only for approved profiles and explicit PAC sources:

• file:// PAC files.
• data: PAC URLs.
• Loopback HTTP(S) PAC services.
• Explicit remote HTTP(S) PAC services that your team controls.

PAC auto-detect and WPAD should be used only for standard PAC routing. They do not receive the BotBrowser request callback.

Enterprise Request Policy

ENT Tier3 profiles can enable trusted request callback workflows for approved deployments. Standard PAC routing remains unchanged; the BotBrowser callback adds request-aware policy handling for explicit PAC sources.

Recommended operating model:

• Use only PAC files or PAC services that your team controls.
• Prefer file:// or loopback PAC URLs for local automation workers.
• Use HTTPS when the PAC source is remote.
• Keep PAC deployment tied to the same profile, proxy, and user data directory policy as the browser session.
• Avoid PAC auto-detect/WPAD for request callback workflows.

For setup templates and profile enablement, use the enterprise support channel.

Common Scenarios

Keep a fixed proxy for most traffic

function FindProxyForURL(url, host) {
  return "SOCKS5 proxy.example.com:1080";
}

Bypass known internal hosts

function FindProxyForURL(url, host) {
  if (shExpMatch(host, "*.internal.example")) {
    return "DIRECT";
  }
  return "HTTPS proxy.example.com:8443";
}

Route selected requests by URL

function FindProxyForURL(url, host) {
  return "SOCKS5 default-proxy.example.net:1080";
}
 
function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (shExpMatch(url, "https://media.example.test/*")) {
    return "SOCKS5 media-proxy.example.net:1080";
  }
  if (dnsDomainIs(host, "static.example.test")) {
    return "HTTPS static-proxy.example.net:8443";
  }
  return "CONTINUE";
}

CONTINUE keeps the default FindProxyForURL route. Returning a standard PAC route from the BotBrowser callback applies that route only to the current request.

Combine PAC with SOCKS5 UDP policy

PAC can select SOCKS5 routes for TCP traffic. QUIC/STUN UDP behavior still follows BotBrowser’s UDP-over-SOCKS5 support and standard browser flags. If the deployment should avoid QUIC/HTTP/3, add --disable-quic:

--proxy-pac-url=file:///absolute/path/to/proxy.pac
--disable-quic

Troubleshooting / FAQ

Next Steps

• Proxy Configuration. Basic proxy setup and supported protocols.
• UDP over SOCKS5. QUIC/STUN tunneling behavior and --disable-quic.
• Proxy Selective Routing. Regex-based bypass rules.
• Per-Context Proxy. Assign different proxies to different contexts.
• CLI Flags Reference. Complete list of all available flags.

Related documentation: CLI Flags: PAC-Like Request Callback | Advanced Features: Network Fingerprint Control

Legal Disclaimer & Terms of Use | Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.