Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.driver.dev/llms.txt

Use this file to discover all available pages before exploring further.

View your browser sessions in real-time and perform manual actions directly in your browser.

​
Live Session Viewer

Driver provides a live viewer where you can watch and interact with your browser session in real-time. To view a session, construct the viewer URL using your session’s cdpUrl: 
https://viewer.driver.dev?ws=<encoded-cdp-url>
1

Create a session

Start a browser session and retrieve the cdpUrl from the response.
2

URL-encode the cdpUrl

Encode the WebSocket URL so it can be passed as a query parameter.
3

Open the viewer

Navigate to the constructed URL in your browser to view the session live.
const session = await client.browser.session.create();

// URL-encode the CDP WebSocket URL
const encodedWs = encodeURIComponent(session.cdpUrl);
const viewerUrl = `https://viewer.driver.dev?ws=${encodedWs}`;

console.log("View your session live:", viewerUrl);
The live viewer allows you to see exactly what your automation is doing and manually interact with the browser — click elements, type text, or navigate to different pages.

​
Viewer Parameters

ParameterValuesDescription
wsURL-encoded WSSThe CDP WebSocket URL from your session
themelight, darkViewer color theme

​
Get Session Details

const session = await client.browser.session.get({
  sessionId: "sess_abc123xyz",
});

console.log(session);

​
Response

{
  "sessionId": "sess_abc123xyz",
  "status": "active",
  "servedBy": "node-us-east-1",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "stoppedAt": null,
  "cdpUrl": "<returned-cdp-url>"
}

​
Session Status Values

StatusDescription
activeSession is running and accepting connections
stoppedSession has been terminated
failedSession failed to start

​
List All Sessions

Retrieve paginated list of all your sessions: 
const sessions = await client.browser.sessions.list({
  page: 1,
  pageSize: 20,
});

console.log(sessions);

​
Pagination Parameters

ParameterTypeDefaultDescription
pagenumber1Page number
pageSizenumber20Results per page

​
Monitoring Sessions

Poll session status to monitor long-running tasks: 
async function waitForSession(sessionId: string, timeout = 30000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const session = await client.browser.session.get({ sessionId });

    if (session.status === "active" && session.cdpUrl) {
      return session;
    }

    if (session.status === "failed") {
      throw new Error("Session failed to start");
    }

    await new Promise((r) => setTimeout(r, 1000));
  }

  throw new Error("Session startup timeout");
}

​
Next Steps