Skip to content

Fix/browser runtime macos - #719

Open
jdoepfert wants to merge 5 commits into
andrewyng:mainfrom
jdoepfert:fix/browser-runtime-macos
Open

jdoepfert wants to merge 5 commits into
andrewyng:mainfrom
jdoepfert:fix/browser-runtime-macos

Conversation

@jdoepfert

Copy link
Copy Markdown

Browser tools: one-time setup script for the macOS app

Fixes #718. Refs #413 (same problem on Windows, not covered here).

Problem

The macOS app doesn't include Playwright, and its bundled Python ignores anything installed outside the app. So every browser_* tool fails, and the error's pip install playwright advice can't help.

Fix

Instead of bundling Playwright and Chromium, which would make the app much bigger, users opt in once:

curl -fsSL https://raw.githubusercontent.com/andrewyng/openworker/main/packaging/setup-browser-macos.sh | bash
  • packaging/setup-browser-macos.sh installs Playwright 1.63.0, built for the app's own Python, plus Chromium into ~/.config/coworker/browser-runtime/ (about 700 MB). --uninstall removes it.
    • Reads the app's Python version from the installed bundle (falls back to 3.12), so it keeps working when the app moves to a newer Python.
    • Works on Apple Silicon and Intel (asks pip for macosx_12_0 wheels, the app's minimum).
    • Needs macOS 14 or later: Playwright 1.63's Node driver needs 13.5, its Chromium 14. On older Macs it stops with a clear message. The rest of OpenWorker still runs on macOS 12+.
    • After a reinstall (e.g. a Playwright bump), it tells the user to restart OpenWorker.
  • App: browser_automation.py and tools.py look in that folder before importing Playwright. Nothing is written inside OpenWorker.app, so the signature stays intact.
  • Error messages:
    • Playwright missing: the macOS app shows the setup command instead of pip install.
    • Chromium won't start: reported as that, not as "requires Playwright".
  • Docs: README and the Browser connector page explain the setup and the macOS 14 requirement.

Testing

  • tests/test_browser_runtime_setup.py, plus the existing browser, connector and catalog tests (184 passed)
  • Script on macOS 26 (Apple Silicon): first install and reinstall; macOS < 14 refusal with a faked version; Intel package resolution checked with a dry-run pip download
  • Frozen server built from the spec launches Chromium from that folder; without it, it shows the new error
  • browser_open_url and browser_read_page work on example.com through the installed folder
  • Full app build (build_dmg.sh) tested in a real session

Related

#396 and #361 replace the browser tools entirely. This is the minimal fix without growing the app, and becomes unnecessary if either lands. #564 touches the same _BrowserController.page().

🤖 Generated with Claude Code

jdoepfert and others added 5 commits October 3, 2026 19:17
- Introduced `setup-browser-macos.sh` for installing Playwright and Chromium.
- Updated `_use_browser_runtime` to ensure Playwright is importable in the packaged app.
- Enhanced error handling in `_BrowserController` to guide users on installation.
- Added tests for runtime integration and error handling.
Intel Macs. The script now asks for macosx_12_0_<arch> packages on both Intel and Apple Silicon. With the old setting, Intel Macs couldn't find a matching greenlet package and the install failed. A test download for Intel now succeeds.
Older macOS. The script now stops on macOS 12 or 13 with: "The browser tools need macOS 14 or later (this Mac runs 13.6). The rest of OpenWorker works without them." I tested this by making the script believe it was on 13.6. The README now says "macOS 14 or later".
Playwright updates.
The script now reads the Python version from the installed app (…/_internal/python3.12), so a future app on a newer Python gets matching packages. If no app is found, it assumes 3.12, as before.
On a reinstall it now ends with "Quit and reopen OpenWorker". A running app keeps the old Playwright loaded, which clashes with the new download.
Error message. "requires Playwright" now only appears when Playwright is actually missing. If Playwright is there but Chromium won't start, the tool says "The browser could not start…" with the details. A test covers this.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Built-in browser tools don't work in the macOS app

1 participant