Skip to main content
A network policy is a list of domains that a browser can open and a list of domains that it cannot open. Create a policy once, then pass its ID as networkPolicyId when you create a browser or a run. The Browser Use proxy applies the policy to every request of that browser. Network policies are part of API V4. The SDKs do not have methods for them yet, so the examples use REST.

​
Create a policy

curl
The response is 201 with the stored policy:
Browser Use generates id. version starts at 1 and increases by 1 with each update.

​
Domain rules

Browser Use stores each domain in a normal form:
  • It removes leading and trailing spaces, changes letters to lower case, and removes a trailing dot.
  • It converts international domain names to punycode.
  • It stores *.example.com as example.com, because each entry also covers its subdomains.
  • It removes duplicate entries.
The API refuses these entries with 422:
  • URLs, paths, and ports, such as https://example.com/ or example.com:443.
  • IP addresses.
  • Other wildcards, such as shop.*.com.
  • A domain that is in both allow and block.
A policy has at most 10,000 domains in allow and block together. A project has at most 100 policies. A request over a limit returns 422.

​
How a policy decides

An entry covers the domain and all of its subdomains. When more than one entry matches a host, the most specific entry wins. If no entry matches, the browser uses defaultAction. With the policy above: To make an allowlist, set defaultAction to "block" and put the permitted domains in allow:
The Browser Use security blocklist always applies first. An entry in allow does not open a domain that this blocklist blocks.

​
Use a policy

​
Standalone browsers

Put networkPolicyId in the body of POST /api/v4/browsers:
curl

​
Agent runs

Put networkPolicyId in the run’s browserSettings:
The ID must name a policy of your project. Else the request returns 404. For a follow-up run in the same session:
  • If you omit networkPolicyId, the run keeps the session’s policy.
  • If you send null, the run uses no policy.
  • If the policy differs from the policy of the open browser, Browser Use does not reuse that browser. It starts a new browser with the new policy.

​
Browser Use proxy with an API key

If you use the Browser Use proxy with your API key as the proxy password, add -policy-<id> to the proxy username, for example user-country-us-policy-6f1c2a4e-8b0d-4e7a-9f3c-2d5b7e9a1c40.

​
Blocked requests

The proxy refuses a blocked request with 403. In the browser, the page does not load and shows a network error. An agent sees the same error.

​
Change or delete a policy

PATCH /api/v4/network-policies/{id} changes only the fields that the request contains. A domain list in the request replaces the whole list:
curl
Running browsers get the change within a few seconds. When the change blocks more domains, the proxy closes the open connections of the browsers, and the new policy decides each new connection. DELETE /api/v4/network-policies/{id} returns 204. Browsers that use the policy continue without a network policy within a few seconds. The Browser Use security blocklist still applies.

​
Endpoints

See also Proxies.