Allowed domains let you restrict which websites a session can navigate to. If you pass one or more domains, Browserbase blocks top-level page navigations to any domain not on the list. This keeps automated sessions focused and prevents unintended navigation.
This feature is experimental and its behavior may change in future releases.
Restricting navigation
Use the allowedDomains field in browserSettings when creating a session to specify which domains are permitted. Below are examples in both Node.js and Python SDKs.
import Browserbase from "@browserbasehq/sdk";
const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
async function createSession() {
const session = await bb.sessions.create({
browserSettings: {
allowedDomains: ["example.com", "docs.example.com"],
},
});
console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
return session;
}
const session = createSession();
from browserbase import Browserbase
import os
bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])
def createSession():
session = bb.sessions.create(
browser_settings={
"allowedDomains": ["example.com", "docs.example.com"],
},
)
print(f"Session URL: https://browserbase.com/sessions/{session.id}")
return session
session = createSession()
Limitations:
- Subdomain matching: Adding
example.com also permits www.example.com, a.b.example.com, and any other subdomain. You do not need to list subdomains separately.
- Top-frame navigation only: Browserbase checks top-frame navigations. It does not block iframe/subframe loads or in-page resource requests (images, scripts, XHR, etc.).
- HTTP(S) domains only: Browserbase does not apply the allowlist to navigations to
about:blank, chrome://, file://, and similar URLs.
