PAC Request Policy for Consistent Browser Routing

Proxy Auto-Config, usually called PAC, gives the browser a policy for selecting a network route. The decision stays in the browser network path, so the same policy can cover navigation, redirects, subresources, and browser-managed requests without depending on a page framework.

That placement is useful when a deployment uses more than one approved proxy route. Regional browsing, internal application testing, media validation, and multi-context workloads may each need different route families. A PAC policy keeps those choices close to the browser profile and launch configuration.

BotBrowser documents standard PAC routing through --proxy-pac-url and, for approved enterprise profiles, an additional request callback in the same PAC script. Standard PAC remains the default model. The callback is an optional layer that helps authorized teams keep request handling consistent while the PAC source, proxy inventory, and profile stay under one review.

Why routing belongs with the browser

A static proxy is often enough for a simple session. It becomes less suitable when one browser workflow needs several approved paths. Moving route choices into framework handlers can also create different behavior between Playwright, Puppeteer, raw CDP, and browser-managed traffic, and interception in the automation layer can interrupt HTTP/2 connection and stream continuity in some workflows.

PAC gives the browser one routing policy. Automation code drives the page, while the browser owns network selection. Because the policy is not tied to a framework, the same policy can serve different automation tools. This division makes a deployment easier to review because the profile, proxy inventory, and routing policy have clear responsibilities.

The approach also supports privacy consistency. A browser profile can define a region, language, timezone, and device family, but those settings lose value when traffic follows an unrelated network path. Keeping the route policy next to the profile reduces configuration drift between the profile settings and the approved egress.

When a static proxy is enough

PAC is not required for every deployment. Prefer a static proxy when all traffic should use one route and there is no request-class policy to maintain. A context that has a single route does not need PAC, and a smaller configuration is easier to operate and leaves fewer moving parts.

Use PAC when route selection is a real browser-level requirement. Do not add it only to mirror framework logic that already has a single, stable route. The policy should reduce operational complexity, not move the same complexity into another file.

Operating model and request callback

A maintainable deployment separates four concerns:

1. The browser profile defines the intended browser settings.
2. The proxy inventory defines the approved network paths.
3. The PAC policy selects a path for each relevant request class.
4. The automation workflow performs the authorized browser task.

This arrangement prevents routing rules from being copied into every script. It also gives support and privacy teams a stable place to review a route change without reading page automation code. Use descriptive policy names and keep each policy focused on one deployment purpose, because a regional validation job, an internal application test, and a media workflow should not share a large policy merely because they run on the same worker. Smaller policies are easier to review, version, and roll back.

Standard PAC scripts keep using FindProxyForURL(url, host) for ordinary proxy selection. For approved ENT Tier3 profiles, the same trusted PAC script can also define BotBrowserFindProxyForRequest, a BotBrowser callback that receives the request URL, host, method, headers, and body state. The callback does not replace standard PAC. When it returns CONTINUE or no valid result, routing falls back to the standard function. The callback can do the following:

• Continue the request and keep the standard PAC route.
• Block the request.
• Write a short tagged capture record to an approved absolute path.
• Route only the current request through a different standard PAC result such as DIRECT, HTTPS, or SOCKS5.
• Complete the request with a controlled synthetic response.

Results can be combined with semicolons. Capture is written first. A controlled response then completes the request and takes priority over blocking and routing, and without a response, blocking takes priority over a route. Response input that is malformed, oversized, unsafe, or unsupported fails closed and is never sent to the destination or the proxy.

The callback is available only for approved profiles and explicit PAC sources: file: PAC files, data: PAC URLs, loopback HTTP(S) PAC services, and remote HTTP(S) PAC services that your team controls. PAC auto-detect and WPAD remain valid for standard PAC routing, but they do not receive the callback. Prefer file: or loopback sources for local workers, and use HTTPS when the source is remote.

Controlled responses have a narrower source policy than the callback itself. They are limited to approved profiles that load a file: or data: PAC source. An HTTP(S) PAC source can still route, capture, and block requests, but it cannot return a controlled response. Administrators should keep the policy under the same access controls as the profile package and reject unreviewed delivery paths.

Controlled responses are suitable for endpoints and fixtures owned by the deployment, such as a readiness result, a stable test asset, or a deterministic reply used in an authorized quality assurance workflow. Keep owned fixtures separate from live destination traffic. They should support repeatable testing and operational checks, not replace ordinary navigation to third-party services.

Good uses for PAC request policy

Regional route consistency

A profile-backed session may need a route that matches its selected region. PAC can keep navigation and supporting requests on the approved route family without duplicating selection logic across automation frameworks.

Internal and external application paths

An enterprise test may combine an internal service with public web dependencies. A small PAC policy can keep internal traffic on the intended private path while external traffic uses the approved proxy route.

Multi-context workers

Workers that create and close browser contexts need predictable ownership. Pairing each context configuration with its profile and policy makes later review easier and reduces reliance on process-wide assumptions. The per-context proxy guide covers how routes are assigned to separate contexts.

Repeatable quality assurance

Owned fixtures can remove unnecessary network variability from a selected test path. With an approved local policy source, controlled responses can support that narrow use while the rest of the page follows standard browser networking.

Safeguards and outcome-based validation

Treat the PAC source, browser profile, and proxy inventory as one reviewed release unit.

• Restrict who can change the policy source.
• Keep the approved policy reference explicit in deployment configuration.
• Use version control for stable policy files.
• Review route ownership before changing proxy credentials or regions.
• Start a fresh browser session when the job configuration changes.
• Keep controlled fixtures under the same access controls as the test workflow.
• Prefer a small allowlist of request classes over a broad catch-all policy.

Remote policy delivery requires the same transport and access review as other production configuration. Broader source availability for standard PAC routing should not be confused with permission to use controlled responses.

Validation should confirm the deployment result without collecting unnecessary page data. Begin with the route plan. Record which request classes should use each approved route and which should remain on standard PAC behavior. Run the normal authorized workflow and compare its observable network outcome with that plan.

Check profile and route alignment together. Region, language, timezone, and proxy egress should describe a coherent environment. For multi-context jobs, review each context independently so one successful context does not mask a configuration problem in another.

For an owned controlled fixture, confirm the expected application behavior through normal application checks. Review the effective policy identifier, profile assignment, access record, and browser outcome together. These observations show whether the deployment follows its approved route plan. Attach the result to the same release record used for rollout and rollback decisions.

Keep validation evidence concise. Policy version, profile family, expected route family, observed egress, and workflow outcome are usually enough for a release record.

Ownership, rollout, and records

A routing policy affects browser traffic before page automation evaluates the result. Give every policy a named owner who understands the application paths it governs. The owner should be able to explain why each route class exists, which profile families use it, and which team approves changes. Proxy operations can remain a separate responsibility, but the boundary between route selection and route availability must be written down.

Review the policy as a production configuration item. A useful review record contains the policy name, its revision, the affected deployment groups, the profile families assigned to it, and the expected outcome for each approved route class. It should also identify the rollback revision and the person responsible for making that decision. This is enough context for an operator to act without copying the policy into a ticket or exposing details that do not belong in an operational record.

Avoid informal policy sharing between jobs. A policy that works for one application may include assumptions about regions, private services, or proxy ownership that do not apply elsewhere. Create a separate reviewed policy when the purpose changes. The additional record is cheaper than investigating an unexplained route after two deployments have evolved independently.

Credentials should not be embedded in policy text that is copied into tickets or browser automation. Use the deployment's normal secret-management path and limit access to the service accounts that run the approved job. Rotate credentials independently from routing logic where the platform permits it, and run the same authorized application checks used for a normal release afterward. The proxy authentication and credential hygiene guide describes this practice in more detail.

Start with a small deployment group that represents the production environment. Use the intended browser release, profile family, operating system, proxy inventory, and automation version. A test on a developer laptop can confirm syntax, but it does not establish that production route ownership, credentials, and access controls are correct.

Compare the staged group with an unchanged group over the same period. Useful observations include successful application completion, browser start and exit status, proxy availability, route-family outcome, and the number of jobs returned to the queue. Keep the page set and job mix comparable. If several inputs change at once, the comparison will not show whether the policy helped or merely coincided with a different workload.

Expand by deployment group rather than changing every worker at once. Pause the rollout when the application outcome, browser stability, or route ownership record no longer matches the release plan. Restore the previous reviewed policy before trying a second change. This keeps rollback predictable and preserves a clear baseline for the next comparison.

Long-running workers should receive policy changes through the same lifecycle used for profile and browser updates. Finish or stop assigned work according to the application's normal shutdown rules, then begin a fresh browser session with the new release unit. Mixing an old browser session with a new policy assignment makes support records difficult to interpret.

Routing records can reveal sensitive operational information even when they do not contain page content. Limit collection to what a support or privacy review needs: policy revision, profile family, approved route family, deployment group, time window, and application outcome. Avoid retaining full destination histories merely to prove that a policy was active.

Apply the organization's ordinary retention schedule to these records. A short-lived staging record may need only the release window, while a regulated production workflow may require a longer audit trail. The deployment owner should decide the period before rollout and document who can read or export the record. Do not let browser logs become an unmanaged copy of network history. Capture records written by the callback follow the same rule, so keep their path, tag, and retention period part of the reviewed policy.

Access reviews should cover both policy editing and policy assignment. Someone who cannot change policy text may still be able to attach an existing policy to the wrong deployment group. Review those permissions together. Remove assignments that no longer have an active owner, and retire policy revisions that are no longer available for rollback.

Recovery and maintenance

When an authorized workflow produces an unexpected route outcome, stop issuing new work to the affected deployment group. Keep the last successful policy revision and release record available. Confirm that the assigned profile family, browser release, proxy inventory, and policy revision match the approved change. This first comparison often identifies configuration drift without requiring page-level investigation.

Check the health of approved proxy routes independently through the organization's normal infrastructure monitoring. A route can be unavailable even when the policy is unchanged. Likewise, a healthy proxy does not prove that the intended policy was assigned. Treat policy selection and route availability as separate facts, then compare both with the application outcome. The proxy failover guide covers what to do when a route itself is unavailable.

Change one release component at a time during recovery. Restoring the previous policy while also changing the profile package, browser version, and proxy region destroys the baseline. Return to the last reviewed unit first. Once the normal application checks pass, introduce the next change through the staged rollout process.

The incident record should state the user-visible outcome, affected deployment groups, last known good revision, corrective action, and release validation result. Summarize observed behavior instead of retaining request-by-request page data. That narrower record supports accountability while respecting the privacy boundary of the browsing session.

Review active policies on a regular schedule and after major application, browser, profile, or network changes. Confirm that every route class still has a current purpose and owner. Remove unused classes rather than leaving them available for possible future work. A shorter policy is easier to reason about during a release and less likely to carry obsolete assumptions.

Verify that documentation links point to the current product release and that deployment templates reference an active policy revision. Test rollback material while it is still valid. A revision that exists only in an old ticket is not a reliable recovery option if its proxy inventory or profile assignment has already been retired.

Include privacy and support owners in the maintenance review. Operations can confirm route health, while privacy reviewers confirm that collection and retention remain proportionate. Support can identify recurring configuration questions that should be resolved in deployment templates. This shared review keeps the policy useful without expanding its scope.

Common configuration mistakes

• Treating every policy source as equivalent. Source requirements differ by capability, so select a documented, approved source for the intended workflow and review that choice whenever the browser or policy package changes.
• Splitting route ownership across layers. When PAC, framework handlers, and an external forwarding service all select routes, the final path becomes difficult to explain, so choose one owner for each decision.
• Reusing a policy for unrelated profiles. A policy created for one region or browser family may not suit another, so review it whenever the profile family, proxy region, or worker role changes.
• Using controlled responses for live web traffic. They are intended for owned fixtures and authorized test paths, and ordinary destination traffic should continue through standard browser networking.

What BotBrowser supports and where it stops

BotBrowser supports standard PAC routing through --proxy-pac-url and, for approved ENT Tier3 profiles, a trusted request callback in the same PAC script that can continue, block, capture, route a single request, or return a controlled synthetic response from a file: or data: PAC source. This keeps route policy in the browser network path, so your team reviews one policy alongside each profile instead of routing logic spread across automation scripts. BotBrowser cannot make a proxy route available or healthy, cannot approve a policy for your organization, does not permit controlled responses from HTTP(S) PAC sources, and does not check who owns a destination, so keeping controlled responses to owned fixtures rather than live third-party traffic is your team's policy.

Use the PAC request callback documentation for supported sources, return values, and operational requirements, and the proxy configuration guide for the underlying proxy choices. The proxy configuration article explains how those choices fit together.

Public sources

• MDN: Proxy Auto-Configuration (PAC) file
• BotBrowser PAC-Like Request Callback documentation