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).

​
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.