Session Inspection & Recording

See how to debug automation sessions via a real-time graphical interface.

Oxylabs Headless Browser provides Session Inspection and Session Recording to observe browser automation in real time or review video playbacks of past sessions. These visual debugging features allow you to:

• Diagnose complex issues that aren't evident from logs or error messages
• Understand page rendering exactly as the browser sees it
• Verify proper execution of your automation workflows
• Troubleshoot unexpected behavior in real-time

Both tools route their visual data through the headlesify.io domain (separate from oxylabs.io used for connections).

Session Inspection (VNC)

Session Inspection tool is a debugging feature that uses VNC (Virtual Network Computing) to provide real-time visual access to your browser automation sessions.

You can enable the Session Inspection tool by using the vnc.headlesify.io endpoint. This opens a noVNC viewer you can watch in your browser. Retrieve the viewer URL from the session ID:

const cdp = await ctx.newCDPSession(page);
const { value: sid } = await cdp.send("__session_id");
const vncUrl = `https://vnc.headlesify.io/novnc/?id=${sid}`;
console.log(vncUrl);  // open this URL in your browser

Session Recording

Record your entire Headless Browser session as a video for debugging, auditing, or reviews. To record a session, add the record=true query parameter to your connection URL:

wss://USER:[e-mail]?record=true

Customizing recording names

Organize and filter your recordings inside your dashboard by assigning custom names to your videos using the record_name parameter. You can use alphanumeric characters with hyphens and underscores, up to a maximum length of 64 characters (^[a-zA-Z0-9_-]{1,64}$):

wss://USER:[e-mail]?record=true&record_name=payment_checkout_flow_01

Accessing playbacks

All completed recordings are automatically encoded and saved to your secure portal. You can search, filter, and review your recordings at https://dashboard.headlesify.io/#recordings.

Code examples

The following Node.js example shows how to connect to the browser with visual options enabled, extract the VNC session ID programmatically, and output the live stream link to your console.

Features support both Playwright and Puppeteer libraries.

import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "ubc.oxylabs.io";

// Enable VNC stream and video recording under a custom name
const params = "o_vnc=true&record=true&record_name=chrome_vnc_test";
const browserUrl = `wss://${username}:${password}@${endpoint}?${params}`;

(async () => {
    // Connect to the browser
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0] || (await browser.newContext());
    const page = ctx.pages()[0] || (await ctx.newPage());

    try {
        // 1. Initialize a CDP session on the active page
        const cdpSession = await ctx.newCDPSession(page);
        
        // 2. Query the custom session identifier
        const { value: sessionId } = await cdpSession.send("__session_id");
        
        // 3. Construct and output the VNC viewer link
        console.log(`Live VNC Link: https://vnc.headlesify.io/novnc/?id=${sessionId}`);

        // Execute your automation steps
        await page.goto("https://example.com");
        
        // Hold session open briefly to allow visual monitoring via VNC link
        await new Promise(resolve => setTimeout(resolve, 10000));

    } catch (error) {
        console.error("Visual session execution failed:", error.message);
    } finally {
        await browser.close();
        console.log("Recording compiled. Access playback at https://dashboard.headlesify.io/#recordings");
    }
})();