Live View

import { CURL, DashButton, TypeScriptExample } from "~/components";

Live View lets you see and interact with a remote Browser Run session in real time. This is useful for debugging automation scripts, monitoring what a browser is doing, or manually stepping in when a task requires human intervention (see Human in the Loop).

Live View is available for any Browser Session, including sessions created with Puppeteer, Playwright, or the Chrome DevTools Protocol (CDP) endpoints.

A browser session is one remote Chrome instance. A session can contain multiple tabs. CDP calls each debuggable item a target, and a page target usually represents one browser tab. Live View connects to a page target.

Access Live View

Open Live View from the Cloudflare dashboard or with a generated devtoolsFrontendUrl. A generated URL opens Cloudflare's hosted interface in any browser. Chrome users can instead open the connection in Chrome DevTools.

Cloudflare dashboard

In the Cloudflare dashboard, go to the Browser Run page and select the Live Sessions tab. This shows all active browser sessions in your account. Expand a session to see its tabs, then select Open to open the Live View for that tab.

:::note Sessions created from the dashboard default to a five-minute inactivity timeout (keep_alive), compared to the one-minute default when creating sessions through the API. To adjust the timeout in the dashboard, use the timeout field when creating a session. In the API and Workers Bindings, use the keep_alive option, which accepts up to 20 minutes. :::

Generated URL (any browser)

When you create a session with targets=true or list a session's targets, the API response includes a devtoolsFrontendUrl for each page target. Open this URL in any browser to watch or control that tab through Cloudflare's hosted interface. The generated URL uses live.browser.run; you do not visit that hostname directly.

The hosted UI supports three viewing modes, controlled by the mode parameter in the URL:

Native Chrome DevTools (Chrome only)

Browser Run supports CDP, the protocol that powers Chrome DevTools. If a generated devtoolsFrontendUrl starts with https://live.browser.run/ui/inspector?wss=, replace that prefix with devtools://devtools/bundled/inspector.html?wss=:

devtools://devtools/bundled/inspector.html?wss=live.browser.run/api/devtools/browser/SESSION_ID/page/TARGET_ID?jwt=...

Paste the updated URL into Chrome's address bar. Chrome opens its built-in DevTools interface for the remote tab. The devtools:// protocol works only in Chrome and supports only the devtools viewing mode.

:::caution[URL validity] The devtoolsFrontendUrl is valid for five minutes by default. This is the deadline for starting a connection, not the duration of an established connection or browser session. Set expiresInMs when generating a custom URL to change the deadline, up to one hour. If the URL expires before you connect, generate a new one. An established connection remains active while the browser session is alive. :::

The API examples in the following sections assume $ACCOUNT_ID is set and $CLOUDFLARE_API_TOKEN has Browser Rendering Write permission.

View a new session

1. Create a browser session with targets=true to include its current page targets and generated Live View URLs in the response:

<CURL url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser" method="POST" headers={{ Authorization: "Bearer $CLOUDFLARE_API_TOKEN", }} query={{ keep_alive: "600000", targets: "true", }} />

{
	"sessionId": "1909cef7-23e8-4394-bc31-27404bf4348f",
	"targets": [
		{
			"description": "",
			"devtoolsFrontendUrl": "https://live.browser.run/ui/inspector?wss=live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=...",
			"id": "8E598E996530FB09E46A22B8B7754F7F",
			"title": "about:blank",
			"type": "page",
			"url": "about:blank",
			"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/1909cef7-.../page/8E598E99...?jwt=..."
		}
	],
	"webSocketDebuggerUrl": "wss://api.cloudflare.com/client/v4/accounts/{account_id}/browser-run/devtools/browser/1909cef7-..."
}

The targets[].devtoolsFrontendUrl opens the hosted interface for a page. The targets[].webSocketDebuggerUrl connects a CDP client to that page. The top-level webSocketDebuggerUrl connects a CDP client to the browser session.

2. Find the page target you want by its title or url. Copy its devtoolsFrontendUrl and open it in your browser. A new session initially contains an about:blank page.

View an existing session

If you have a running session and want to connect to it:

1. List your active sessions and copy the ID of the session you want to view:

   <CURL url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/session" method="GET" headers={{ Authorization: "Bearer $CLOUDFLARE_API_TOKEN", }} />

2. Using the session ID, list the targets in that session:

   <CURL url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/json/list" method="GET" headers={{ Authorization: "Bearer $CLOUDFLARE_API_TOKEN", }} />

   [
   	{
   		"id": "110850A800BDB8B593CDDA30676635CF",
   		"type": "page",
   		"url": "https://example.com",
   		"title": "Example Domain",
   		"description": "",
   		"devtoolsFrontendUrl": "https://live.browser.run/ui/view?wss=live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=...",
   		"webSocketDebuggerUrl": "wss://live.browser.run/api/devtools/browser/28d75446-.../page/110850A8...?jwt=..."
   	}
   ]
   

3. Copy the devtoolsFrontendUrl and open it in your browser.

Generate a Live View URL

Listing targets returns a default devtoolsFrontendUrl for every page target. Generate a custom URL to change its viewing mode, connection deadline, or viewer permissions.

Set parameters

The following optional parameters configure generated links:

The REST API response includes id, options, devtoolsFrontendUrl, and webSocketDebuggerUrl. Open the frontend URL in a browser or use the WebSocket URL with a CDP client. The Cloudflare.getLiveView CDP command returns devtoolsFrontendUrl.

:::caution[Treat Live View URLs as credentials] A Live View URL contains a signed jwt value. Anyone with the complete URL can access the permitted connection. Share it only through trusted channels. A read-only link still exposes visible page data.

Generate Live View URLs from trusted server-side code. Never expose $CLOUDFLARE_API_TOKEN in browser code. :::

A read-only Live View guardrail applies only to the generated connection. Other connections and automation scripts can still control the session. Session guardrails restrict HTTP and HTTPS destinations for the entire session and remain active for every Live View connection.

REST API

Use the Live View endpoint to generate a URL:

<CURL url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/live_view" method="POST" headers={{ Authorization: "Bearer $CLOUDFLARE_API_TOKEN", }} json={{ mode: "tab", expiresInMs: 300000, }} />

Share a view-only link

To block viewer interaction, set guardrails to { "mode": "readonly" }:

<CURL url="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/browser-run/devtools/browser/$SESSION_ID/live_view" method="POST" headers={{ Authorization: "Bearer $CLOUDFLARE_API_TOKEN", }} json={{ mode: "tab", guardrails: { mode: "readonly" }, }} />

The link streams the session but blocks navigation, input, and JavaScript evaluation. The tab title starts with READ ONLY - .

:::caution A view-only link is for humans, not automation. Puppeteer and Playwright cannot drive a read-only connection because the required commands are blocked. :::

CDP

CDP is Chrome's remote debugging protocol. Cloudflare.getLiveView is a Cloudflare extension that generates a Live View URL over an existing CDP connection. This Puppeteer example generates a URL for the current page:

import type { Page } from "@cloudflare/puppeteer";

export async function getLiveViewUrl(page: Page): Promise<string> {
	const cdp = await page.createCDPSession();

	const { devtoolsFrontendUrl } = await cdp.send("Cloudflare.getLiveView", {
		mode: "tab",
		expiresInMs: 300000,
	});

	return devtoolsFrontendUrl;
}

To use Live View for a human operator handoff, refer to the Human in the Loop workflow.