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:
Figranium replaces the variable with its current value before navigating.

​
API integration

You can start a headful session programmatically:
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.

​
Access control

Figranium’s VNC stack is hardened against unauthenticated access. If you connect to it through the embedded viewer in the UI, everything works automatically — this section is only relevant if you build a custom client or open a raw VNC connection.

​
Network binding

Both the VNC server (x11vnc) and the noVNC websocket proxy (websockify) bind to 127.0.0.1 only. They are not reachable from outside the container, even if you publish port 54311 on the Docker host. All browser traffic reaches the VNC session through the authenticated /websockify endpoint on the main Figranium port (default 11345).
If you were previously connecting a VNC client directly to <host>:54311 or <host>:5900, this no longer works. Connect through the Figranium UI, or proxy through wss://<host>:11345/websockify with a valid session cookie or API key.

​
VNC password

On first start, Figranium generates a random VNC password and writes it to data/vnc_password.txt. x11vnc requires this password for every connection, so a client that reaches port 5900 still cannot attach without it. The embedded noVNC viewer fetches the password automatically from an authenticated endpoint before connecting — you do not need to type it in. To retrieve the password for a custom client:
The endpoint requires an authenticated session or a valid API key. See GET /api/headful/vnc-password.
Treat data/vnc_password.txt like any other secret. It is stored inside the persistent data volume and remains valid across restarts. Delete the file to force regeneration on the next start.

​
Authenticated WebSocket upgrades

Every WebSocket upgrade to /websockify (used by noVNC) is validated before the connection is proxied to the VNC server. Requests must satisfy all of the following:
  • Originate from an IP address permitted by ALLOWED_IPS.
  • Present an Origin header that matches the request Host (CSWSH protection). If both Origin and Host resolve to loopback or private addresses (localhost, 127.0.0.1, ::1, host.docker.internal, any *.local hostname, or an RFC 1918 private range), the ports and aliases do not need to match. This lets Vite dev servers, Docker port mappings, and IPv6 loopback aliases connect without tripping the CSWSH check while still rejecting cross-origin upgrades from public hosts.
  • Carry either a valid session cookie or an API key (x-api-key header or ?apiKey= query parameter).
Unauthenticated upgrade attempts are dropped and logged with a [SECURITY] prefix on the server console. If you build a custom noVNC client, pass your API key on the WebSocket URL: