Skip to main content
Figranium includes powerful Headful Debugging capabilities that allow you to see and interact with the automation as it runs. This is powered by a VNC server running alongside the Playwright container.

​
Why Headful?

  • Debugging: Step through tasks visually to identify why a selector fails.
  • Manual Intervention: Solve CAPTCHAs or complete complex 2FA flows that automation cannot handle.
  • Exploration: Browse sites naturally to discover selectors and API endpoints.
  • Recording: Create high-fidelity video demonstrations of your automation.

​
Starting a Headful Session

  1. Editor: Open a task in the editor.
  2. Run: Click Open Browser in the editor panel to log in or debug visually.
The browser window will open inside the VNC viewer embedded in the UI.

​
Controls

The VNC interface provides a standard desktop environment:
  • Mouse/Keyboard: Full interaction support.
  • Clipboard: Copy/paste text between your host and the remote browser.
  • Resolution: The viewport resizes dynamically (default 1920x1080).

​
Popups and multi-page navigation

Headful sessions automatically track the active browser page across popups and new tabs. When a site opens a popup — for example, an OAuth login window or a payment gateway — Figranium switches to the new page so you can interact with it in the VNC viewer. When that page closes, the session returns to the previous page. This means workflows that span multiple pages work without any extra configuration:
  • OAuth and SSO flows: Complete third-party login prompts that open in a popup.
  • Payment windows: Interact with payment providers that redirect through a new tab.
  • Multi-tab browsing: Open links in new tabs and switch between them naturally.
If all pages in a session are closed, the headful session remains active and waits for a new page to open.

​
Persistence

Headful sessions use a dedicated persistent browser profile directory (data/browser-profile-headful). Cookies are automatically synced to agent and scrape runs via data/headful-storage-state.json:
  • Sync interval: Every 30 seconds while a headful session is active.
  • Sync on close: Cookies are also saved when the headful session is stopped via Close Browser.
  • Agent & scrape pickup: Each non-stateless agent or scrape run injects the saved cookies at startup, so they pick up any session established in headful.
This means the typical workflow still works:
  1. Login once: Log in manually in the headful browser.
  2. Automate: Run an Agent or Scrape task — it will automatically have those cookies available.
Note: Only non-expired cookies are synced. If headful-storage-state.json does not exist yet (no headful session has run), agent and scrape runs simply start with their own profile cookies. Stateless Option: Enable statelessExecution to launch a clean, incognito-like session that won’t save cookies and won’t receive headful cookies.

​
Element picking

The headful browser doubles as a selector discovery tool. When you click the Highlight Tool icon in an action block’s selector field, Figranium opens a headful session with inspect mode already active — no extra step required.
  1. The crosshair overlay appears automatically in the VNC viewer.
  2. Hover over any element to see it highlighted with a tooltip showing the top selector candidates.
  3. Click the element to confirm your selection.
Figranium generates up to five selector alternatives, ranked from most readable to most structural. The best candidate auto-fills the selector field, and the alternatives appear as clickable pills below the input so you can compare and switch without re-picking. See CSS Selectors — Built-in Highlight Tool for details on the ranking algorithm.

​
Variable support

Headful sessions resolve task variables in the starting URL. For example, if your task defines a variable site, you can set the headful URL to: 
https://{$site}.example.com/dashboard
Figranium replaces the variable with its current value before navigating.

​
API integration

You can start a headful session programmatically: 
curl -X POST http://localhost:11345/headful \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
The response includes the VNC connection URL.

​
Stopping

Click Close Browser in the Editor to terminate the session and close the browser. This ensures resources are freed.