mirror of
https://github.com/browseros-ai/BrowserOS.git
synced 2026-05-13 15:46:22 +00:00
bb62213e84
* fix: install linux sysroot in configure, not via gclient hook `gn gen` was failing on the arm64 leg with `Missing sysroot (//build/linux/debian_bullseye_arm64-sysroot)`. The previous design relied on `git_setup` writing `target_cpus` to `.gclient` so that `gclient sync`'s DEPS hook would download the cross-arch sysroot. That chain breaks for any chromium_src that was synced before cross-arch support landed (the hook is gated on .gclient state at sync time) and for partial pipeline runs that skip git_setup entirely. Nothing in configure declared or verified its sysroot precondition. Make configure self-healing: on Linux, invoke `build/linux/sysroot_scripts/install-sysroot.py --arch=<target>` directly before `gn gen`. install-sysroot.py is idempotent (stamp file + SHA check), fast when already installed, and decoupled from .gclient — it's exactly what the failing assertion's error message recommends. The script accepts our arch names directly: `x64` translates to `amd64` internally via ARCH_TRANSLATIONS, and `arm64` is a valid pass-through. Also temporarily pin release.linux.yaml to x64 only while we validate the sysroot bootstrap end-to-end. Flip back to `[x64, arm64]` once arm64 is green. * chore: pin release.linux.yaml to arm64-only for sysroot bootstrap test x64 already builds cleanly — the failing leg is arm64 cross-compile from an x64 host. Pin the config to arm64 to exercise the new install-sysroot.py path in configure without burning time on x64. Flip back to [x64, arm64] once arm64 is green.
BrowserOS Browser (Chromium Fork)
Custom Chromium build with AI agent integration, enhanced privacy patches, and native MCP support.
Based on Chromium 146.0.7680.31 · Built with Python 3.12+ · Licensed under AGPL-3.0
What This Is
This package contains the BrowserOS browser build system — everything needed to fetch Chromium source, apply BrowserOS patches, and produce signed binaries for macOS, Windows, and Linux. The build system is a Python CLI that orchestrates the entire pipeline from source to distributable.
BrowserOS patches add:
- Native AI agent sidebar and new tab integration
- MCP server endpoints baked into the browser
- Enhanced privacy via ungoogled-chromium patches
- Custom branding, icons, and entitlements
- Keychain access group management (macOS)
- Sparkle auto-update framework (macOS)
Prerequisites
| Requirement | Details |
|---|---|
| Disk space | ~100 GB for Chromium source + build artifacts |
| Python | 3.12+ |
| macOS | Xcode + Command Line Tools |
| Linux | build-essential, clang, lld, and Chromium's Linux deps |
| Windows | Visual Studio 2022, Windows SDK |
Directory Structure
packages/browseros/
├── build/ # Build system (Python CLI)
│ ├── __main__.py # CLI entry point
│ ├── browseros.py # Main app definition
│ ├── modules/
│ │ ├── setup/ # Chromium source fetch and setup
│ │ ├── patches/ # Patch application logic
│ │ ├── apply/ # Apply patches to source tree
│ │ ├── extract/ # Extract patches from modified source
│ │ ├── feature/ # Feature flag management
│ │ ├── package/ # Binary packaging
│ │ ├── sign/ # Code signing (macOS, Windows)
│ │ ├── ota/ # Over-the-air update support
│ │ └── resources/ # Resource management
│ ├── config/ # Build configuration
│ └── features.yaml # Feature flag definitions
│
├── chromium_patches/ # BrowserOS patches applied to Chromium source
│ ├── chrome/browser/ # Browser UI and feature patches
│ ├── components/ # Component patches (e.g., os_crypt)
│ └── ... # Organized to mirror Chromium source tree
│
├── chromium_files/ # New files added to Chromium (not patches)
├── series_patches/ # Ordered patch series
├── resources/ # Icons, entitlements, signing resources
│ └── entitlements/ # macOS entitlements (app, helper, GPU, etc.)
│
├── tools/
│ └── bdev # Developer tool
│
├── CHROMIUM_VERSION # Pinned Chromium version (MAJOR.MINOR.BUILD.PATCH)
├── BASE_COMMIT # Base Chromium commit hash
├── pyproject.toml # Python project config
└── requirements.txt # Python dependencies
Build System
The browseros CLI manages the full build lifecycle:
# Install the build system
pip install -e .
# Or use uv
uv pip install -e .
Key commands:
browseros setup # Fetch and prepare Chromium source
browseros apply # Apply all patches to Chromium source
browseros build # Build BrowserOS binary
browseros package # Package into distributable (DMG, installer, AppImage)
browseros sign # Code sign the binary (macOS/Windows)
Patch System
BrowserOS applies patches on top of vanilla Chromium. Patches are organized in two directories:
chromium_patches/— Individual file patches, organized to mirror the Chromium source tree. Each file here replaces or modifies the corresponding file in Chromium.series_patches/— Ordered patch series applied sequentially.
Adding a New Patch
- Make your changes in the Chromium source tree
- Use
browseros extractto pull changes back into patch format - Place the patch in the appropriate directory mirroring Chromium's structure
- Test with a full
browseros apply && browseros buildcycle
Chromium Version Pinning
The exact Chromium version is pinned in CHROMIUM_VERSION:
MAJOR=146
MINOR=0
BUILD=7680
PATCH=31
To update the base Chromium version, update this file and BASE_COMMIT, then resolve any patch conflicts.
Signing (macOS)
macOS builds require code signing for Keychain access, Gatekeeper, and notarization:
- Entitlements are in
resources/entitlements/(app, helper, GPU, renderer, etc.) - Designated requirements pin to Team ID for Keychain persistence across updates
- The signing module is at
build/modules/sign/macos.py
Feature Flags
Feature flags are defined in features.yaml and control which BrowserOS-specific features are compiled into the build. The feature module (build/modules/feature/) manages flag resolution at build time.
Related Resources
- Chromium Build Instructions
- ungoogled-chromium — upstream privacy patches
- BrowserOS Agent Platform — the TypeScript/Go agent system that runs inside the browser