brought support for running Fara on Windows devices

[danielkornev]

Summary

Running the agent with --headful on Windows caused the browser to crash immediately with:

[WinError 2] The system cannot find the file specified

The root cause was that the code attempted to launch Xvfb—a Linux virtual framebuffer that does not exist on Windows. This resulted in repeated failures to start the browser.

This PR updates the browser initialization logic to only start Xvfb on Unix-like systems and skip it on Windows, where Playwright can run headfully using the native display.

The Problem

• When launching in headful mode, both _init_regular_browser() and _init_persistent_browser() attempted to start Xvfb unconditionally.
• On Windows, this caused a [WinError 2] because Xvfb is not present.
• Cleanup code also attempted to stop Xvfb even when it was never started, triggering additional errors.

The Solution

• Added import platform and OS detection.
• Xvfb is now started only on Linux/macOS.
• On Windows:
  • Browser launches normally using the native GUI—no Xvfb required.
  • Cleanup logic no longer tries to stop Xvfb.
• Headful mode now works correctly on Windows devices.

Changes in This PR

• Added platform check using platform.system()
• Updated _init_regular_browser() to skip Xvfb on Windows
• Updated _init_persistent_browser() to skip Xvfb on Windows
• Updated close() method to only stop Xvfb on non-Windows systems
• Minor cleanup and safeguards to avoid unnecessary error logs

Testing

Repro command (now fixed):

python test_fara_agent.py --headful --task "how many pages does wikipedia have" --start_page "https://www.bing.com" --endpoint_config "endpoint_configs/azure_foundry_config.json"

Verified on Windows:

• Browser now launches visibly
• No crashes
• Agent workflow proceeds as expected

Why This Matters

This fix restores support for Windows devices—an important platform for developers using FARA. Since headful mode is essential for debugging agent behavior, this significantly improves the Windows developer experience.

[Copilot]

Pull request overview

This PR fixes a critical bug that prevented FARA from running in headful mode on Windows devices. The issue was caused by unconditional attempts to start Xvfb (a Linux virtual framebuffer) which doesn't exist on Windows, resulting in a [WinError 2] crash. The fix adds platform detection to skip Xvfb initialization on Windows while maintaining existing behavior on Linux/macOS.

Key Changes:

• Added platform module import for OS detection
• Modified browser initialization to conditionally start Xvfb only on non-Windows systems
• Updated cleanup logic to avoid stopping non-existent Xvfb processes on Windows

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

[nitpick] Consider caching the platform check result as a class attribute during __init__ (e.g., self.is_windows = platform.system() == "Windows"). Currently, platform.system() is called in three different methods (_init_regular_browser, _init_persistent_browser, and close), which could be optimized by computing it once. This would also improve code readability by making the Windows detection logic more explicit.

[danielkornev]

@copilot open a new pull request to apply changes based on this feedback

[husseinmozannar]

@copilot open a new pull request to apply changes based on this feedback

[cheekjames104-stack]

Wanna play

[danielkornev]

Is there anything else needed to accept this PR?

[husseinmozannar]

Hi @danielkornev , I found there were a few other fixes needed to work on Windows, I made them in PR @danielkornev and merged that. Thank you again for your contribution, I'll be closing this PR and issue as resolved.

[danielkornev]

Thanks a lot for the quick turnaround! I just tested the update on Windows and everything works great now. Really appreciate the improvements you added on top of the original PR.