The latest Browser Run scripting update introduces a pair of HTTP endpoints that let you hand over a JavaScript function—written for Playwright, Puppeteer, or the raw Chrome DevTools Protocol—and have Cloudflare execute it inside a temporary Worker that is already linked to a browser instance. Because the Worker is created on demand, you no longer have to maintain a dedicated Worker deployment just to drive a headless browser.
What changed in the API
POST /browser-run/scriptnow accepts a JSON payload with acodefield containing an async function and alibraryidentifier (e.g.,playwright). The service spins up a browser, runs the function, and returns the function’s result wrapped in{"success":true,"result":...}.- The response includes
cf-browser-session-idandcf-browser-target-idheaders, exposing the underlying session and page identifiers for later reuse. - A second endpoint,
POST /browser-run/script/<sessionId>, lets you execute additional scripts against an existing session, optionally targeting a specific page viatargetIdor creating parallel pages. - Launch options such as
keep_alive,recording, andlabare supplied via the query string. Selectingbrowser=kitesurfswitches the runtime to a CDP‑only mode. - Workers can call the same endpoints through the built‑in
env.BROWSER.script()binding, eliminating the need for an API token. - The dashboard now offers a Script Studio UI for interactive testing without any token.
- Sessions persist after script execution; they must be closed explicitly with
DELETE /devtools/browser/<sessionId>or by invokingbrowser.close().
Why it matters to engineers
- AI/ML pipelines: Inline browser automation can fetch dynamic content or render JavaScript‑heavy pages directly before feeding data to models, reducing data‑staging steps.
- Cloud/platform teams: Eliminating a permanent Worker reduces surface area, simplifies Terraform or Pulumi definitions, and cuts operational overhead.
- DevOps/SRE: On‑demand scripts can be integrated into CI/CD jobs for smoke‑testing UI flows or verifying deployment health without managing separate test infrastructure.
- Security engineers: The isolated Worker model limits code execution to the request scope, and session identifiers are exposed only in response headers, making it easier to audit and control access.
Architectural and operational considerations
- Each
/scriptcall creates a short‑lived Worker; budgeting for Worker execution time and associated request costs is advisable. - Reusing a session via
/script/<sessionId>can improve performance for multi‑step workflows, but it also requires tracking the session ID across calls. - Choosing
browser=kitesurflimits the runtime to CDP, which may be preferable for low‑level debugging or when Playwright/Puppeteer libraries are unnecessary. - When invoked from a Worker binding, authentication is handled by the platform, removing token management but still requiring the Worker’s execution role to have Browser Run permissions.
- Idle timeout policies apply to sessions that are not explicitly closed; monitoring for orphaned sessions can prevent resource leakage.
Security implications
- The isolation of the execution environment means that the submitted script cannot directly access other Workers or internal services unless explicitly coded to do so.
- Session and target IDs are returned in response headers; protecting these values in logs and downstream systems is essential to avoid unintended reuse.
- Because the API does not close sessions automatically, lingering sessions could be a vector for abuse if an attacker obtains a valid
sessionId. Implementing strict access controls around who can callDELETE /devtools/browser/<sessionId>mitigates this risk. - When using the dashboard’s Script Studio, no API token is required, but the same isolation guarantees apply; ensure that only authorized personnel have dashboard access.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Adopt the new /script endpoints for any workflow that currently relies on a dedicated Worker to drive a browser. Start by refactoring existing automation scripts into the JSON payload format and test session reuse for multi‑step processes. Track session identifiers and enforce cleanup policies to avoid resource waste. Finally, review your role‑based permissions to ensure that only trusted identities can invoke the scripting API or delete sessions.
