BrowserOS Documentation

Browseros Onboarding (`docs/browseros/onboarding.mdx`) Copy Section

title: "Getting Started" Copy Chapter

Welcome to BrowserOS! Let's get you set up.

1. Go to `chrome://settings/importData`
2. Select **Google Chrome** and click **Import**
3. Choose **Always allow** when prompted

<Tip>
This imports everything in one click — bookmarks, passwords, history, and extensions.
</Tip>

**Quick option:** Get a free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — 20 requests per minute at no cost.

<Card title="Configure your LLM" icon="key" href="/browseros/features/bring-your-own-llm">
  Set up Gemini, Claude, OpenAI, or run models locally with Ollama
</Card>

- **Chat Mode:** Ask questions about the page
- **Agent Mode:** Describe a task and watch it execute

<Note>
For Agent Mode, use Claude Opus 4.5 or Sonnet 4.5. Local models work great for Chat but aren't powerful enough for agents yet.
</Note>

You're all set! Copy Chapter

Explore what BrowserOS can do:

Neo Audit And Replay (`docs/neo/audit-and-replay.mdx`) Copy Section

title: "Audit and replay" keywords: ["BrowserOS neo audit", "AI agent replay", "browser session recording", "local audit trail"] Copy Chapter

BrowserOS neo records everything your AI does in the browser so you can go back and see exactly what happened. All of it lives on your computer. Nothing goes to any server we control.

The audit trail Copy Chapter

Every session your AI runs shows up on the audit page. Search across all of them, filter by agent, status, or site, and click any row to open its full story.

Sessions land in one of three states:

• Live: the AI is still working.
• Done: it finished cleanly.
• Failed: something errored during the run.

What each session shows you Copy Chapter

Click any session and you get its full story: agent, timestamps, and every step the AI took, in order.

If the session used more than one tab, a tab strip lets you jump between them. Each tab has its own timeline of actions. Most steps include a screenshot of what the AI was looking at when it ran. Click one to open it full-size.

Sessions also carry a View Session Replay button that unlocks as soon as replay data lands.

Replay like a video Copy Chapter

Click View Session Replay to watch the whole session play back. The replay is the actual page the AI saw, not just a screenshot: DOM changes, scrolls, clicks, everything as it happened.

Use the scrubber to jump to any moment. Click any step on the right timeline to skip the replay straight to that action. If the session touched multiple tabs, switch between them at the top; each tab is its own recording with its own time origin.

Where all of this lives Copy Chapter

Everything you see on these pages sits in one folder on your computer: ~/.browserclaw/ in your home directory.

• ~/.browserclaw/browserclaw.sqlite is the shared database for audit history, tasks, sessions, recording indexes, tab claims, and tab ownership.
• ~/.browserclaw/screenshots/ is a JPEG per screenshotted step.
• ~/.browserclaw/replays/ is the recording data per session.

The BrowserOS neo server that reads and writes these files only accepts requests from your own machine. It binds 127.0.0.1, the local loopback, so nothing on your network can reach it. No account. No telemetry. No cloud sync.

If you want to delete a session or wipe everything, delete the files. That's it.

What isn't recorded Copy Chapter

• Your personal tabs. The recorder is only loaded into tabs your AI opened. Tabs you opened for your own work never get it. This isn't a policy on top of a general recorder; the recorder script is never even loaded there.
• Passwords. Any input marked as a password field is masked before it hits the recording.
• Canvas and mouse jitter. Canvas contents are not recorded. Cursor movements are not recorded either.

If you want the full picture, keep reading:

Neo Cockpit (`docs/neo/cockpit.mdx`) Copy Section

title: "Your dashboard" keywords: ["BrowserOS neo dashboard", "AI agent activity", "watch AI agent live", "session history"] Copy Chapter

Open a new tab in BrowserOS neo and you land on your dashboard. It shows what your AI is working on right now and what it did before, so you always know what happened without pinging your AI to check.

What you see Copy Chapter

Two regions stack on the page:

• Running now shows a live card for every AI that is actively working. It only appears when at least one AI is running.
• Recent activity shows the sessions your AIs already finished, newest first. Click any of them to open the full story.

Running now Copy Chapter

Every live agent gets its own card at the top of the dashboard.

Each card carries:

• A live preview of the browser tab your AI is looking at right now, updating as it works.
• A LIVE chip and a pulsing dot so you can tell at a glance which agents are actually doing something.
• The site title, the AI's name, and a short trail of the last few actions it took (like tabs → read → navigate).
• A tab-count chip in the corner so you know how many tabs this AI has open.
• Two buttons at the bottom of the card:
  • Watch switches your active tab to the one the AI is working in, so you can look over its shoulder.
  • Stop ends the session. If your AI went off the rails, one click cancels the run.

Recent activity Copy Chapter

Once a session finishes, it moves down into Recent activity. The most recent (or any still-live) session takes the big lead tile on the left. Four supporting tiles show what's after that. Anything older stacks in a compact typographic list below.

Each tile is clickable and takes you straight to the full session view, where you can read every action step by step or hit View Session Replay to watch the whole run like a video.

The home page holds the twelve most recent sessions. To see everything, click View all activity at the bottom of the section and you'll land on the full audit list.

Where to next Copy Chapter

Neo How It Works (`docs/neo/how-it-works.mdx`) Copy Section

title: "How BrowserOS neo works" keywords: ["BrowserOS neo setup", "connect AI to browser", "how BrowserOS neo works", "AI browser walkthrough"] Copy Chapter

This page walks you from a fresh download to your first AI-driven session. Six steps. About five minutes.

Once it's open, it works like Chrome or any other browser you've used. Bookmarks, extensions, keyboard shortcuts, all in the same places.

There is nothing special about this step. You are just using a browser. But it matters, because every account you sign in to here becomes something your AI can use later.

<Note>
Your AI cannot see your personal tabs unless you ask it to. It works in its own tabs, side by side with yours. Signing in to Gmail here means your AI can use Gmail when you ask it to. It does not mean your AI is reading your inbox while you're not looking.
</Note>

<Frame caption="The connect page: one endpoint, one click per AI tool.">
  
</Frame>

Find the AI tool you use: Claude Code, Cursor, Codex, Antigravity, VS Code, Zed, or another. Click **Connect** on its row. BrowserOS neo sets everything up for you.

Restart your AI tool once, and it now has a browser.

<Tip>
Using an AI tool that isn't listed? Copy the endpoint URL at the top of the page and paste it into your AI's own settings. See the [Connect page](/neo/mcp) for the manual setup.
</Tip>

```text
Find a good time next week for a 30-minute team meeting and send the invite.
```

Or something closer to your own work:

```text
Summarize my important unread emails from the last two days.
```

```text
Pull the numbers from the Q3 dashboard in Notion and put them in a summary at the top.
```

Whichever you pick, hit send.

<Frame caption="Every running AI and every finished session, at a glance.">
  
</Frame>

Two things to look at:

- **Running now**: the AI working on your task right now. You'll see the site it's on, how long it's been at it, and a live preview of what it's looking at.
- **Recent activity**: sessions that already finished. Click any tile to open the full story of what happened.

You don't have to sit and stare. Come back whenever you want; the dashboard shows you what's been going on.

<Frame caption="Replay any session like a video. Scrub through, see exactly what your AI saw at every moment.">
  
</Frame>

The replay plays back like a video. Hit rewind to see the exact moment things went off, or the exact moment something went well. On the right, every step your AI took is listed in order, and you can click any one to jump the replay to that moment.

Now you know what worked. Tell your AI, and it'll do the next task better.

Where to next Copy Chapter

Neo Install (`docs/neo/install.mdx`) Copy Section

title: "Install BrowserOS neo" keywords: ["install BrowserOS neo", "download BrowserOS neo", "BrowserOS neo macOS", "BrowserOS neo Windows"] Copy Chapter

BrowserOS neo is a full browser, so installing it works like installing Chrome or Firefox. Download it, drag it across or run the installer, and open it.

macOS Copy Chapter

The tap is needed because BrowserOS neo is not in Homebrew's own cask repository yet. Once it is, the same `brew install --cask browseros-neo` keeps working and the tap becomes optional.

Upgrade with `brew upgrade --cask browseros-neo`, though the browser also updates itself.

Windows Copy Chapter

Keeping it up to date Copy Chapter

BrowserOS neo updates itself. It checks for new versions in the background and installs them on the next restart, so there is nothing to do after the first install.

Next Copy Chapter

Neo Privacy (`docs/neo/privacy.mdx`) Copy Section

title: "Privacy and data" keywords: ["BrowserOS neo privacy", "AI browser privacy", "local-first browser", "no telemetry AI browser"] Copy Chapter

Everything BrowserOS neo records about your work stays on your computer. No cloud sync, no account, no server-side history of what your agents did. This page walks through exactly what stays local, what leaves as anonymous product events, and what your AI's own provider handles.

What stays on your machine Copy Chapter

Your history, cookies, logged-in sessions, downloads, and every recording of what your agents did live in BrowserOS neo's local browser profile on your disk. Sessions and screenshots the audit and replay pages show you all live under ~/.browserclaw/.

None of it uploads. There is no cloud sync, no server-side account, no shared history.

If you want to wipe any of it, delete the files.

What we never see Copy Chapter

The following never leaves your machine, not in any stream, not in any log:

• URLs your agents visit
• Page titles and page content
• Prompts you send your AI
• Tool arguments and tool results
• Screenshots
• File paths
• Passwords
• API keys
• Your email

Anonymous product events Copy Chapter

BrowserOS neo sends a small amount of anonymous usage data so we can see how the product is used and fix rough edges. It's on by default and off with one toggle in Settings.

Here's every field that goes out:

• Startup and shutdown
• Which AI tools connect and disconnect (the tool's name from a fixed list, plus session end times)
• BrowserOS neo version and your operating system

None of the fields in the "never leaves" list above are in this stream. There is no user identifier. There is no page content.

These events go to PostHog, a product analytics service. They're subject to PostHog's own privacy policy. If you'd rather send nothing at all, open Settings and switch the toggle off.

Your AI's own provider Copy Chapter

When your AI works in BrowserOS neo, the AI itself (Claude Code, Cursor, Codex, and so on) talks to its own vendor with your prompts. What that vendor does with the data is governed by their privacy policy, not ours. BrowserOS neo does not intermediate that leg.

The Claude Desktop extension Copy Chapter

The Claude Desktop extension (the .mcpb file you drop onto Settings) collects zero data. No analytics, no telemetry, no error reporting, no user identifiers.

The extension is a small forwarder: Claude Desktop asks it something, it hands the call to BrowserOS neo on your own machine, and passes the result back to Claude Desktop. It talks to no service on the internet on its own. Nothing kept, nothing sent.

Read the full policies Copy Chapter

Where to next Copy Chapter

Neo Tabs And Isolation (`docs/neo/tabs-and-isolation.mdx`) Copy Section

title: "Your tabs and agent tabs" keywords: ["BrowserOS neo tabs", "agent tabs", "personal tabs", "AI browser"] Copy Chapter

You use your browser for your own work. When an AI drives BrowserOS neo, it works in tabs of its own, right next to yours.

Two kinds of tabs, one browser Copy Chapter

• Your tabs. Pages you opened yourself.
• The AI's tabs. Pages your AI opened for the task you gave it.

Each AI's tabs land in their own colored tab group at the top of your tab strip, titled with the AI's name. Your tabs stay outside any group. One glance tells you what belongs to whom.

Your AI knows the difference Copy Chapter

BrowserOS neo tells your AI which tabs belong to you and which it opened itself. Your AI uses that to stay out of your workflow by default. It knows your tabs are there and can read their titles and URLs, so it has context, but it doesn't jump in.

If you want your AI to help with something you have open, reply to the email you're reading, extract the numbers from the doc on your screen, just ask. Your AI can work on the tab. That's your call.

When an AI's session ends Copy Chapter

Close an AI's session and its tab group closes with it. The tabs it opened go away in one step. Your tabs are never touched.

If you close one of an AI's tabs while it's still running, the AI notices right away. Nothing gets stuck.

Where to next Copy Chapter

Snippets Changelog (`docs/snippets/changelog.mdx`) Copy Section

All notable changes to BrowserOS are documented here. For the full release history with download links, see our GitHub Releases.

v0.46.0 Copy Chapter

_{June 17, 2026}

• Claude Code & Codex in your browser — The agent harness now bundles full coding agents. Claude Code and Codex plug straight into the assistant, so you can drive your browser with the agent — and the subscription — you already use.
• A brand new experience — A redesigned new tab, a calmer composer, and a rebuilt command center for switching between agents. The whole assistant is cleaner, faster to reach, and easier to live in.
• New MCP tools — A tighter, more reliable browser tool surface for agents, rebuilt from the ground up. Plus one-click install of BrowserOS as an MCP server into the agents you already run, with automatic URL sync.
• Chromium 148 — Updated to the latest Chromium base with all recent upstream fixes and security patches
• Streamlined — We've pulled back a few features that weren't getting much use — Skills, Soul, and Memory — so we can focus and ship better versions soon.

v0.44.0 Copy Chapter

_{March 20, 2026}

• ChatGPT Pro & GitHub Copilot — Already paying for ChatGPT Pro, Plus, or GitHub Copilot? Use that subscription to automate browser tasks in BrowserOS at no extra cost — just log in with your existing account.
• Voice input — Talk to your agent instead of typing. The chat bar now accepts voice input for any query.
• Smarter agent — Overhauled agent grounding for more reliable and precise browser actions.
• Bug fixes & reliability — Improved memory tools, fixed fill tool issues, new tab layout fixes, and numerous stability improvements across the board.

v0.43.0 Copy Chapter

_{March 12, 2026}

• Skills — Reusable instructions that teach your agent how to handle specific tasks. Ships with 12 built-in skills like deep research, price comparison, and form filling — and you can create your own.
• Memory — Your assistant now remembers you across conversations. Core memory stores permanent facts like your name and projects, while daily notes capture session context and auto-expire after 30 days. Everything stays local on your machine.
• Kimi K2.5 — In partnership with Moonshot AI, Kimi K2.5 is now the default model in BrowserOS — open-source, multimodal, and great for browser automation. Bring your own key from platform.moonshot.ai anytime.
• SOUL.md — Shape your assistant's personality, tone, and boundaries. It evolves on its own as you interact — the more you use it, the more it feels like yours.

v0.42.0 Copy Chapter

_{March 9, 2026}

• SOUL.md — Your assistant now has a soul. Tell it how you like to communicate, set boundaries, shape its personality — and it adapts on its own over time. The more you use it, the more it feels like your assistant.
• Vertical tabs — One of the most requested features is here. BrowserOS now ships with vertical tabs by default. More screen space, better tab management, and a cleaner layout out of the box. Prefer horizontal? You can switch back anytime in settings. Read more →
• Long-term memory — Your assistant finally remembers you. Your name, your projects, what you talked about last week — it carries context across every conversation so you never have to repeat yourself. All stored locally on your machine.
• Chromium 146 — Updated to the latest Chromium release with all recent upstream fixes and security patches

v0.41.0 Copy Chapter

_{March 4, 2026}

• New agent (v3) — Completely redone from scratch. 2x faster, 2–3x better performance
• Tools — major upgrade — Agent tools and MCP server both got a big overhaul. ~20 new tools (54 total) including file upload, save as PDF, background windows, and more. Connection with third-party coding agents (Claude Code, Codex, etc.) is much better now
• General fixes — Better agent installation, bug fixes, and smoother experience overall
• Linux Debian packaging — Fixed the remaining Debian packaging issues

v0.40.1 Copy Chapter

_{February 16, 2026}

• Chromium 145 — Upgraded to the latest Chromium base with all recent upstream fixes and security patches
• Login session import improvements — Importing login sessions is now more reliable
• Stability & reliability — General improvements across the board

v0.39.0 Copy Chapter

_{February 3, 2026}

• Sync — Save your browser configuration, agent history, and scheduled tasks across machines. Your setup now follows you wherever you go
• App Connector redesign — Connecting MCP apps is now easier. The new App Connector UI makes it simpler to discover, install, and manage your connected apps
• MCP port stability — Additional fixes for users still experiencing port issues. More reliable connections across restarts
• Keyboard shortcuts — Updated shortcuts to avoid conflicts with European keyboards

v0.38.0 Copy Chapter

_{January 28, 2026}

Bug fix and stability release.

• MCP port fix on Windows & Linux — Fixed an issue with MCP port. Port now stays consistent across restarts and made it more reliable
• Settings fix — Fixed chrome.browser.settings not working correctly. Settings should now persist and apply as expected
• Improved agent — Made the agent more reliable and performant. General stability fixes across the agent loop

v0.37.0 Copy Chapter

_{January 21, 2026}

• Workflows — Build reliable, repeatable browser automations with a visual graph builder. Chat with the workflow agent to define step-by-step automation—ideal for complex tasks where ad-hoc prompts aren't enough.

• Cowork — Describe an outcome, step away, and come back to finished work. Combine browser automation with local file operations—research on the web and save reports, scrape data and export to files, all in one task. Read more →

v0.36.3 Copy Chapter

_{January 15, 2026}

• Agent history — Agent conversations are now saved automatically. View and resume them anytime from the Assistant panel

v0.36.2 Copy Chapter

_{January 10, 2026}

Bug fix release focused on MCP stability.

• MCP server disconnect fix — Fixed port handling issue causing MCP connections to drop unexpectedly

v0.36.0 Copy Chapter

_{January 8, 2026}

• Agent personalization — Add your own prompts to personalize the agent. Tweak its behavior, adjust how it responds, set your preferred formatting, and more
• Toolbar customization — Hide the Hub chat and labels from the settings page to declutter your toolbar
• MCP server port stability — The port now stays consistent through browser restarts, so you don't have to keep updating your MCP clients
• Fixed agent install/update issues — The agent now handles installs and updates more proactively

v0.35.0 Copy Chapter

_{December 25, 2025}

• Agent stability fixes — Fixed bugs to make the agent loop much more reliable
• Gemini 3 support — Gemini 3 now supported through OpenRouter and Google adapters
• Better error surfacing — Error messages are now clearer

v0.34.0 Copy Chapter

_{December 20, 2025}

• Third-party MCP server support — Connect external MCP servers like Google Calendar, Notion, Google Docs, Gmail, and more. You can also connect your own custom MCP servers
• Gemini 3 support — Gemini 3 Pro and Flash models now work with BrowserOS
• Windows icon fix — The Windows icon now displays BrowserOS logo correctly
• Agent & UI improvements — Various agent loop fixes and UI polish

v0.33.0 Copy Chapter

_{December 18, 2025}

• OpenAI-compatible provider support — Connect any OpenAI-compatible API endpoint
• Multi-window & multi-profile agent support — Agent now works across multiple windows and browser profiles
• MCP server reliability — Fixed connection drops and improved stability
• Agent reliability improvements — General stability fixes

v0.32.0 Copy Chapter

_{December 12, 2025}

A complete revamp of BrowserOS.

New features:

• New Agent — Completely rebuilt agent: faster, smarter, and more reliable
• Agent Per Tab — Run multiple agents in different tabs simultaneously
• Polished UI — Fresh, cleaner interface design
• Manifest V2 Support — Ad blockers like uBlock Origin work again
• Native Split View — Work on two things side by side
• Chromium 142 — Updated to Chromium 142.0.7444.49
• Azure & AWS Bedrock — Native support for Azure OpenAI and AWS Bedrock models

Breaking changes:

• Old agent will stop working — update required
• LLM provider settings won't carry over — reconfiguration needed

v0.30.0 Copy Chapter

_{November 14, 2025}

• Better text extraction — Improved copy button in LLM Chat
• MCP server stability — Improved connection reliability
• UI cleanup — Unpinned extensions for cleaner look
• Third-party MCP fixes — Fixed support for third-party MCP servers

Snippets Contributing (`docs/snippets/contributing.mdx`) Copy Section

BrowserOS has two main parts you can contribute to:

• Agent — The AI features, UI, and browser automation (TypeScript/React)
• Browser — The custom Chromium build (C++/Python)

Most contributors work on the Agent since it's much easier to set up.

Quick Links Copy Chapter

• GitHub Repository
• Discord Community
• Report Issues

Ways to Contribute Copy Chapter

Report bugs — Open an issue with steps to reproduce, expected vs actual behavior, and screenshots.

Suggest features — Share ideas on GitHub or Discord.

Improve docs — Docs live in docs/ and use Mintlify. Edit pages and update docs/docs.json for navigation.

Path 1: Agent Development Copy Chapter

The Agent is a monorepo with 3 components:

Architecture Copy Section

Setup Copy Section

# Clone the repo
git clone https://github.com/YOUR-USERNAME/BrowserOS.git
cd BrowserOS/packages/browseros-agent

# Install dependencies
bun install

# Copy environment files
cp apps/server/.env.example apps/server/.env.development
cp apps/app/.env.example apps/app/.env.development

Running Locally Copy Section

# Terminal 1: Start the server
bun run start:server

# Terminal 2: Start the agent extension (dev mode)
bun run start:agent

Then load the extension in BrowserOS:

1. Go to chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked and select the apps/app/dist/ folder

Commands Copy Section

Path 2: Browser Development Copy Chapter

Only go down this path if you're working on Chromium-level features like patches to the browser itself.

Requirements:

• ~100GB disk space
• 16GB+ RAM recommended
• 3+ hours for first build

Prerequisites Copy Section

Build Instructions Copy Section

1. Clone Chromium source

Follow the official Chromium: Get the Code guide. This sets up depot_tools and fetches ~100GB of source code.

Note the path where you clone it (e.g., ~/chromium/src).

2. Install UV and dependencies

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Navigate to build system
cd packages/browseros

# Install dependencies
uv sync

3. Build debug version

uv run browseros build \
  --chromium-src <your-chromium-src-path> \
  --setup \
  --prep \
  --build \
  --build-type debug

The --setup and --prep flags are only needed for the first build. After that, just use --build for incremental builds:

uv run browseros build --chromium-src <path> --build --build-type debug

4. Run BrowserOS

Build Flags Copy Section

Troubleshooting Copy Section

Build fails with missing dependencies — Make sure you followed all steps from the Chromium build guide for your platform.

Out of disk space — Chromium needs ~100GB. Check with df -h.

Build takes too long — Use ccache, more CPU cores, or stick to debug builds.

UV command not found — Restart your terminal after installing UV.

Making Your First PR Copy Chapter

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a branch: git checkout -b feature/your-feature
4. Make changes and test them
5. Commit: git commit -m "feat: add your feature"
6. Push: git push origin feature/your-feature
7. Open a PR with a clear description

Sign the CLA Copy Section

On your first PR, our bot will ask you to sign the Contributor License Agreement. Just comment:

I have read the CLA Document and I hereby sign the CLA

Code Standards Copy Chapter

TypeScript:

• Use strict typing, avoid any
• Use Zod schemas instead of TypeScript interfaces
• Use path aliases (@/lib) not relative paths (../)
• Naming: PascalCase for classes, camelCase for functions

React:

• Tailwind CSS only (no SCSS or CSS modules)
• Hooks at top level only
• Test with Vitest

General:

• Keep functions short (under 20 lines)
• Write tests for new features
• Handle errors gracefully

Getting Help Copy Chapter

• Discord — discord.gg/YKwjt5vuKr
• GitHub Issues — github.com/BrowserOS-ai/BrowserOS/issues
• GitHub Discussions — github.com/BrowserOS-ai/BrowserOS/discussions

By contributing, you agree that your contributions will be licensed under AGPL-3.0.

Browseros Comparisons Chrome Devtools Mcp (`docs/browseros/comparisons/chrome-devtools-mcp.mdx`) Copy Section

title: "Chrome DevTools MCP" Copy Chapter

Both BrowserOS MCP and Chrome DevTools MCP give AI agents control over a browser via the Model Context Protocol. But they're built for different scopes. Chrome DevTools MCP focuses on debugging and inspection, while BrowserOS MCP is a complete browser automation and app integration platform.

This page breaks down the differences for developers evaluating which to use with Claude Code, Gemini CLI, Cursor, or any MCP client.

At a Glance Copy Chapter

Feature Comparison Copy Chapter

Navigation & Tab Management Copy Section

Content & Observation Copy Section

Interaction & Input Copy Section

File & Export Copy Section

Window Management Copy Section

Tab Groups Copy Section

Bookmarks Copy Section

History Copy Section

Debugging & Performance Copy Section

External App Integrations Copy Section

Setup Comparison Copy Chapter

```bash
# One command, done
claude mcp add --transport http browseros http://127.0.0.1:9239/mcp --scope user
```

The server URL is available at `chrome://browseros/mcp`. Copy it and connect.

```bash
# Step 1: Launch Chrome with debug port
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Step 2: Install and run the MCP server
npx @anthropic-ai/chrome-devtools-mcp@latest

# Step 3: Connect your MCP client to the server
```

Some sites may block sign-in when the browser is controlled via WebDriver (the default launch mechanism).

Summary Copy Chapter

BrowserOS MCP gives you a broader automation surface: browser control, content extraction, file operations, and 40+ app integrations through a single connection. Debugging and performance tools are coming soon to BrowserOS MCP, which will close the remaining gap with Chrome DevTools MCP. For most AI agent workflows, BrowserOS MCP already covers more ground out of the box.

Browseros Comparisons Claude Cowork (`docs/browseros/comparisons/claude-cowork.mdx`) Copy Section

title: "Claude Cowork" Copy Chapter

Both BrowserOS Cowork and Claude Cowork let an AI agent work with your local files autonomously. You describe a task, step away, and come back to completed work. They share a similar file toolkit under the hood. The key difference is what else each product can do. BrowserOS Cowork runs inside a real browser with full web access and 40+ app integrations. Claude Cowork runs inside an isolated VM with professional document generation.

This page compares both products so you can decide which fits your workflow.

At a Glance Copy Chapter

Feature Comparison Copy Chapter

File Operations Copy Section

Both products provide a comparable set of file tools. You can read, write, edit, search, and organize files in both. This is table-stakes for both products.

Working with the Web Copy Section

This is the biggest difference. BrowserOS Cowork runs inside a real browser with your existing logins and sessions.

Claude Cowork has no browser access. If your task involves anything on the web, whether that's researching, filling out forms, grabbing content from a site, or checking on a web app, you need BrowserOS.

Connected Apps Copy Section

BrowserOS connects to 40+ services directly. Claude Cowork has a handful of connectors.

Document Generation Copy Section

Claude Cowork has an edge when it comes to creating polished office documents.

How They Work Copy Chapter

- Works in your real browser with your existing logins
- File access sandboxed to the folder you select
- 40+ app integrations via OAuth
- Connect from any AI tool (Claude Code, Gemini CLI, Cursor, etc.)
- Uses whatever AI model you choose

- Runs in a secure VM, isolated from your main system
- File access to folders you grant permission to
- ~4 connectors (Google Drive, Gmail, DocuSign, FactSet)
- Only works in the Claude Desktop app
- Uses Claude models only
- Comes pre-loaded with Python, Node.js, Ruby, and common tools

Where Claude Cowork Shines Copy Chapter

• Professional documents: Create Excel spreadsheets with working formulas, PowerPoint presentations, and formatted Word documents
• Parallel subtasks: Automatically breaks complex work into smaller tasks that run at the same time
• Stronger isolation: Runs in a full virtual machine, giving you OS-level separation from your main system
• Zero setup: Works out of the box in the Claude Desktop app with pre-installed tools and languages

Where BrowserOS Cowork Shines Copy Chapter

• Full browser access: Navigate websites, fill forms, click buttons, take screenshots, and extract content from any page. Claude Cowork cannot touch the web.
• Your real logins: Because it runs in your actual browser, the agent can access sites where you're already logged in: dashboards, internal tools, social media, banking portals, anything.
• 40+ app integrations: Gmail, Slack, GitHub, Calendar, Notion, Linear, Figma, Salesforce, and more. All accessible in the same session as your file work. Claude Cowork has about 4 connectors.
• Pick your AI model: Use Claude, GPT-5, Gemini, Kimi K2.5, or a local model. Claude Cowork only works with Claude.
• Full internet access: Your agent can visit any website. Claude Cowork's VM is restricted to a short list of allowed sites.
• Free: BrowserOS is free. Just bring your own AI API key. Claude Cowork requires a paid Claude subscription.

Summary Copy Chapter

Both products handle file operations equally well. The choice comes down to what else you need. If your work touches the web, connected apps, or you want to choose your own AI model, BrowserOS Cowork gives you that. If you need polished office documents and prefer a fully isolated desktop experience, Claude Cowork is a good fit.

Browseros Comparisons Openclaw (`docs/browseros/comparisons/openclaw.mdx`) Copy Section

title: "OpenClaw" Copy Chapter

OpenClaw is an open-source personal AI assistant that runs on your machine and connects through messaging apps like WhatsApp, Telegram, Slack, and Discord. It is a powerful tool for technical users who want a self-hosted, always-on AI agent.

BrowserOS takes a different approach. Instead of running a background server that you message through chat apps, BrowserOS puts the AI assistant directly inside your browser, where most of your work already happens. No terminal setup, no daemon management, no Node.js required.

This comparison is for users deciding which tool fits their needs.

At a Glance Copy Chapter

Where BrowserOS Shines Copy Chapter

No technical setup required Copy Section

OpenClaw requires Node.js 22+, npm installation, a terminal-based onboarding wizard, daemon configuration (launchd or systemd), and channel pairing for each messaging platform. If something goes wrong, you need openclaw doctor to diagnose issues.

BrowserOS is a browser. Download it, open it, and start talking to the assistant. There is no daemon to manage, no services to keep running, and no terminal needed.

Browser automation built in Copy Section

BrowserOS gives the assistant full control of your browser with 53 tools: clicking buttons, filling forms, navigating between pages, taking screenshots, managing tabs, organizing bookmarks, searching history, and more. The assistant sees what you see and can interact with any website you are logged into.

OpenClaw has browser automation through a dedicated Chrome instance with CDP, but it runs as a separate process rather than being integrated into the browser you are already using. With BrowserOS, the assistant works directly in your browsing session with all your cookies, logins, and open tabs.

40+ app integrations built in Copy Section

BrowserOS connects to Gmail, Google Calendar, Slack, Notion, GitHub, Linear, Jira, Figma, Salesforce, Stripe, and 30+ more services out of the box. Most services connect through OAuth (one-click sign-in), while some require an API key. Either way, the assistant detects when an app is not connected and walks you through the setup right in the conversation.

OpenClaw uses a skills system where integrations are community-built plugins. Some popular services have skills available, but connecting a new service often means finding the right skill, installing it, and configuring credentials manually.

Works where you already are Copy Section

Most of your work happens in a browser. BrowserOS puts the assistant right there, so it can see the page you are on, interact with web apps, and pull data from your open tabs. There is no context-switching between a chat app and your browser.

OpenClaw's approach of messaging through WhatsApp or Telegram is clever for mobile use, but when you are at your computer working in a browser, having the assistant inside that browser is more natural and more capable.

Where OpenClaw Shines Copy Chapter

Messaging app access Copy Section

OpenClaw connects to 20+ messaging platforms including WhatsApp, Telegram, Signal, iMessage, Discord, Slack, Microsoft Teams, and more. You can message your assistant from your phone or any chat app without opening a specific application. This is ideal if you want AI help on the go through apps you already have open.

BrowserOS is a desktop browser. To use the assistant, you need to be in BrowserOS.

Always-on background agent Copy Section

OpenClaw runs as a daemon on your machine, processing tasks even when you are not actively chatting. It supports cron jobs, webhooks, and Gmail Pub/Sub for automated triggers. It can wake up, do something, and report back through your messaging app.

BrowserOS has scheduled tasks that run automations on a schedule, but the browser needs to be running. OpenClaw's daemon approach is more suited for server-like always-on operation.

Mobile companion apps Copy Section

OpenClaw offers iOS and Android companion apps with camera access, voice input, screen recording, and device-level actions (notifications, contacts, calendar, SMS). This extends the assistant to your phone in a way that BrowserOS cannot currently match.

Agent-to-agent communication Copy Section

OpenClaw supports multi-session agent coordination where agents can discover each other, read transcripts, and send messages between sessions. This is useful for complex workflows where multiple specialized agents collaborate.

Self-modifying skills Copy Section

OpenClaw agents can write and install their own skills during a conversation. If the assistant does not have a capability, it can create one on the fly. This makes it extremely flexible for power users who want the agent to extend itself.

Feature Comparison Copy Chapter

App Integrations Copy Section

Setup and Maintenance Copy Section

Who Should Use What Copy Chapter

Using Both Together Copy Chapter

BrowserOS and OpenClaw are not mutually exclusive. Some users run OpenClaw as their always-on mobile assistant (accessible through WhatsApp or Telegram) while using BrowserOS as their desktop browser for work that involves web apps, browser automation, and visual tasks. The two tools complement each other rather than compete directly.

Browseros Features Ad Blocking (`docs/browseros/features/ad-blocking.mdx`) Copy Section

title: "Ad Blocking" Copy Chapter

BrowserOS supports full ad blocking through uBlock Origin, the most powerful open-source ad blocker available — the full extension, not the watered-down "Lite" version.

Why BrowserOS? Copy Chapter

Chrome killed support for uBlock Origin by phasing out Manifest V2 extensions. The only option left on Chrome is "uBlock Origin Lite," a significantly weaker version that can't use advanced filtering rules.

BrowserOS re-enabled full Manifest V2 support, so you can install and run the original uBlock Origin at full power — the same extension Chrome no longer allows.

BrowserOS vs Chrome Copy Chapter

We ran both browsers through adblock.turtlecute.org, a test that measures how effectively a browser blocks ads and tracking scripts.

Out of 133 ad-related requests:

• BrowserOS blocked 91 (68%)
• Chrome blocked 9 (7%)

That's roughly 10x more protection with zero configuration.

What This Means Copy Chapter

Fewer ads means faster page loads, less bandwidth usage, and significantly reduced tracking. BrowserOS handles this natively so you can focus on browsing.

Browseros Features Bring Your Own Llm (`docs/browseros/features/bring-your-own-llm.mdx`) Copy Section

title: "Bring Your Own LLM" Copy Chapter

BrowserOS includes a default AI model you can use right away, but it has strict rate limits. For the best experience, bring your own API keys or run models locally.

See how to connect your own LLM in under a minute:

<video
controls
className="w-full aspect-video rounded-xl"
src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/1-bring-your-own-LLM.mov"

Use Your Existing Subscription Copy Chapter

Already paying for ChatGPT Pro or GitHub Copilot? Connect your existing account to BrowserOS with a single sign-in — no API keys, no extra cost.

Sign in with your OpenAI account. Access GPT-5 Codex, GPT-5.4, and the full Codex lineup with up to 400K context.

Sign in with your GitHub account. Access 19+ models including Claude, GPT-5, and Gemini through one subscription.

Which Model Should I Use? Copy Chapter

Kimi K2.5 — In Partnership with Moonshot AI Copy Chapter

{/* */}

BrowserOS has partnered with Moonshot AI to bring Kimi K2.5 as a first-class provider. Kimi K2.5 is now the recommended model in BrowserOS and is set as the default provider.

For a limited time, BrowserOS users get extended usage limits powered by Kimi K2.5. This means you can use the AI agent, chat, and other AI-powered features with increased limits at no cost.

Why Kimi K2.5? Copy Section

Kimi K2.5 offers excellent performance for agentic tasks at a fraction of the cost of other frontier models. It supports images, has a 128,000 token context window, and delivers strong results on browser automation tasks. Combined with BrowserOS's open-source agent framework, this makes for a powerful and affordable AI browsing experience.

Bring Your Own Kimi API Key Copy Section

You can also bring your own Kimi API key if you want to use Kimi K2.5 beyond the extended usage period, or if you want your own dedicated limits.

Get your API key:

1. Go to platform.moonshot.ai and create an account
2. Navigate to the API keys section in your dashboard
3. Click Create new API key and copy the key

Add to BrowserOS:

1. Go to chrome://browseros/settings
2. Click USE on the Moonshot AI card
3. Enter your API key (it will be encrypted and stored locally on your machine)
4. The model is pre-configured to kimi-k2.5 with a 128,000 context window
5. Click Save

Cloud Providers Copy Chapter

Connect to powerful AI models using your API keys. Your keys stay on your machine — requests go directly to the provider.

**Get your API key:**
1. Go to [aistudio.google.com](https://aistudio.google.com)
2. Click **Get API key** in the sidebar
3. Click **Create API key** and copy it



**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the Gemini card
3. Set **Model ID** to `gemini-2.5-flash` (or `gemini-2.5-pro`, `gemini-3-pro-preview`, `gemini-3-flash-preview`)
4. Paste your API key
5. Check **Supports Images**, set **Context Window** to `1000000`
6. Click **Save**

**Get your API key:**
1. Go to [console.anthropic.com](https://console.anthropic.com/dashboard)
2. Click **API keys** in the sidebar
3. Click **Create Key** and copy it



**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the Anthropic card
3. Set **Model ID** to `claude-opus-4-5-20251101` (or `claude-sonnet-4-5-20250929`, `claude-haiku-4-5-20251001`)
4. Paste your API key
5. Check **Supports Images**, set **Context Window** to `200000`
6. Click **Save**

**Get your API key:**
1. Go to [platform.openai.com](https://platform.openai.com)
2. Click settings icon → **API keys**
3. Click **Create new secret key** and copy it



**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the OpenAI card
3. Set **Model ID** to `gpt-5` (or `gpt-5.2`, `gpt-5-mini`, `gpt-4.1`, `o4-mini`)
4. Paste your API key
5. Check **Supports Images**, set **Context Window** to `200000`
6. Click **Save**

**Get your API key:**
1. Go to [openrouter.ai](https://openrouter.ai) and sign up
2. Go to [openrouter.ai/keys](https://openrouter.ai/keys) and create a key

**Pick a model:**
Go to [openrouter.ai/models](https://openrouter.ai/models) and copy the model ID you want (e.g., `anthropic/claude-opus-4.5`, `google/gemini-2.5-flash`).



**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the OpenRouter card
3. Paste the model ID and your API key
4. Set **Context Window** based on the model
5. Click **Save**

**Prerequisites:**
1. An Azure subscription with access to [Azure OpenAI Service](https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/OpenAI)
2. A deployed model (e.g., GPT-4o) in your Azure OpenAI resource

**Get your credentials:**
1. Go to [portal.azure.com](https://portal.azure.com) → **Azure OpenAI** resource
2. Navigate to **Keys and Endpoint**
3. Copy **Key 1** and your **Endpoint URL**

**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the Azure card
3. Set **Base URL** to your Azure endpoint (e.g., `https://your-resource.openai.azure.com/openai/deployments/your-deployment`)
4. Set **Model ID** to your deployment name
5. Paste your API key
6. Check **Supports Images**, set **Context Window** to `128000`
7. Click **Save**

**Prerequisites:**
1. An AWS account with [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html) enabled
2. Model access granted in the Bedrock console for your desired models

**Get your credentials:**
1. Go to the [AWS Console](https://console.aws.amazon.com) → **IAM**
2. Create or use an existing access key with Bedrock permissions
3. Note your **Access Key ID**, **Secret Access Key**, and **Region**

**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the AWS Bedrock card
3. Set **Base URL** to your Bedrock endpoint (region-specific)
4. Set **Model ID** to the Bedrock model ID (e.g., `anthropic.claude-3-sonnet-20240229-v1:0`)
5. Paste your credentials
6. Check **Supports Images**, set **Context Window** to `200000`
7. Click **Save**

**Add to BrowserOS:**
1. Go to `chrome://browseros/settings`
2. Click **USE** on the OpenAI Compatible card
3. Set **Base URL** to the provider's API endpoint
4. Set **Model ID** to the model you want to use
5. Paste your API key
6. Set **Supports Images** and **Context Window** based on the model
7. Click **Save**

<Tip>
Most newer AI providers support the OpenAI-compatible API format. Check your provider's docs for the base URL and available model IDs.
</Tip>

Local Models Copy Chapter

Switching Between Models Copy Chapter

Use the model switcher in the Assistant panel to change providers anytime. The default provider is highlighted.

Browseros Features Chatgpt Pro Oauth (`docs/browseros/features/chatgpt-pro-oauth.mdx`) Copy Section

title: "ChatGPT Pro / Plus" Copy Chapter

Connect your ChatGPT Pro or Plus subscription to BrowserOS and access GPT-5.5, GPT-5 Codex, GPT-5.4, and the full lineup of OpenAI's most advanced models — with up to 1.05M context. No API keys needed.

Setup Copy Chapter

1. Open BrowserOS and go to Settings (chrome://browseros/settings). You'll see the AI Providers section.

2. Click USE on the ChatGPT Plus/Pro card. You'll be prompted to sign in with your OpenAI account.

3. Sign in with the OpenAI account that has your ChatGPT Pro or Plus subscription active, and accept the authorization.

4. Once authorized, ChatGPT will appear as a provider in your settings. Select a model and start using it.

Available Models Copy Chapter

ChatGPT Pro subscribers have access to the full model lineup. ChatGPT Plus subscribers can access a subset of models depending on their plan. The available models will be shown automatically after you connect.

Reasoning Settings Copy Chapter

ChatGPT Pro includes additional settings for models that support reasoning:

• Reasoning Effort — Control how much the model "thinks" before responding. Options: none, low, medium, high.
• Reasoning Summary — Choose how reasoning is displayed. Options: auto, concise, detailed.

These settings are available in the provider configuration after connecting.

Disconnecting Copy Chapter

To disconnect your OpenAI account, go to Settings, find the ChatGPT Plus/Pro provider, and click Disconnect. Your OAuth tokens will be immediately deleted from your machine.

Browseros Features Connect Mcps (`docs/browseros/features/connect-mcps.mdx`) Copy Section

title: "Connect Apps" Copy Chapter

Connect your favorite apps to BrowserOS and let the assistant work across all of them. Read emails, check your calendar, create tasks, post messages, manage files, and more, all through natural conversation.

<video
controls
className="w-full aspect-video rounded-xl"
src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/4-MCP.mp4"

How It Works Copy Chapter

BrowserOS uses the Model Context Protocol (MCP) to connect your apps. You do not need to install anything or manage API keys. Just sign in once and the assistant handles the rest.

Smart App Connection Copy Chapter

When you ask the assistant to do something that needs an app you have not connected yet, it shows an interactive card right in the conversation. You can connect the app with one click or choose to skip it. No need to set things up in advance.

{/*

See Smart Nudges for more details on how connection suggestions work.

You can also connect apps ahead of time from the sidebar if you prefer.

Connect from the Sidebar Copy Chapter

40+ Supported Apps Copy Chapter

BrowserOS connects to over 40 apps across every category you need.

Example Prompts Copy Chapter

The assistant figures out which apps to use based on what you ask. Just describe what you want in plain language.

Cross-App Workflows Copy Chapter

The real power of connected apps is combining them in a single request. The assistant can pull data from one app and use it in another without you switching between tabs.

Add a Custom MCP Server Copy Chapter

You can connect any MCP-compatible server that exposes an SSE endpoint.

1. Go to Settings > Connected Apps
2. Click Add custom app
3. Enter your server URL (e.g., http://localhost:8000/sse) and give it a name

Custom servers appear alongside built-in apps and work the same way.

Connect to OAuth-Protected Remote Servers Copy Section

Some remote MCP servers (like Atlassian Jira, GitHub, etc.) require OAuth authentication. Use mcp-remote and supergateway to handle the OAuth flow locally:

npx -y supergateway --stdio "npx -y mcp-remote https://mcp.atlassian.com/v1/sse" --port 8000

A browser window will open to sign in. Once authenticated, add http://localhost:8000/sse as a custom MCP in BrowserOS.

Privacy and Security Copy Chapter

Browseros Features Cowork (`docs/browseros/features/cowork.mdx`) Copy Section

title: "Cowork" Copy Chapter

Cowork lets you describe complex tasks and let the agent handle them end-to-end. It combines browser automation with local file operations: research on the web, then save reports directly to your folder. Read code, edit files, run shell commands, and search through your project, all in the same session as your browser tasks.

Here's what it looks like to give the agent access to your local files:

<video
controls
className="w-full aspect-video rounded-xl"
src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/3-filesystem-access.mp4"

Why Cowork? Copy Chapter

Without Cowork, the agent can only interact with browser tabs. With Cowork enabled, it gains full access to a folder on your machine through 7 filesystem tools:

The real power: do both browser automation AND file operations in a single task. Describe what you want, step away, and come back to finished work.

Setting Up Cowork Copy Chapter

The agent is sandboxed to your selected folder. It cannot access files outside of it.

Filesystem Tools Copy Chapter

Cowork provides 7 filesystem tools that the agent can use alongside browser automation:

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | string (required) | File path relative to working directory |
| `offset` | number (optional) | Starting line number (1-indexed) |
| `limit` | number (optional) | Max lines to read |

Responses are capped at 2000 lines or 50KB per request.

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | string (required) | File path relative to working directory |
| `content` | string (required) | Complete file content to write |

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | string (required) | File path relative to working directory |
| `old_string` | string (required) | Exact text to find |
| `new_string` | string (required) | Replacement text |

Returns a side-by-side diff of the change.

| Parameter | Type | Description |
|-----------|------|-------------|
| `command` | string (required) | Shell command to execute |
| `timeout` | number (optional) | Timeout in seconds (default: 120) |

Output is truncated to the last 2000 lines if too large. Returns the exit code on failure.

| Parameter | Type | Description |
|-----------|------|-------------|
| `pattern` | string (required) | Glob pattern (e.g., `*.ts`, `**/*.json`) |
| `path` | string (optional) | Directory to search (default: working directory) |
| `limit` | number (optional) | Max results (default: 1000) |

Returns relative file paths sorted alphabetically.

| Parameter | Type | Description |
|-----------|------|-------------|
| `pattern` | string (required) | Search pattern (regex by default) |
| `path` | string (optional) | Directory or file to search |
| `glob` | string (optional) | Filter files by glob (e.g., `*.ts`) |
| `ignore_case` | boolean (optional) | Case-insensitive search |
| `literal` | boolean (optional) | Treat pattern as literal string |
| `context` | number (optional) | Lines of context around matches |
| `limit` | number (optional) | Max matches (default: 100) |

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | string (optional) | Directory path (default: working directory) |
| `limit` | number (optional) | Max entries (default: 500) |

Entries are sorted alphabetically, case-insensitive.

Try It: Research and Create a Report Copy Chapter

With Cowork enabled, try this prompt:

Read the top 3 stories on Hacker News, read the comments too, and write an HTML report.

The agent will:

Example Use Cases Copy Chapter

Security Copy Chapter

Browseros Features Github Copilot Oauth (`docs/browseros/features/github-copilot-oauth.mdx`) Copy Section

title: "GitHub Copilot" Copy Chapter

Connect your GitHub Copilot subscription to BrowserOS and access 19+ models — including Claude, GPT-5, and Gemini — through a single GitHub sign-in. No API keys needed.

Free tier includes GPT-5 Mini, Claude Haiku 4.5, GPT-4o, and GPT-4.1. Copilot Pro ($10/month) unlocks Claude Sonnet 4.6, Claude Opus 4.6, Gemini 3 Pro, GPT-5.4, and more.

Setup Copy Chapter

1. Open BrowserOS and go to Settings (chrome://browseros/settings). You'll see the AI Providers section.

2. Click USE on the GitHub Copilot card. A device code will appear — copy it, then click the link to open GitHub's device authorization page.

3. Select your GitHub account to authorize.

4. Paste the device code and authorize BrowserOS to access your Copilot subscription.

5. Once authorized, GitHub Copilot will appear as a provider in your settings. Select a model and start using it.

Available Models Copy Chapter

Free Tier Copy Section

Copilot Pro / Pro+ Copy Section

Disconnecting Copy Chapter

To disconnect your GitHub account, go to Settings, find the GitHub Copilot provider, and click Disconnect. Your OAuth tokens will be immediately deleted from your machine.

Browseros Features Local Models (`docs/browseros/features/local-models.mdx`) Copy Section

title: "Bring Your Local Model" Copy Chapter

BrowserOS works great with local models for Chat Mode. Run models completely offline — your data never leaves your machine.

Context Length Copy Chapter

Set context length when starting Ollama:

OLLAMA_CONTEXT_LENGTH=20000 ollama serve

Increasing context length uses more VRAM. Run ollama ps to check your current allocation. See the Ollama context length docs for more details.

Setup Copy Chapter

<Steps>
  <Step title="Install Ollama">
    Download from [ollama.com](https://ollama.com) and install it.
  </Step>
  <Step title="Pull a model">
    ```bash
    ollama pull qwen/qwen3-4b
    ```
  </Step>
  <Step title="Start Ollama with higher context">
    ```bash
    OLLAMA_CONTEXT_LENGTH=20000 ollama serve
    ```
  </Step>
  <Step title="Configure in BrowserOS">
    1. Go to `chrome://browseros/settings`
    2. Click **USE** on the Ollama card
    3. Set **Model ID** to `qwen/qwen3-4b`
    4. Set **Context Window** to `20000`
    5. Click **Save**

    
  </Step>
</Steps>

<Steps>
  <Step title="Install LM Studio">
    Download from [lmstudio.ai](https://lmstudio.ai) and install it.
  </Step>
  <Step title="Load a model">
    Open LM Studio → **Developer** tab → load a model. It runs a server at `http://localhost:1234/v1/`.

    
  </Step>
  <Step title="Configure in BrowserOS">
    1. Go to `chrome://browseros/settings`
    2. Click **USE** on the **OpenAI Compatible** card
    3. Set **Base URL** to `http://localhost:1234/v1/`
    4. Set **Model ID** to the model you loaded
    5. Set **Context Window** to at least `20000`
    6. Click **Save**

    
  </Step>
</Steps>

Recommended Models Copy Chapter

Pick a model based on your available RAM/VRAM. Smaller models are faster but less capable.

Lightweight (under 5 GB) Copy Section

Good for machines with 8 GB RAM. Fast responses, suitable for simple chat tasks.

Mid-range (10–15 GB) Copy Section

Needs 16+ GB RAM. Better reasoning, handles longer conversations well.

Heavy (60+ GB) Copy Section

For workstations with 64+ GB RAM. Closest to cloud model quality.

Browseros Features Scheduled Tasks (`docs/browseros/features/scheduled-tasks.mdx`) Copy Section

title: "Scheduled Tasks" Copy Chapter

Scheduled Tasks let you run the BrowserOS agent automatically, whether it is daily, every few hours, or every few minutes. Write a prompt once, set a schedule, and let the agent handle it on autopilot.

Watch how to set up a scheduled task from scratch:

<video
controls
className="w-full aspect-video rounded-xl"
src="https://pub-80f8a01e6e8b4239ae53a7652ef85877.r2.dev/resources/feature-videos/5-scheduled-tasks.mp4"

Creating a Scheduled Task Copy Chapter

There are two ways to create a scheduled task: from a conversation or from the settings page.

From a conversation Copy Section

After the agent completes a task that could run on a schedule, it will suggest scheduling it with an interactive card. You can also ask directly:

• "Schedule this to run every morning"
• "Can this run daily at 8am?"
• "Automate this task"

The agent fills in the task details for you. Just review and confirm. See Smart Nudges for more details.

From settings Copy Section

Schedule Types Copy Chapter

Example Use Cases Copy Chapter

Your scheduled task prompts can be as complex as you want. If you have connected apps like Google Calendar, Slack, Notion, or Gmail, your scheduled tasks can work across all of them.

Viewing Results Copy Chapter

When a scheduled task runs, you can see the results in two places:

• New Tab page: Results show up right on your new tab
• Scheduled Tasks page: View the full run history for each task

Each task keeps a history of its last 15 runs. Click on any run to see the full output, including what tools the agent used and what it found.

You can also:

• Test a task manually without waiting for the next scheduled run
• Retry a failed task
• Cancel a task that is currently running

How It Works Copy Chapter

Cloud Sync Copy Chapter

If you are signed in, your scheduled task configurations sync across devices. Create a task on your laptop and it appears on your desktop. Edits sync both ways, and conflicts are resolved automatically using timestamps.

Only the schedule setup syncs (name, prompt, schedule type, and timing). Task run results and output stay on the device where the task ran.

See Sync to Cloud for more details.

Privacy Copy Chapter

Browseros Features Smart Nudges (`docs/browseros/features/smart-nudges.mdx`) Copy Section

title: "Smart Nudges" Copy Chapter

Smart Nudges are context-aware suggestions that appear as interactive cards during a conversation. The agent detects opportunities to connect an app or schedule a task, and shows you a card at the right moment. You decide whether to act on it or skip it.

There are two types of nudges: App Connection and Schedule Suggestion.

App Connection Copy Chapter

When you ask the agent to do something that involves an external app (like sending an email or checking your calendar), it checks whether that app is connected. If it is not, the agent shows a connection card before starting the task.

What happens after you choose Copy Section

Supported apps Copy Section

The agent can suggest connections for all 40+ built-in integrations, including Gmail, Google Calendar, Slack, Notion, GitHub, Linear, Jira, Figma, Salesforce, and many more. See Connect Apps for the full list.

Schedule Suggestion Copy Chapter

After the agent completes a task that could run on a recurring schedule, it shows a scheduling card. This helps you turn one-time tasks into automated routines without leaving the conversation.

You can also ask directly Copy Section

You do not have to wait for the agent to suggest it. Just tell the agent you want to schedule the task:

The agent will infer the task name, schedule type, and timing from your conversation and show the scheduling card immediately.

What gets scheduled Copy Section

The scheduling card pre-fills the Scheduled Tasks dialog with:

• Task name: A short description based on the conversation
• Prompt: The original query you asked the agent
• Schedule type: Daily or hourly, based on what makes sense for the task
• Time: A suggested time (for daily tasks)

You can adjust any of these before confirming.

When Nudges Appear Copy Chapter

Nudges are designed to appear at the right moment without interrupting your workflow:

Nudges do not appear in:

• Scheduled tasks running in the background
• Chat mode (read-only, no browser automation)

Privacy Copy Chapter

Browseros Features Sync To Cloud (`docs/browseros/features/sync-to-cloud.mdx`) Copy Section

title: "Sync to Cloud" Copy Chapter

Sign in to BrowserOS and your data follows you everywhere. Your conversations, AI model settings, and scheduled tasks sync automatically to the cloud so you never lose your setup.

Why Sign In? Copy Chapter

Without an account, everything stays on one device. Sign in and your data is backed up and available wherever you use BrowserOS.

How to Sign In Copy Chapter

What Gets Synced Copy Chapter

**Your API keys are never synced.** Sensitive credentials like API keys, access keys, and session tokens stay on the device where you entered them. You will need to re-enter API keys on each new device.

What Stays Local Copy Chapter

Some settings are device-specific and do not sync to the cloud:

• API keys and secrets for LLM providers
• Theme (light/dark mode)
• Workspace folder selection
• Connected MCP servers
• Scheduled task results (run output stays on the device where the task ran)

This is intentional. Sensitive credentials never leave your device, and display preferences can differ between machines.

How Sync Works Copy Chapter

BrowserOS uses a local-first approach. Your data is always saved on your device first, then synced to the cloud in the background.

Security Copy Chapter

Browseros Features Use With Claude Code (`docs/browseros/features/use-with-claude-code.mdx`) Copy Section

title: "MCP Clients (Claude Code, OpenClaw)" Copy Chapter

BrowserOS is the best browser for AI coding agents. It comes with a built-in MCP server that gives your AI agent full browser control and direct access to 40+ external services — Gmail, Slack, GitHub, Google Calendar, Linear, Notion, and more — all through a single MCP connection.

Why Use BrowserOS with Claude Code? Copy Chapter

Getting Started Copy Chapter

Start Claude Code and try it:
```bash
claude
> Open amazon.com in BrowserOS
```

<Tip>
Run `claude --dangerously-skip-permissions` to skip confirmation prompts for each browser action.
</Tip>

To remove later:
```bash
claude mcp remove browseros --scope user
```

Replace the URL with your BrowserOS MCP URL from settings.

Add BrowserOS:
```json
{
  "mcpServers": {
    "browseros": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:9239/mcp"]
    }
  }
}
```

<Warning>
Do not add BrowserOS to `claude_desktop_config.json` as a raw `{ "url": "..." }` entry. Claude Desktop local config expects a command wrapper here, so use `npx mcp-remote <mcp_url>`.
</Warning>

Restart Claude Desktop to connect.

Connect from a Remote Machine Copy Chapter

The BrowserOS MCP server only listens on 127.0.0.1, so by default only programs on the same computer can reach it. If your agent runs somewhere else — for example a Hermes or OpenClaw agent on a VPS controlling BrowserOS on your laptop — you need a reverse tunnel that forwards requests from the remote machine to the MCP server on your laptop.

All commands below use port 9239 — replace it with the port shown on your chrome://browseros/mcp settings page.

1. Install [Tailscale](https://tailscale.com/download) on both your laptop and the VPS, and sign in to the same tailnet on both.
2. On the laptop, share the MCP port with your tailnet:
```bash
tailscale serve --bg 9239
```
3. Tailscale prints an HTTPS URL like `https://your-laptop.tailnet-name.ts.net`. On the VPS, point your agent at that URL with the `/mcp` path:
```bash
claude mcp add --transport http browseros https://your-laptop.tailnet-name.ts.net/mcp --scope user
```

Run `tailscale serve reset` on the laptop to stop sharing.

Cloudflare prints a URL like `https://random-words.trycloudflare.com`. On the VPS, connect your agent to `https://random-words.trycloudflare.com/mcp`.

<Warning>
Quick tunnels are public and unauthenticated — anyone who discovers the URL can control your browser. The URL also changes every time `cloudflared` restarts, so you must update your agent config after each restart. For anything long-running, use a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with Cloudflare Access in front, or use Tailscale instead.
</Warning>

ngrok prints a URL like `https://abc123.ngrok-free.app`. On the VPS, connect your agent to `https://abc123.ngrok-free.app/mcp`.

<Warning>
The URL is public — anyone who discovers it can control your browser — and it changes every time ngrok restarts unless you use a reserved domain. Use Tailscale instead for anything long-running.
</Warning>

Example Prompts Copy Chapter

In BrowserOS, go to localhost:3000, click the login button, and check for console errors

Take a screenshot of the current page in BrowserOS and save it to screenshots/

Search my BrowserOS history for "invoice" and list the recent matches

Read my latest Gmail messages and summarize them

Create a Linear issue for the bug I just found and post a summary to Slack

Browser Automation Tools Copy Chapter

BrowserOS exposes 53 browser automation tools to MCP clients, organized into the following categories:

40+ External App Integrations Copy Chapter

BrowserOS connects your AI agent directly to the tools you already use — no separate MCP servers to install or configure. Everything is accessible through the same BrowserOS MCP connection.

How It Works Copy Section

Supported Services Copy Section

Demo Videos Copy Chapter

Agentic coding workflow Copy Section

Browser automation with Claude Code Copy Section

Browseros Features Vertical Tabs (`docs/browseros/features/vertical-tabs.mdx`) Copy Section

title: "Vertical Tabs" Copy Chapter

BrowserOS supports vertical tabs — a side panel that lists all your open tabs along the left edge of the browser window. Instead of shrinking tab titles into a cramped horizontal strip, vertical tabs give each tab its own full-width row so you can read titles at a glance, even with dozens of tabs open.

Why Vertical Tabs? Copy Chapter

Modern screens are wide, not tall. A horizontal tab bar wastes vertical space you could use for content, and tabs quickly become unreadable as they shrink. Vertical tabs solve both problems:

Enabling Vertical Tabs Copy Chapter

Toggle vertical tabs on or off from the Customization settings page.

To switch back, return to the same setting and turn the toggle off. Your tabs move back to the horizontal strip instantly.

How It Works Copy Chapter

When vertical tabs are enabled, the tab strip relocates from the top of the window to a collapsible side panel on the left. Each tab is displayed as a row showing the page favicon and full title.

• Click a tab row to switch to it.
• Right-click a tab for the standard context menu (pin, mute, close, move to group).
• Drag tabs up or down to reorder them, or drag them into and out of tab groups.
• The panel can be collapsed to show only favicons, freeing up even more horizontal space.

Vertical Tabs + Tab Groups Copy Chapter

Vertical tabs pair naturally with tab groups. Groups appear as collapsible sections in the side panel, making it easy to keep projects separate and fold away tabs you are not actively using.

Browseros Integrations N8n (`docs/browseros/integrations/n8n.mdx`) Copy Section

title: "n8n Integration" Copy Chapter

Connect BrowserOS to n8n to build automated workflows. Your n8n AI agents can control the browser—open pages, click buttons, extract data, and fill forms.

What You Can Build Copy Chapter

• Lead enrichment — Pull a list of LinkedIn URLs from a spreadsheet and scrape each profile
• Price monitoring — Check product prices hourly and send a Slack alert when they drop
• Form automation — Auto-fill job applications using data from your CRM
• Data extraction — Scrape authenticated pages that require login

Prerequisites Copy Chapter

Before you start:

• BrowserOS running with MCP server enabled (Settings → BrowserOS as MCP)
• n8n running locally (npx n8n or install globally with npm install n8n)

Setup Copy Chapter

1. Install the MCP community node Copy Section

In n8n, go to Settings → Community Nodes and install n8n-nodes-mcp:

2. Create a workflow Copy Section

Build a workflow with these nodes:

1. Add a Chat Trigger node (receives your messages)
2. Add an AI Agent node and connect it to the trigger
3. Add a Chat Model under the AI Agent (e.g., OpenAI, Claude)
4. Add an MCP Client Tool under the AI Agent

3. Configure the AI Agent Copy Section

In the AI Agent node, set Source for Prompt to Connected Chat Trigger Node.

4. Connect to BrowserOS Copy Section

Click on the MCP Client node and configure:

• Endpoint: Your BrowserOS MCP URL (find it in Settings → BrowserOS as MCP)
• Server Transport: HTTP Streamable

5. Test it Copy Section

Save the workflow, click Open chat, and try:

open google.com in BrowserOS

Troubleshooting Copy Chapter

If the connection fails:

• Make sure BrowserOS is running
• Check that MCP server is enabled in BrowserOS settings
• Verify the port number matches your BrowserOS MCP URL

Browseros Troubleshooting Connection Issues (`docs/browseros/troubleshooting/connection-issues.mdx`) Copy Section

title: "Has Agent Crashed?" Copy Chapter

If you see "Failed to Fetch" or "Unable to connect to BrowserOS agent", your agent has been killed.

Windows: Did you allow the BrowserOS Agent? Copy Chapter

When BrowserOS starts for the first time on Windows, a popup will ask if you want to allow BrowserOS Agent to access the network. Click Allow — the agent runs as a separate process alongside the browser and needs this permission to work. If you clicked Cancel or missed this prompt, the agent won't be able to connect.

To fix this, go to Windows Security → Allow an app through your network settings, and make sure BrowserOS Agent is enabled.

Fix It Copy Chapter

<Frame>
  
</Frame>

<Frame>
      
    </Frame>

    <Note>If the agent still doesn't reconnect, end both **BrowserOS** and **BrowserOS Agent** in Task Manager, then reopen the app.</Note>
  </Tab>
  <Tab title="macOS">
    Right-click BrowserOS in the Dock → **Quit**, then reopen the app.
  </Tab>
</Tabs>

Still Not Working? Copy Chapter

<Tabs>
  <Tab title="macOS/Linux">
    Find the process:
    ```bash
    lsof -i :9100
    ```

    Kill it (replace `PID` with the process ID from above):
    ```bash
    kill -9 PID
    ```
  </Tab>
  <Tab title="Windows">
    Find the process:
    ```powershell
    netstat -ano | findstr :9100
    ```

    Kill it (replace `PID` with the process ID from above):
    ```powershell
    taskkill /PID PID /F
    ```
  </Tab>
</Tabs>

Then restart BrowserOS.

**Windows users:** Antivirus software sometimes triggers a false positive. Try temporarily disabling your antivirus and restarting BrowserOS.

Get Help Copy Chapter

If you're still experiencing issues, reach out:

Browseros Update Linux (`docs/browseros/update/linux.mdx`) Copy Section

title: "Update on Linux" Copy Chapter

<Frame>
  
</Frame>

Browseros Update Macos (`docs/browseros/update/macos.mdx`) Copy Section

title: "Update on macOS" Copy Chapter

<Frame>
  
</Frame>

Browseros Update Windows (`docs/browseros/update/windows.mdx`) Copy Section

title: "Update on Windows" Copy Chapter

<Frame>
  
</Frame>

<Frame>
  
</Frame>

Wait about 30–40 seconds. The temporary folder will disappear on its own, and the updated **BrowserOS** app will automatically appear on your desktop.

<Frame>
  
</Frame>

<Note>If BrowserOS was already running, close it completely and reopen it for the update to take effect.</Note>

<Frame>
  
</Frame>

<Warning>If you click Cancel, the agent won't be able to connect and you'll see a "Failed to Fetch" error. If this happens, go to **Windows Security → Allow an app through your network settings** and enable **BrowserOS Agent**.</Warning>

Your settings and data will be preserved after the update.

Neo Mcp Claude Desktop (`docs/neo/mcp/claude-desktop.mdx`) Copy Section

title: "Claude Desktop and Cowork" keywords: ["Claude Desktop MCP", "Claude Cowork MCP", "BrowserOS neo Claude Desktop extension"] Copy Chapter

Claude Desktop and Claude Cowork both run inside the same Claude app. A single BrowserOS neo extension gives them both a real browser to work in.

Install Copy Chapter

Verify Copy Chapter

Open BrowserOS neo, then in Claude Desktop ask:

Open browseros.com/agents in a new tab and tell me the page title.

Claude opens the page inside BrowserOS neo and replies with the title.

Cowork gets it too Copy Chapter

Cowork runs inside Claude Desktop, so the same extension unlocks it there as well. Ask Cowork to do a task that involves the web, and it uses BrowserOS neo the same way Claude Desktop does. No second install.

Where the extension came from Copy Chapter

The extension is a small forwarding wrapper: Claude Desktop talks to it locally, and it forwards every call to BrowserOS neo's local endpoint. Nothing goes to a server we control. Source, install file, and privacy policy live in the browserclaw-claude-desktop repo.

Troubleshooting Copy Chapter

Claude says BrowserClaw is not running. Open BrowserOS neo. The local server starts with the app. The message uses the old product name because it comes from the extension, which still ships under it.

The extension does not load. Restart Claude Desktop. If it still fails, remove the extension from Settings and install the latest release again.

Claude is not using the browser when it should. Say Use BrowserClaw for this the first time and Claude picks up the tools. That is the name of the MCP entry, so it is the name Claude recognizes.

Where to next Copy Chapter

Neo Mcp Manual (`docs/neo/mcp/manual.mdx`) Copy Section

title: "Manual URL setup" keywords: ["BrowserOS neo manual MCP setup", "BrowserOS neo skill", "install browseros-neo skill", "Hermes MCP", "Vercel AI SDK MCP", "OpenClaw MCP"] Copy Chapter

Any AI tool that speaks MCP over HTTP can use BrowserOS neo. Adding the MCP server connects the two, and installing the BrowserOS neo skill on top improves the experience.

The MCP syntax varies by tool, and so does the way skills are loaded. Here are the tools we have documented so far.

First, grab the endpoint URL from BrowserOS neo. Open a new tab, click MCP in the sidebar, and click Copy at the top of the page. It looks like this:

http://127.0.0.1:9200/mcp

Now pick your AI tool below.

Install the skill Copy Chapter

The skill is one SKILL.md file, published from the BrowserOS repository. Most agents read skills from a shared .agents/skills directory, and the quickest way to put it there is the skills.sh CLI:

npx skills add browseros-ai/browseros --skill browseros-neo

That writes ./.agents/skills/browseros-neo/SKILL.md in the current project and symlinks it for agents that use their own directory. Add -g instead to install it once for every project.

Not every agent reads .agents/skills, so check your tool below.

Hermes Agent Copy Chapter

Hermes Agent from Nous Research supports connecting to external HTTP MCP servers via its YAML config. Full details in Hermes' MCP docs.

Open ~/.hermes/config.yaml and add a mcp_servers entry:

mcp_servers:
  browseros-neo:
    url: "http://127.0.0.1:9200/mcp"

Then reload Hermes:

• Inside an existing hermes chat session, run /reload-mcp.
• Or restart Hermes.

Hermes also has a CLI command that adds a server interactively: hermes mcp add browseros-neo. Either path works.

Adding the skill. Hermes does not read .agents/skills. It keeps skills in ~/.hermes/skills/, so install it from the file directly:

hermes skills install https://raw.githubusercontent.com/browseros-ai/BrowserOS/main/skills/browseros-neo/SKILL.md

Check it landed with hermes skills list, or /skills inside a chat session. Hermes loads the name and description up front and pulls the full text only when it needs it, so the skill costs almost nothing until it is used. Full details in Hermes' skills docs.

Vercel AI SDK Copy Chapter

The Vercel AI SDK supports MCP tools via the @ai-sdk/mcp package. Full details in the AI SDK MCP docs. Point the client at BrowserOS neo's endpoint URL, pull the tools, and pass them into streamText or generateText.

import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'http://127.0.0.1:9200/mcp',
  },
});

const tools = await mcpClient.tools();

const result = await streamText({
  model: 'xai/grok-4.5',
  tools,
  prompt: 'Open the running BrowserOS neo tab and summarise what my agent just did.',
  onFinish: async () => {
    await mcpClient.close();
  },
});

The AI SDK docs recommend closing the client once you're done. In streaming code that means mcpClient.close() inside onFinish. In non-streaming code, use a try / finally block.

Adding the skill. The AI SDK is a library rather than an agent, so nothing discovers skills for you. Run the npx skills add command above, then read the file into your system prompt:

import { readFile } from 'node:fs/promises';

const skill = await readFile('.agents/skills/browseros-neo/SKILL.md', 'utf8');

const result = await streamText({
  model: 'xai/grok-4.5',
  tools,
  system: skill,
  prompt: 'Book me a table for four on Friday.',
});

For more than one skill, the AI SDK's agent skills guide covers loading names and descriptions up front and fetching the full text on demand with a loadSkill tool.

OpenClaw Copy Chapter

OpenClaw is an open-source personal AI assistant that can act as an MCP client. Full details in OpenClaw's MCP docs.

The fastest path is the CLI:

openclaw mcp add browseros-neo --url http://127.0.0.1:9200/mcp --transport streamable-http

Or edit ~/.openclaw/openclaw.json directly:

{
  "mcp": {
    "servers": {
      "browseros-neo": {
        "url": "http://127.0.0.1:9200/mcp",
        "transport": "streamable-http"
      }
    }
  }
}

Verify the connection with the built-in doctor:

openclaw mcp doctor browseros-neo --probe

Adding the skill. OpenClaw already reads .agents/skills, both in the workspace and at ~/.agents/skills, so the npx skills add command above is enough and there is nothing else to wire up. If you would rather use OpenClaw's own installer, it takes a skills.sh reference:

openclaw skills install skills-sh:browseros-ai/browseros/browseros-neo

Add --global to install it for every workspace. Confirm with openclaw skills list. Full details in OpenClaw's skills docs.

Any other MCP-compatible AI tool Copy Chapter

The pattern is the same: paste http://127.0.0.1:9200/mcp into the AI tool's own MCP server config, using whatever syntax that tool expects. BrowserOS neo's endpoint uses Streamable HTTP transport (per the current MCP spec), so any client that supports Streamable HTTP works.

For the skill, run npx skills add browseros-ai/browseros --skill browseros-neo and then check where your agent looks for skills. Most read .agents/skills and will find it with no further work. If yours keeps them somewhere of its own, copy .agents/skills/browseros-neo/SKILL.md into that directory, or point its own installer at the file:

https://raw.githubusercontent.com/browseros-ai/BrowserOS/main/skills/browseros-neo/SKILL.md

If you get your AI tool talking to BrowserOS neo and want to help others do the same, please open a discussion with the setup steps.

Where to next Copy Chapter

Packages Browseros Bos Build Docs Build Cli (`packages/browseros/bos_build/docs/build-cli.md`) Copy Section

Build CLI Reference

Everything browseros build can do beyond the common invocations in
../README.md. Run these from packages/browseros.

Seeing and tweaking a plan Copy Chapter

The composed plan is always a projection of plan() in core/planner.py —
generated, never hand-copied, so it cannot drift from what actually runs.

# Print the composed steps + required env vars and exit
# (works without a chromium checkout)
browseros build --preset release --show-plan

# Comment out steps, as an operation: subtract from the composed plan
browseros build --preset release --skip upload,series_patches

# Resume the tail after a failure without recompiling
browseros build --preset release --from sign_macos

# One-off GN overrides while iterating (appended last, so they win)
browseros build --preset debug --gn-arg symbol_level=2 --gn-arg dcheck_always_on=true

`--skip` Copy Section

Subtracts after composition, so it never re-triggers composition rules —
skipping sign_windows will not add mini_installer. CLI --skip and a
profile's skip: list union. Unknown step names fail loudly; a valid step
absent from this plan is a no-op, so a saved skip: keeps working as presets
evolve. It is subtraction from the canonical plan, never a copy of it.

`--from` Copy Section

Resumes the composed (post-skip) run timeline at a step. Earlier runs are
dropped, the first run containing the step is sliced, later runs stay whole. A
failed universal merge resumes with just
--arch universal --from merge_universal — no recompiles.

CLI-only: a resume is a one-off, so there is no from: profile key.

`--gn-arg` Copy Section

Repeatable, valid in any mode. Appends GN overrides after the flags file and
the product args, so last write wins and configure honors them without editing
the committed config/gn/*.gn files.

Values are verbatim GN: bools and ints bare, strings with embedded quotes
(--gn-arg 'target_cpu="arm64"'). CLI-only by design — a profile that wants
different flags should use a different flags file.

Only the configure step writes args.gn. A plan that skips it (for example
--from compile) reuses the existing file untouched, including any overrides a
previous invocation wrote there.

Modules profiles — "you own this list now" Copy Chapter

For the rare run that genuinely wants an arbitrary sequence, a profile may carry
modules: as an explicit opt-in — a local, commentable file that bypasses the
planner entirely:

# my-tail.yaml (local only — never shipped)
modules: [compile, sign_macos, package_macos]
build_type: release   # only valid with modules:; defaults to debug
arch: arm64           # single arch only

Planner-owned keys (preset, clean, provision, download, sign,
upload, resource_mode, skip) and the --skip / --from flags are
rejected alongside modules:. You own the list; edit it directly. Shipped
profiles stay switch-based, and a golden test keeps them from drifting.

The same escape hatch exists on the command line for one-off runs:

browseros build --modules clean,compile,sign_macos --product browseros
browseros build --list                                # every available step

Phase flags are the middle ground — auto-ordered, no explicit step list:

browseros build --setup --build --sign --package
browseros build --build --sign                        # skip setup

Note that --prep does not apply series_patches. Run
browseros build -m series_patches separately if you need them.

Remote and ephemeral runners Copy Chapter

A fresh machine needs nothing outside this package:

uv sync
uv run browseros source ensure --root "$CHROMIUM_ROOT" --reset
uv run browseros source clean-outputs --root "$CHROMIUM_ROOT" --all-products --arch x64
uv run browseros build --profile release-ci --chromium-src "$CHROMIUM_ROOT/src" --arch x64

The complete preparation command holds the checkout lock, fetches the exact
missing pin, resets source and managed dependencies, then runs sync/hooks.
Omit --reset to preserve local changes; conflicting checkout/sync operations
fail without silently discarding work. --step checkout and --step sync remain
partial-operation compatibility commands. Cache restore/save also hold the lock;
archives exclude lock files. Hosted roots remain exclusive to their workflow job.

macOS CI uses source workspace through macos-chromium-workspace.sh: it refreshes
the persistent base once and holds its lock through every requested product copy.
Per-product output/resource cleanup follows; release-ci and nightly-macos
then skip source cleanup and provisioning. source cleanup-workspaces removes
owned copy contents but retains small ownership markers and lock directories so
waiting processes cannot acquire a replacement lock inode. Local release and
explicit --modules clean retain their reset behavior.

Concurrency Copy Chapter

Every build takes an exclusive lock on its Chromium checkout, keyed by the
resolved src path and held regardless of product. A second build against the
same checkout fails fast and tells you who holds it. Pass --lock-wait to queue
behind it instead.

Release builds run git reset, git clean, and patch application in one shared
checkout, which is why the lock exists. The lock file sits next to the gclient
root rather than under src/, so git clean cannot delete it mid-build.

Products Copy Chapter

A product is one file: products//product.py with a
ProductDescriptor.define() call — about five irreducible inputs, roughly forty
fields derived by convention, keyword overrides for deviations — plus its server
bundle definitions. Verify with:

browseros product doctor          # identity uniqueness + branding assets

Packages Browseros Bos Build Docs Docker Image (`packages/browseros/bos_build/docs/docker-image.md`) Copy Section

Neo Docker image

ghcr.io/browseros-ai/neo runs BrowserOS neo on a virtual display, streams it over
noVNC, and exposes Neo's MCP server. One tag covers linux/amd64 and linux/arm64.
The user guide is docker/neo/README.md; this page is
for building and publishing it.

Where things live Copy Chapter

Prerequisite: a Linux release with both architectures Copy Chapter

The image installs released packages. A version can be published only when its
releases/browserclaw/<version>/linux/release.json lists both x64_deb and
arm64_deb, i.e. the Neo release ran with linux_arch=all and uploaded to R2.
browseros release docker --push checks this before building and names what is missing:

❌ Neo 0.51.1.4 has no x64_deb on the CDN

Build locally Copy Chapter

From packages/browseros:

# This machine's architecture, loaded into local Docker (arm64 on Apple silicon).
uv run browseros release docker --version 0.52.0.1

# A package that isn't on the CDN, e.g. a CI artifact. Loaded locally only.
uv run browseros release docker --deb ~/Downloads/BrowserOS_neo_v0.52.0.1_arm64.deb

# Then run and check it.
cd docker/neo
NEO_VERSION=0.52.0.1 docker compose up -d --wait
python3 smoke.py
docker compose down

A local .deb named like a release package (BrowserOS_neo_v<version>_<arch>.deb)
supplies the version and platform itself; otherwise pass --version.

Publish Copy Chapter

gh workflow run release-docker.yml -f version=0.52.0.1              # version tag only
gh workflow run release-docker.yml -f version=0.52.0.1 -f latest=true

The workflow builds the amd64 image, runs smoke.py against it, then pushes both
architectures with GITHUB_TOKEN. Tag latest only once the version has been
promoted (browseros release publish); a draft should never become latest.

From a workstation instead, after docker login ghcr.io with a token that has
write:packages, and with a buildx builder that can build arm64 and amd64:

uv run browseros release docker --version 0.52.0.1 --push [--latest]

First publish Copy Chapter

A new ghcr package starts private. After the first push, open the package's settings
on GitHub and change its visibility to Public (the org must allow public packages).
Public images pull without logging in.

browseros release docker --push links the package to this repository by putting an
org.opencontainers.image.source annotation on the pushed index (it also requests a
provenance attestation so a single-platform push has an index to annotate). The
Dockerfile's label of the same name is not enough on its own: GitHub reads the
index, and the label only reaches the per-platform images. The link is what lets the
workflow's GITHUB_TOKEN push; a package created without it must be connected in its
package settings first.

Runtime notes for maintainers Copy Chapter

• Ports inside the container are fixed: noVNC 6080, MCP proxy 9010
  (--browseros-proxy-port), CDP 9110 and claw-server 9210 (pinned, loopback only).
• All state lives under /data. The profile is /data/profile. claw-server's database,
  recordings, skills and agent settings are /data/browserclaw (BROWSERCLAW_DIR); its
  default, ~/.browserclaw, is not on the volume.
• Remote MCP needs a profile setting. Docker's port forwarding doesn't arrive from
  loopback, so the entrypoint merges browseros.server.allow_remote_in_mcp: true into
  the profile's Local State before Neo starts.
• Shutdown quits Neo over CDP. neo-quit sends Browser.close; Chromium's SIGTERM
  path skips flushing. Neo on Linux still records a crash even after a clean quit,
  so Neo starts with --hide-crash-restore-bubble.
• The sandbox is off by default (NEO_SANDBOX=false): Docker's default seccomp
  profile blocks the user namespaces it needs. With the sandbox off, a managed policy
  hides Chromium's --no-sandbox warning bar.
• claw-server runs in hosted mode (BROWSERCLAW_MODE=hosted): agents get the browser
  tools without skills, human help or name_session, and name tasks with a taskName
  argument. The entrypoint also turns human help off through /api/v1/settings/agent on
  every start, before the container reports healthy, for claw-servers that predate the mode.

Packages Browseros Bos Build Docs Linux Arm64 (`packages/browseros/bos_build/docs/linux-arm64.md`) Copy Section

Neo Linux arm64 releases

Neo can build Linux arm64 packages with the existing x64 WarpBuild runner.
bos_build already selects target_cpu = "arm64", installs Chromium's arm64
sysroot, downloads the published arm64 Neo server, and packages an arm64
AppImage and Debian archive. This design connects those capabilities to the
release workflow and its exact artifact checks.

Interface and ownership Copy Chapter

The Neo release selection is linux_arch=all|x64|arm64, defaulting to all so
routine releases include both Linux architectures. Explicit x64 or arm64
selections narrow the artifact contract. The standalone/reusable Linux workflow
calls this input arch and keeps its x64 default for BrowserOS and source-mode
callers. CLI defaults remain compatible with historical release receipts.

The deep module is the existing release metadata validator in release/common.py.
Its interface accepts the selected platforms and architecture sets, then checks
product, version, source commit, workflow provenance, and the exact artifact set.
GitHub drafts, download promotion, and appcast generation cross the same seam;
callers do not independently interpret which Linux packages constitute a release.

Missing or extra keys fail validation. Selecting arm64 must never silently
attach x64 packages left by another run. Archive names and existing download
aliases remain architecture-specific; the x64 aliases retain their historical
names.

Neo dispatch: platforms + linux_arch + publication
  -> preflight validates and freezes the selection/source
  -> release-linux expands product x architecture
       -> existing x64 build runner
       -> published server for the target architecture
       -> Chromium build -> verified AppImage + Debian pair
       -> versioned artifacts and Linux release.json
  -> draft finalizer validates the selected exact artifact set
  -> explicit promotion uses that same architecture selection

Metadata is one serialized handoff Copy Chapter

Both architectures own entries in the same versioned linux/release.json.
Its existing read/merge/write operation is not atomic. The Linux matrix therefore
runs with max-parallel: 1, inside the existing release-linux concurrency group.
This deliberately serializes compilation as well as publication: it is the
smallest ownership rule that prevents lost updates without a new storage protocol
or another finalization job. Each architecture still has its own checkout cache
key and product output directory.

A retry of a failed architecture may use a later workflow attempt than an already
successful sibling. Linux metadata merges only when the release identity, source,
workflow run, and complete pinned resource versions match. Unpinned standalone
receipts are replaced across attempts because mutable latest resources may
have changed. Each Linux artifact records its
own workflow attempt. The platform-level attempt is present only when every
artifact belongs to that attempt; mixed attempts cannot claim a single attempt.
An explicitly requested attempt still fails closed for a mixed receipt. Other
platforms retain their existing merge rules.

Build host and resource mode Copy Chapter

Use the existing x64 Linux runner to cross-compile. AppImage tooling is selected
for the host, while its ARCH setting and Debian metadata describe the target.
Installing an arm64 appimagetool on the x64 host would break packaging.

This release path uses published resources: the Neo server release already
produces linux-arm64, and extensions/onboarding are architecture-independent.
The separate source-resource provider currently supports Linux x64 only. The
Linux workflow rejects source mode with an arm64-containing selection during
planning, before allocating an expensive browser runner. Adding source mode
requires a Cargo GNU cross-linker and its own server/lane contract work.

Run an arm64 build Copy Chapter

After this change is merged, dispatch from the default branch:

gh workflow run release-browserclaw.yml --ref main \
  -f platforms=linux -f linux_arch=arm64 -f publication=draft-only

This binds the browser to exact published-resource versions created by the same
release transaction and leaves a browser draft. draft-only creates private
resource drafts/versioned objects and does not promote their aliases or feeds.
Omit linux_arch to build both architectures. Releases selecting only macOS or
Windows accept the default without building Linux.

Expected arm64 browser assets:

BrowserOS_neo_v<VERSION>_arm64.AppImage
BrowserOS_neo_v<VERSION>_arm64.deb

For standalone Linux builds using the existing published resources:

gh workflow run release-linux.yml --ref main \
  -f products=browserclaw -f arch=arm64 -f upload_to_r2=true

A standalone arch=all build requires one product and explicit server_version,
extension_version, and onboarding_version inputs. Otherwise two builds could
resolve different mutable latest resources hours apart. The full Neo workflow
supplies these exact versions automatically; an unpinned standalone request for
both architectures fails before any browser runner is allocated.
Server/onboarding pins must be numeric MAJOR.MINOR.PATCH releases; extension
pins use the existing numeric Chrome version format. Mutable aliases such as
latest and alpha are rejected both during planning and retry retention.

Pass --linux-arch arm64 (or all) to browseros release github create,
browseros release publish, and browseros release appcast when binding those
operations to an architecture-selected release.
An explicit CLI architecture always binds exact pairs, including x64, without
requiring additional provenance flags. Existing generic CLI calls with no release
contract keep their legacy behavior; when a contract is requested and the Linux
architecture is omitted, that contract defaults to x64.

Evidence required before shipping Copy Chapter

The implementation checks the release tooling without generating Chromium build
files. A successful cross-build is still required to establish that the pinned
Chromium source and BrowserOS patches compile for Linux arm64.

On a real Linux arm64 machine, inspect the ELF architecture and Debian metadata,
install the Debian archive, extract and launch the AppImage, and verify browser
startup, the sandbox, Neo extension startup, and the bundled Neo server. Verify
these on the intended distribution baseline, including its shared-library/glibc
requirements. Cross-host packaging deliberately skips target execution and library
checks, so those checks alone cannot establish runtime compatibility.

Packages Browseros Bos Build Docs Nightly Macos Ci (`packages/browseros/bos_build/docs/nightly-macos-ci.md`) Copy Section

Nightly macOS CI

The two manual entry workflows complete and publish one product each:

Dispatch either entry from main; neither has a schedule or release-shape inputs.

gh workflow run nightly-macos-browseros.yml --ref main
gh workflow run nightly-macos-browserclaw.yml --ref main

.github/workflows/reusable-build-macos-nightly.yml is named
Reusable: Build macOS nightly and accepts only workflow_call. It retains the
existing signed arm64 build, provisioning profiles, published resources, deferred
R2 upload, and unconditional Chromium-workspace and signing-keychain cleanup.

Product transaction Copy Chapter

Each entry freezes one source SHA, reserves a browser version and its own server
and extension versions, then prepares those two exact components. BrowserOS pins
server, agent, and the existing app-onboard version. BrowserOS neo pins
claw-server-rust, browserclaw, and the existing claw-onboard version.
Onboarding bundles continue to release independently.

manual dispatch from main
  -> reserve one product transaction on a draft PR
  -> prepare and verify its server and extension
  -> build one signed macOS arm64 browser
  -> finalize its server and extension; assemble its server appcast
  -> acquire release-feed-snapshots
  -> compose current-main snapshots and render its extension pin
  -> reconcile the product gate and merge state
  -> conditionally create or verify its immutable DMG and receipt
  -> publish current committed feeds and reconcile its rolling prerelease

A sibling build or finalizer is never a dependency. Component callers pass
state_owner: suite and disable standalone feed publication, leaving the product
transaction as the owner of its tracked state.

The retry identity is nightly-- and the reservation branch
is bot/release-nightly--<12-source-chars>. Different products therefore
have different records even when dispatched at the same source commit. The
transaction PR is created as a draft. Open, closed, and merged canonical suite
records continue to reserve their versions; closing a failed PR does not free a
version already used by immutable uploads.

Builders always check out the Reservation SHA. The state and merge commits are
never build inputs. After branch deletion, refs/pull//head keeps the
validated reservation reachable for recovery. Shared browser version and build
offset allocation remains monotonic across both products and saved family records.

Shared feeds and publication recovery Copy Chapter

One release-feed-snapshots job holds the lock from current-main resolution
through state merge and publication. It writes only its server alpha appcast and
the three shared extension snapshots. Rendering pins only the selected extension;
unpinned entries carry their newer live or committed versions through
--baseline-root. This preserves a sibling whose snapshot merge succeeded but
whose R2 upload failed. Standalone extension publishers use the same boundary.

Final state composition keeps the checkout HEAD at Source SHA, restores the
selected snapshots from current main, and passes that main SHA as
--state-base-sha. Backend reconciliation preserves unrelated and sibling state
while retaining the original reservation and selected component pins.

Publication first verifies that the transaction is merged and its Merge SHA is
an ancestor of current main. It conditionally creates the product's immutable
DMG and receipt before exposing any mutable feeds. Identical bytes and transaction
bindings are accepted on retry; conflicts fail without overwrite. The publisher
restores current committed feed files, so recovery cannot overwrite a later
sibling snapshot with files from the old transaction merge.

Use Re-run failed jobs on the original run for post-build or post-merge
failures. An already-merged publication skips rendering and state reconciliation,
reuses the original signed Actions artifact, and publishes current committed
feeds. A new full run cannot restart an already-merged transaction. Signed
artifacts are retained for 14 days; recovery needs those exact bytes.

Live feeds retain downgrade guards; nightlies never pass --allow-downgrade.
Rolling publication is source- and checksum-aware: a newer product release is a
superseded/no-op, an exact partial draft resumes, and conflicting source/version
or asset identities fail. A release record and its live tag must resolve to the
same source before cleanup or replacement is allowed.

Cutover and saved family runs Copy Chapter

The old .github/workflows/nightly.yml dispatch entry and
nightly-macos-product.yml helper are removed from current main. Historical runs
retain their saved workflow definitions, including that helper. Both new entries
retain the historical top-level release-suite concurrency group with
cancel-in-progress: false and queue: max. This conservatively serializes whole
nightly runs during cutover: an active or rerun family transaction cannot overlap
a product transaction, while each new graph can succeed independently.

Legacy records without a product field remain family records with identity
nightly-. Inspect or recover those with the legacy CLI by omitting
--product, or rerun failed jobs on the original family run. Their draft PRs,
closed records, and pre-PR reservation branches remain allocation history. No
automatic cancellation, closure, or migration of those records occurs.

Historical standalone extension-feed runs saved before this change do not have
the shared publication lock; finish those runs before starting new nightlies.
Rewriting main history remains unsupported because reservation provenance must
remain auditable.

Mac runner and resources Copy Chapter

The reusable worker requires [self-hosted, macOS, ARM64, browseros-builder] and
shares macos-build with full releases. Component allocation retains
release-component-allocation; both locks retain pending jobs with queue: max.

The profile keeps resource_mode: published and executes:

uv run browseros build --profile nightly-macos --product <browseros-or-browserclaw> \
  --arch arm64 --resource-mode published --chromium-src "$CHROMIUM_SRC"

Set BROWSEROS_REPO_PATH to the persistent BrowserOS checkout and
BROWSEROS_CHROMIUM_SRC to the warm CI-owned Chromium clone base. The runner must
run in the logged-in GUI user's session with Xcode, depot_tools, uv, gh,
signing/notarization credentials, and enough disk for disposable workspaces.
The Chromium helper fetches the exact pin and syncs the CI base before copying it
under the same checkout lock into a product-qualified APFS workspace;
both workspace and signing-keychain cleanup run under if: always().

The optional PROD_MACOS_BROWSEROS_PASSKEY_PROFILE_B64 and
PROD_MACOS_BROWSERCLAW_PASSKEY_PROFILE_B64 secrets remain product-specific.
Missing profiles leave normal signing available without platform passkeys;
configured invalid profiles fail before the long build.

Packages Browseros Bos Build Docs Release Ci (`packages/browseros/bos_build/docs/release-ci.md`) Copy Section

Browser release CI

The full BrowserOS and BrowserOS neo workflows orchestrate the existing
component release workflows before building the browser. Component workflows
own component versions and publication. Native browser lanes consume the
normal published-resource manifests and latest aliases.

Signed nightlies use independent product transactions through
nightly-macos-browseros.yml and nightly-macos-browserclaw.yml. Each freezes its
source and resource pins, builds one signed browser, and merges only its product
state before publishing its immutable browser artifacts and rolling prerelease.
The shared allocation and publication locks protect versions and sibling feed
entries. Historical family transactions remain recoverable; see
nightly-macos-ci.md for ownership and cutover details.

The existing release-browseros.yml and release-browserclaw.yml full-release
entrypoints retain their native lane orchestration. Nightly browser jobs build
the exact reservation commit (the frozen source plus its deterministic version
overlay); later state commits and squash merges are never browser build inputs.

Full-release graph Copy Chapter

Both products use the same fixed sequence:

dispatch from main
  -> publish server release, latest resources, and alpha OTA
  -> reflect the successful server version on main
  -> publish extension release, versioned CRX, and alpha/bundled feeds
  -> reflect the successful extension version on main
  -> Linux x64 ───────┐
     Windows x64 ─────┼─> create or refresh the browser draft
     macOS universal ─┘

BrowserOS calls release-server.yml and releases the agent extension.
BrowserOS neo calls release-claw-server.yml and releases the browserclaw
extension. Each reusable component workflow must finish successfully before
the next stage starts. A failed component release prevents every native
browser lane from starting.

The full workflow freezes the dispatch SHA and passes it to every component
and browser build. Version reflection is intentionally separate: a component
first allocates and builds its next version from that SHA, publishes its tag,
GitHub release, and canonical R2 objects, and only then opens the version-bump
PR. A failed build or publication never changes the committed component
version.

The native lanes use resource_mode: published. This is the same path used by
normal local published-resource builds, but the orchestrator pins the exact
server and product-extension versions returned by its component jobs plus the
onboarding version recorded by the frozen checkout. The unchanged extension
pins come from that checkout's bundled manifest.
This prevents another release from changing mutable latest or feed aliases
while a native browser lane waits for a runner.

Dispatch Copy Chapter

A dispatch without inputs is a full release: it publishes the product's server
and extension, updates alpha, builds signed Windows x64 and signed macOS
universal, uploads browser deliverables, and creates a draft browser GitHub
release. Neo builds both Linux x64 and arm64 by default; BrowserOS builds Linux
x64. release-browseros.yml has no release-shape inputs.

gh workflow run release-browseros.yml --ref main
gh workflow run release-browserclaw.yml --ref main

release-browserclaw.yml can narrow that run. Every input defaults to the full
release, and preflight rejects anything else before allocating a version:

draft-only passes defer_finalize: true to both component workflows. Each
component still allocates a version from the frozen SHA, uploads its immutable
versioned R2 objects and keeps a private GitHub draft, and the browser lanes pin
those exact versions. Nothing downstream of component finalization runs: no
component tags, server latest alias, public component releases, server OTA,
extension alpha/bundled feeds, or version-reflection PRs. The macOS lane also
runs with notify: false, which skips its Slack failure ping and blanks
SLACK_WEBHOOK_URL so a builder .env cannot post. The browser draft is
created as usual from only the selected receipts.

# Signed macOS arm64 test build with private component drafts.
gh workflow run release-browserclaw.yml --ref main \
  -f platforms=macos -f macos_arch=arm64 -f publication=draft-only

# Cross-compiled Linux arm64 test build with private resource drafts.
gh workflow run release-browserclaw.yml --ref main \
  -f platforms=linux -f linux_arch=arm64 -f publication=draft-only

Linux arm64 uses the existing x64 WarpBuild runner and published arm64 server
resources. linux_arch=all builds the x64 and arm64 AppImage/DEB pairs serially
so their shared Linux release metadata cannot lose an architecture. The browser
draft checks exactly the selected pairs. Pass the same --linux-arch selection
to later release CLI validation/promotion. See Linux arm64 for
the design, source-mode limit, retry provenance, and native verification gate.

The deferred component drafts remain allocations bound to that source SHA: a
later dispatch of the same SHA reuses them, and releases from other SHAs skip
their versions. Browser R2 objects are versioned but not write-once, so give the
next real release a new browser version instead of reusing a test build's.

The dispatch ref must be the repository default branch. Product, component,
native-lane, and shared Mac concurrency groups use queue: max, so up to 100
pending releases wait instead of a newer dispatch replacing an older one.

The browser version comes from resources/BROWSEROS_VERSION at the frozen
dispatch SHA. Set that version on main before dispatching when the browser
itself needs a new version. Server and extension versions are independently
allocated by their component workflows.

Standalone component releases Copy Chapter

The component workflows remain independently dispatchable and use main by
default:

gh workflow run release-server.yml --ref main
gh workflow run release-claw-server.yml --ref main
gh workflow run release-extensions.yml --ref main -f extension=agent
gh workflow run release-extensions.yml --ref main -f extension=browserclaw

Direct server dispatches default to publish_ota=true. They publish the
versioned and latest resources, render all five platform appcast fragments,
merge the tracked snapshot through a short-lived pull request, and then publish
that exact appcast to alpha.

Direct extension dispatches default to publish_alpha_feed=true. They publish
the CRX release and canonical versioned R2 object, update the alpha and bundled
manifests atomically through a short-lived pull request, publish those exact
manifests, and reflect in-repository extension versions only after finalization
succeeds.

Production promotion remains explicit:

cd packages/browseros
uv run browseros ota server promote --product browseros --publish
uv run browseros ota server promote --product browserclaw --publish

Retry procedures Copy Chapter

Rerun failed jobs in the original full-release run:

RUN_ID=<github-run-id>
gh run rerun "$RUN_ID" --failed
gh run watch "$RUN_ID" --exit-status

Component allocation and publication are idempotent. A rerun recovers a
matching release for the same source SHA instead of silently allocating a new
version. Successful earlier stages are not rebuilt, and downstream browser
lanes stay gated until the failed stage succeeds.

For the combined signed nightly, rerun failed jobs in the original run when
possible. The stable transaction identity is nightly-. Browser
jobs fetch the transaction branch before merge, or
refs/pull//head after branch deletion, only to make the proven
transaction history reachable. They verify that history contains the recorded
reservation, then always check out reservation_sha: the frozen source plus
the exact version/component overlay, without the later tracked-state commit.
They never rebuild from the squash merge SHA, whose tree may include unrelated
main commits. A new whole-run invocation that finds the transaction already
merged fails closed; post-merge recovery must rerun failed jobs so it reuses the
successful signed artifacts from the original run.

If browser draft creation alone fails, rerun that job in the original run. It
uses the R2 metadata written by the selected native lanes and verifies the same
source SHA and workflow run ID before refreshing the draft. It runs only when
every selected lane succeeded and every unselected lane was skipped. Native lanes from
different rerun attempts are valid because GitHub keeps the run ID stable.

Local published-resource build Copy Chapter

The full workflows use the standard published-resource path. The equivalent
local build is:

cd /path/to/BrowserOS/packages/browseros
uv run browseros build \
  --preset release \
  --product browseros \
  --arch x64 \
  --resource-mode published \
  --no-sign \
  --no-upload \
  --chromium-src /path/to/chromium/src

Use --product browserclaw for BrowserOS neo. Published mode resolves mutable
component aliases, so publish the intended component releases before starting
the browser build.

Local source build Copy Chapter

Source mode remains available for local development. It builds
the product extension, onboarding bundle, and active host's server from the
checkout; only the pinned bug reporter is downloaded. It does not publish
component tags, latest aliases, server OTA, or extension feeds.

cd /path/to/BrowserOS/packages/browseros
SOURCE_SHA="$(git rev-parse HEAD)"

uv run browseros build \
  --preset release \
  --product browseros \
  --arch x64 \
  --resource-mode source \
  --source-sha "$SOURCE_SHA" \
  --no-sign \
  --no-upload \
  --chromium-src /path/to/chromium/src

Chrome, Bun, and the product's build-time secrets must be available. BrowserOS
neo additionally needs the native Rust toolchain. Source mode does not bump
versions, commit, push, or open a PR.

Publication boundary Copy Chapter

The full workflow creates or refreshes a draft browser GitHub release after
every selected native lane uploads complete R2 metadata. It does not publish the
browser appcast. Inspect the browser draft before promotion.

Required configuration Copy Chapter

Component publication and browser uploads use the R2_* secrets. BrowserOS
server builds need BROWSEROS_CONFIG_URL, POSTHOG_API_KEY, and SENTRY_DSN;
BrowserOS neo server builds need CLAW_POSTHOG_KEY. Extension builds need the
matching signing key and build-time secrets.

Windows signing needs the eSigner secrets and SPARKLE_PRIVATE_KEY. macOS uses
repository variables BROWSEROS_REPO_PATH and BROWSEROS_CHROMIUM_SRC plus
the signing and notarization secrets on the persistent builder. Signed macOS
releases require separate base64-encoded Developer ID provisioning profiles:
PROD_MACOS_BROWSEROS_PASSKEY_PROFILE_B64 for com.browseros.BrowserOS and
PROD_MACOS_BROWSERCLAW_PASSKEY_PROFILE_B64 for
com.browseros.BrowserClaw. Each profile must authorize team 8YMKWU47S5, its
bundle-specific keychain groups, and
com.apple.developer.web-browser.public-key-credential; the build validates
those claims before signing. The profiles are not interchangeable because
Apple assigns the managed capability to an exact App ID.
Until Apple approves a profile, its secret may remain unset: the corresponding
browser still builds, signs, and runs with the standard entitlements, but macOS
platform passkeys are unavailable. Once a secret is configured, a missing,
wrong, or malformed profile is a hard release error.
BROWSEROS_CHROMIUM_SRC is a dedicated, CI-owned APFS clone base. Setup keeps
its pinned Chromium identity strict but repairs local Git changes and
BrowserOS-owned output directories before the release runs against a disposable
copy-on-write workspace. The workspace is cleaned under if: always(). Runner
labels, cache behavior, and queue recovery are documented in warpbuild-ci.md;
persistent macOS setup is in nightly-macos-ci.md.

Packages Browseros Bos Build Docs Source Preparation Plan (`packages/browseros/bos_build/docs/source-preparation-plan.md`) Copy Section

Automatic release build preparation

Chromium upgrades must not require an operator to repair each release runner.
The selected BrowserOS checkout's CHROMIUM_VERSION is the source of truth.
Bring stale checkouts to that exact tag, finish cleanup, synchronize dependencies
and hooks, then build from a prepared workspace.

Source preparation and macOS workspace ownership Copy Chapter

One source-preparation implementation in bos_build owns reset, exact-tag
acquisition, checkout alignment, .gclient preservation, and dependency sync.
git_setup remains its local-build adapter; source ensure is its provisioning
adapter. Preserve the existing explicit clean commands and local no-clean
behavior. Source reset must account for gclient-managed repositories, which are
not necessarily Git submodules.

The macOS persistent base is infrastructure-owned cache state. Refresh it before
APFS copying and hold the existing checkout lock through preparation and copy.
Each product receives an independent disposable workspace; a universal build
prepares once and retains its workspace through both architectures. Product-
qualified workspace markers and state files must survive multiple requested
copies and support complete cleanup after partial failure.

All cleanup that can delete dependency toolchains must finish before the final
sync. Builds consuming prepared copies skip source cleanup and provisioning,
but retain output/checkpoint cleanup and pruning of stale resource families in
the separate persistent BrowserOS repository. Source cache publication remains
after successful sync and output cleanup, before product patches and resources.

Do not use a moving upstream branch, fetch every Chromium tag, overwrite custom
.gclient settings, or interpret matching HEAD as proof that sync succeeded.
Keep this focused; no general workspace-provider framework is needed.

Windows host prerequisites Copy Chapter

The build currently selects the locally installed Windows toolchain through
DEPOT_TOOLS_WIN_TOOLCHAIN=0. Git and gclient cannot install a missing Windows
SDK in that mode. A separate setup module must determine the SDK required by the
selected Chromium source, ensure the exact supported SDK is installed on the CI
host, and verify its required headers/libraries/tools before configuration.

The Chromium 155 release failed because its required SDK directory
10.0.28000.0 was absent. Official installation instructions specify SDK package
10.0.28000.2270. Resolve this through supported Microsoft provisioning and
explicit installed-file verification; do not change Chromium's SDK pin to an
older installed version.

Implementation ownership Copy Chapter

The two implementation pieces have independent interfaces, so empty skeleton
modules are unnecessary. Each worker uses an isolated worktree, designs the
details, completes independent review, and merges its scoped PR. Preserve both
intentions when integrating current main; never force-push.

Acceptance Copy Chapter

Exercise preparation using real disposable checkouts: missing tag, old HEAD,
dirty source and dependency repositories, interrupted sync, preserved developer
changes and .gclient configuration, checkout locking, multi-product copies,
and universal ordering. Verify Windows setup on a real Windows runner; Python
syntax or mocked installation alone is not evidence of SDK readiness.

The owner's Chromium constraints apply: no GN generation or cleanup and no
Chromium unit/browser test targets. Any Chromium source change requires the
specified autoninja -C out/Default_browseros_arm64 chrome build gate.

Completion requires merged changes and a successful full BrowserOS Neo release
workflow, including server, extension, Linux, Windows, macOS universal, and
browser draft creation. Verify the expected browser artifacts and source
identity. Production promotion remains a separate request.

Packages Browseros Bos Build Docs Warpbuild Ci (`packages/browseros/bos_build/docs/warpbuild-ci.md`) Copy Section

WarpBuild Release CI

The release Linux and Windows browser lanes run Chromium builds on WarpBuild
Azure BYOC runners:

• .github/workflows/release-linux.yml
• .github/workflows/release-windows.yml
• .github/workflows/build-browseros.yml

The full product workflows call the Linux and Windows wrappers, which delegate
one native lane to the reusable build-browseros.yml workflow. That workflow
owns the WarpBuild checkout, cache, sync, one bos_build invocation, browser
artifact upload, and lane attestation. The wrappers own their product matrix
and queue watchdog. Signed macOS releases and nightlies use the repo-scoped Mac
builder; see release-ci.md and nightly-macos-ci.md.

Runners Copy Chapter

WarpBuild provisions the Linux and Windows runners in the BrowserOS Azure
subscription through the browseros-ci-eastus BYOC stack in East US. Both
configurations are on-demand, with no standby pool and static IPs disabled.
They are ephemeral:
the VM and build disk are created for a job and discarded afterward. Their
compute SKUs and disk capacities mirror the source Azure build VMs, but they
do not clone or retain those VMs' persistent disks.

WarpBuild's Windows Server 2025 image is Hypervisor Generation 1, so its VM
family must accept a Gen1 image. Standard_D32as_v5 supports both Generation 1
and 2, making the current 32-vCPU/128-GiB configuration image-compatible. A
live smoke run successfully provisioned its VM and registered a GitHub runner.
Standard_D32ls_v5 is Gen1-compatible too, but it was rejected for this stack
after East US returned HTTP 409 SkuNotAvailable; that is a regional-capacity
failure, not an image-generation mismatch. Dalsv7 is Generation 2-only, so
Standard_D32als_v7 fails during Azure VM creation before a runner can
register with GitHub.

There is no 32-core macOS tier; 12x is WarpBuild's largest Mac. The macOS
label is kept in the runner catalog for future reusable build-browseros.yml
callers, but the current signed macOS release and nightly workflows use the
self-hosted browseros-builder runner. The macOS image version must satisfy
the chromium pin's SDK requirement — check
build/config/mac/mac_sdk.gni (mac_sdk_official_version) in the pinned
tree when bumping CHROMIUM_VERSION; chromium 148 needs the macOS 26 SDK,
and the macOS 15 image (Xcode 16.4 / SDK 15.5) fails compiling
skia_utils_mac.mm (kCGImageByteOrder32Host only exists in SDK 26).
WarpBuild runners register as self-hosted, so GitHub's 6-hour hosted-job
cap does not apply — but timeout-minutes must be set explicitly (the
implicit default is 360). The 2048 GB Linux and 1024 GB Windows build disks
leave ample headroom for the ~60-75 GB checkout and ~25-40 GB out dir. The
workflow prints df -h after each build. The WarpBuild BYOC connection and
runner configurations are the source of truth for labels, sizes, and Azure
placement; public docs pages can lag the live configuration.

One-time setup (WarpBuild) Copy Chapter

The warpbuildbot GitHub app is installed org-wide on browseros-ai
(since 2026-06-11). Two more things must be true before any warp-* job
leaves queued:

1. The org must allow self-hosted runners on public repos. WarpBuild
   runners register as org-level self-hosted runners, and GitHub blocks
   those on public repositories by default
   (https://www.warpbuild.com/docs/ci/public-repos). BrowserOS is public,
   so an org admin must check: Organization Settings → Actions → Runner
   groups → Default → "Allow public repositories". Via API (needs
   admin:org scope):

   bash Copy

   gh auth refresh -h github.com -s admin:org
   gh api orgs/browseros-ai/actions/runner-groups \
     --jq '.runner_groups[] | {id, name, allows_public_repositories}'
   gh api -X PATCH "orgs/browseros-ai/actions/runner-groups/<id>" \
     -F allows_public_repositories=true

   Before flipping the toggle, check what else lives in that group — it
   widens exposure for every runner in it:

   bash Copy

   gh api "orgs/browseros-ai/actions/runner-groups/<id>/runners" \
     --jq '.runners[] | {name, status, labels: [.labels[].name]}'

   Expect only ephemeral warp-* runners (usually none while idle). The
   signed-nightly Mac (browseros-builder) is registered at the repo
   level, so this org-group toggle does not change its exposure. If the
   group ever holds other persistent org-level runners, give WarpBuild a
   dedicated runner group instead of widening Default.

   Done for browseros-ai on 2026-06-13 — pickup verified live (a
   queued job was claimed within ~60 s of dispatch).

2. The Azure BYOC connection must be healthy: sign in at
   https://app.warpbuild.com/ and confirm the BrowserOS Azure subscription,
   stack browseros-ci-eastus in East US, and both custom runner
   configurations listed above. Also check Azure quota and regional capacity
   for their VM SKUs when provisioning fails.

Smoke test the platform whose runner configuration changed:

gh workflow run release-linux.yml -f products=browseros -f upload_to_r2=false
gh workflow run release-windows.yml \
  -f products=browserclaw \
  -f sign=false \
  -f upload_to_r2=false

Then watch its build job leave queued within ~5 minutes (gh run watch).
Only dispatch one when you intentionally want to spend Azure compute time.

Release lane flow Copy Chapter

release-linux.yml and release-windows.yml select products (browseros,
browserclaw, or all) and call
.github/workflows/build-browseros.yml with profile=release-ci. Full product
releases set resource-mode=published, pass the frozen dispatch SHA, and build
one product after its server and extension workflows publish their latest
resources. Standalone wrapper dispatches use the same published-resource path.
Linux is unsigned. Windows follows the caller's sign input.

Linux also accepts arch=x64|arm64|all (default x64). The product-by-architecture
matrix cross-compiles arm64 on the existing x64 runner. Its entries run serially
because both architectures merge one product/version's linux/release.json;
the queue watchdog succeeds on the first runner pickup rather than timing out
on intentionally queued siblings. Published resources support both targets;
source mode is limited to x64. A dual-architecture standalone build requires one
product and exact server_version, extension_version, and onboarding_version
inputs; full product releases supply those pins. See Linux arm64.

The reusable workflow performs the per-platform recipe:

1. actions/checkout.
2. On Windows, select
   $RUNNER_TEMP/browseros-global.gitconfig through GIT_CONFIG_GLOBAL,
   write depot_tools' required Git settings with PATH Git, and export the
   selection to every later step. This is deliberately after repository
   checkout but before any Chromium/depot_tools operation. Linux and macOS
   skip the step.
3. astral-sh/setup-uv, resolve the Chromium pin and paths, then restore the
   pinned chromium checkout from cache (see below).
4. browseros source ensure --reset --repair-cached-depot-tools —
   fetches only the missing exact tag, resets source and gclient-managed Git
   repositories, and syncs dependencies/hooks after destructive cleanup.
   Existing .gclient settings and full history are preserved. Only line-ending
   drift in cached depot_tools is repaired; substantive changes fail closed.
5. browseros source clean-outputs --all-products ... — removes known product
   output/checkpoint state and prunes retired resource families in the selected
   BrowserOS repository. This does not delete hook-managed toolchains.
6. Preparation failure stops before cache publication or product patching.
7. Save the cache (only when the restore missed, i.e. first run per pin).
8. In source mode, download and validate the prepared common-resource artifact.
   Set up Bun for the BrowserOS server or the native Rust target for the
   BrowserOS neo server.
9. Invoke uv run browseros build once with the selected profile, product,
   architecture, resource mode, Chromium path, signing/upload switches, and
   prepared directory. bos_build builds the native server, stages validated
   resources, compiles, packages, signs when requested, uploads browser
   deliverables, and writes the lane manifest.
10. Upload the lane manifest with 30-day retention in source mode and browser
    build artifacts with 14-day retention.

Source mode never downloads server, onboarding, or product-extension resources
from R2; the only downloaded build input is the prepared GitHub artifact.
Published mode deliberately retains the download_resources provider.

The release-ci profile is the release preset minus clean/git_setup
(steps 5-6 replace them). Why not run git_setup as-is: it does
git fetch --tags, which on the shallow CI clone would pull objects for all
~70k chromium tags; the script instead fetches exactly the pinned tag at depth
2. On Windows the mini_installer module builds the installer that the signing
step signs when sign=true.

Caching strategy Copy Chapter

Cache key: chromium-src--<arch>-v2-<CHROMIUM_VERSION>. Contents:
the whole gclient root (depot_tools, .gclient, post-sync src) captured
immediately after gclient sync, before patches and before any out/ dir
exists — pristine and deterministic. The pin changes rarely, so steady state
is one cold sync per chromium bump per platform.

Generation v2 was introduced after the Windows Git bootstrap standardized
core.autocrlf=false. It deliberately has no v1 fallback: those immutable
archives may contain a depot_tools worktree checked out under the previous
line-ending policy. The first v2 run per platform is therefore cold and
publishes a cache under the current policy.

• Linux / macOS — WarpCache (WarpBuilds/cache@v1): drop-in for
  actions/cache with no size cap (entries expire 7 days after last use).
  Restore-keys fall back to the previous pin's cache, then the script
  fast-forwards src with a single-tag fetch.
• Windows — R2 tarball (browseros source cache): WarpCache does not
  support Windows runners and actions/cache caps at 10 GB/repo. The tree
  is zstd-tarred (~25-30 GB) into ci-cache/chromium/ in the existing R2
  bucket using the same R2_* secrets the build already needs for
  download_resources. R2 has zero egress fees. Missing credentials or a
  cache miss degrade to a cold checkout, never a failure.

Expected timings (32-core linux/windows, M4 Pro mac):

The compile dominates either way; the cache removes the checkout cost and
network flakiness. Toolchains deleted by clean (~2-4 GB) are re-fetched by
hooks each run — accepted, matches the maintainer's local flow.

Linux and Windows compute and managed-disk costs accrue in the BrowserOS Azure
subscription; WarpBuild's managed-runner list prices do not apply. Use Azure
Cost Management for the actual BYOC cost and the WarpBuild account for any
separate platform or cache charges. Current signed macOS release and nightly
builds run on the self-hosted Mac Mini.

Azure BYOC does not support WarpBuild snapshot runners. Keep checkout
acceleration on WarpCache for Linux and the R2 tarball for Windows; do not add
snapshot.key runner syntax or WarpBuilds/snapshot-save to these lanes.

Future optimizations (not yet wired) Copy Section

• Compiler cache (sccache/ccache via cc_wrapper) in a CI gn flags
  variant: release rebuilds often differ only slightly, so this is the lever
  that could cut warm builds to well under an hour.

Operating release lanes Copy Chapter

# BrowserOS Linux build from intentionally published component resources.
gh workflow run release-linux.yml \
  -f products=browseros \
  -f upload_to_r2=false

# BrowserClaw unsigned Windows verification without R2 upload.
gh workflow run release-windows.yml \
  -f products=browserclaw \
  -f sign=false \
  -f upload_to_r2=false

# Full releases publish components before building the native matrices.
gh workflow run release-browseros.yml --ref main
gh workflow run release-browserclaw.yml --ref main

Manual wrapper dispatches and signed nightlies use published mode. Source mode
remains available through workflow_call for specialized prepared-source
builds. Retry a failed full-release lane with
gh run rerun <run-id> --failed so it retains the original source SHA and run
ID. Successful lanes from an earlier rerun attempt remain valid.

The first run per platform is the cache warm-up; expect cold timings. If a
pin bump lands, the next run is cold again for that version. To force a fresh
checkout, bump the v2 in the cache key (workflow) — for Windows also delete
the old object under ci-cache/chromium/ in R2.

Troubleshooting: depot_tools cannot read global Git config Copy Chapter

The Windows failure signature is
fatal: unable to read config file 'C:/Users/runneradmin/.gitconfig', followed
by depot_tools' recommended core settings, a stray 'failed' is not recognized message, and gclient exit 9009. This occurs after the runner has
started; it is not an Azure provisioning, cache, or clean failure.

The reusable workflow does not depend on the runner account's HOME, XDG, or
AppData mapping. Its Windows-only bootstrap selects a disposable file under
RUNNER_TEMP with GIT_CONFIG_GLOBAL, writes the four Chromium settings plus
depot-tools.allowGlobalGitConfig=true, and verifies each value before source
setup. It uses PATH Git intentionally because depot_tools may not exist on a
cold checkout. Later depot_tools git.bat and gclient.bat processes inherit
the same GIT_CONFIG_GLOBAL, so warm and cold checkouts share one explicit
configuration.

If this signature returns, inspect the "Configure Git for depot_tools" step and
confirm its five read-back checks passed and its GITHUB_ENV assignment names
the temporary file. Fix the workflow contract; do not modify the runner image
or create C:/Users/runneradmin/.gitconfig manually. WarpBuild runners are
ephemeral, and account-level repair would disappear with the VM while
reintroducing HOME-resolution ambiguity.

Troubleshooting: cached depot_tools appears all-dirty Copy Chapter

The Windows cache-policy migration failure occurs after R2 restore and the
Chromium clean step. gclient.bat starts, prints Updating depot_tools...,
then Git reports Your local changes to the following files would be overwritten by checkout for most depot_tools files, followed by Aborting
and Failed to update depot_tools. This is distinct from the missing-global-
config signature above and from Azure runner provisioning.

An archive written under core.autocrlf=true can restore CRLF working-tree
bytes whose index contains LF. Once the job selects core.autocrlf=false,
Git correctly sees those tracked files as modified. Chromium's later clean
module resets src, but depot_tools self-update happens before anything else
resets the depot_tools worktree.

The reusable workflow passes --repair-cached-depot-tools only on its
disposable source-provisioning calls. The provisioner validates the repository
and classifies its tracked diff. It resets and verifies the checkout only when
every change is line-ending-only. If it finds substantive tracked changes, it
fails with substantive tracked changes and preserves the files; this prevents
cache corruption from being silently masked. It likewise rejects non-default
index flags such as assume-unchanged or skip-worktree, because those flags can
hide real content from status and diff. The flag defaults off for local CLI
use, so developer-owned depot_tools edits are never reset implicitly. Untracked
files are preserved.

Cache generation v2 has no v1 fallback, so normal recovery is a cold sync
followed by a new archive under the current Git policy. If this signature
appears on a v2 hit, inspect the source-ensure log for either the normalization
message or the fail-closed error. Do not delete files in a persistent checkout
and do not broaden the repair to unconditional git reset --hard.

Troubleshooting: jobs stuck in `queued` Copy Chapter

A job no runner ever picked up shows runner_id: 0 and empty steps:

gh run view <run-id> --json jobs --jq '.jobs[] | {name, status}'
gh api repos/browseros-ai/BrowserOS/actions/jobs/<job-id> \
  --jq '{status, runner_id, runner_name, labels}'

Causes, in the order to check:

1. Runner group blocks public repos — see one-time setup above. This
   stalls all platforms at once.
2. Label does not match a live runner configuration — compare the job
   label with the two exact custom labels above in
   https://app.warpbuild.com/. An unsupported label queues forever;
   WarpBuild reports no error back to GitHub.
3. Azure BYOC stack — confirm the connection and stack are healthy, then
   open the BYOC stack's launch errors and inspect LaunchInstances. An Azure
   400 that reports an image/VM-size generation mismatch means the image and
   selected VM family support different Hypervisor Generations; choose a
   Gen1-compatible size for the current Windows image. An Azure 409
   SkuNotAvailable is different: the requested SKU has no capacity for that
   subscription, location, or zone. Check quota and regional capacity in the
   configured region, then choose a regionally available Gen1-compatible size.
   Standard_D32as_v4 is the verified-family fallback if D32as v5 is
   unavailable, but confirm its capacity in East US before switching.
4. WarpBuild incident — check their dashboard.

Mechanics worth knowing:

• GitHub discards self-hosted jobs queued for more than 24h, and each release
  platform workflow has a concurrency group (release-linux or
  release-windows) with cancel-in-progress: false. A queued build can
  therefore pin the platform lane for a full day. Linux's queue-watchdog
  exits after the first runner pickup; later matrix entries intentionally queue
  behind it. If no Linux job starts, the watchdog cancels at 20 minutes. The
  Windows watchdog steps in at the 20-minute mark: it cancels the run when no build job is
  actually running (everything stuck in queue or already finished), and fails
  loudly without cancelling while any build is in progress. In that mixed
  case, cancel the run manually once the live builds finish — a still-queued
  job otherwise pins the group for up to 24h with no watcher left.
• Do not rely on a configuration fix to repair the current release.
  Unsupported labels need a new workflow_job.queued webhook; Azure launch
  failures may be retried while a job is queued, but the lane's watchdog may
  already have failed. After correcting the configuration, cancel the stuck
  run and re-dispatch according to the release procedure.
• A job that IS picked up but dies in "Set up job" within seconds with
  Unable to resolve action <owner>/<name>@vN has nothing to do with
  WarpBuild: the floating major tag does not exist upstream (e.g.
  astral-sh/setup-uv publishes v8.x.y releases but no v8 tag). Pin an
  exact existing version.

Packages Browseros Bos Build Docs Windows Install Verification (`packages/browseros/bos_build/docs/windows-install-verification.md`) Copy Section

Windows Install Verification Checklist

Use a Windows machine or VM with a clean user profile when verifying a fresh
install. BrowserOS installs per-user; the Apps & Features entry is under:

HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall

Fresh Install Copy Chapter

• Download the Windows installer artifact and double-click it.
• A progress window appears with the title/text Installing BrowserOS….
• The installer window closes when installation completes.
• BrowserOS launches automatically after the fresh install.
• Apps & Features shows BrowserOS.
• Apps & Features shows publisher BrowserOS Software Inc.
• Apps & Features shows the BrowserOS icon.
• Apps & Features shows the expected version.
• A Start Menu shortcut exists and launches BrowserOS.
• A desktop shortcut exists and launches BrowserOS.

Update Path Copy Chapter

• Install an older BrowserOS version.
• Open chrome://settings/help and let WinSparkle find the newer update.
• Start the update from the WinSparkle flow.
• No installer progress window appears during the update.
• BrowserOS does not auto-launch as part of the update install.
• Relaunch BrowserOS after the update completes.
• chrome://settings/help shows the new expected version.
• WinSparkle.dll exists in
  %LOCALAPPDATA%\BrowserOS\Application\<version>\.

Silent Fresh Install Copy Chapter

• Run the installer with --silent from Command Prompt or PowerShell.
• No installer UI appears.
• BrowserOS is installed successfully.
• BrowserOS does not auto-launch during the silent install.

Portable Zip Copy Chapter

• Download the portable zip artifact.
• Extract the zip.
• The extracted contents include the Windows installer executable.

Packages Browseros Bos Build Docs Windows Sdk Setup (`packages/browseros/bos_build/docs/windows-sdk-setup.md`) Copy Section

Windows SDK setup

Windows release/debug plans run windows_sdk after source preparation and before product resources and patches. It also runs for prepared CI checkouts (--provision none). Planning with --show-plan does not inspect source or install anything.

The selected Chromium tag supplies both SDK directory pins (build/vs_toolchain.py and build/toolchain/win/setup_toolchain.py) and the package requirement (docs/windows_build_instructions.md). For example, SDK package 10.0.28000.2270 installs into directory 10.0.28000.0. An older source checkout or conflicting requirements fail before installation.

To check an already prepared checkout without building:

uv run --project packages/browseros browseros build --modules windows_sdk `
  --chromium-src C:/chromium/src --arch x64 --build-type release

Local builds only check. When prerequisites are missing, install the package requested by the pinned Chromium documentation from Microsoft's SDK downloads, selecting Desktop C++ x86/x64 and Debugging Tools for Windows, then rerun. ARM64 builds additionally need their existing target libraries and debugging tools; automatic installation is currently scoped to the x64 CI lane.

The reusable Windows build explicitly sets BROWSEROS_INSTALL_WINDOWS_SDK=1. Installation additionally requires GITHUB_ACTIONS=true and an already elevated process. The module never opens a UAC prompt or requests a restart. It resolves the exact package from Microsoft's supported downloads table and validates its Microsoft Authenticode signature before launching the quiet installer. Installation is machine-wide; WINDOWSSDKDIR, when set, selects the same root used by Chromium.

Every invocation verifies nonempty headers, libraries, resource/manifest/IDL tools, and debugging DLLs, plus machine registration at or above the required servicing version in the same SDK family. It then runs the pinned Chromium vs_toolchain.py get_toolchain_dir and setup_toolchain.py for x86/x64 (and ARM64 when requested). The environment-block argument is none, so these checks generate no environment files, GN files, or Ninja files.

An installer failure leaves logs in the printed browseros-windows-sdk-* directory under RUNNER_TEMP on managed CI. The reusable workflow uploads those logs as windows-sdk-logs--<arch> even if the build fails, retaining them for 14 days. Only the transient “another installation is running” result is automatically retried, up to three attempts. Other failures stop the build and can be retried after fixing the reported cause; there is no completion marker that could conceal a partial installation. A successful installer result still requires the file and Chromium environment checks to pass. A reboot-required result is reported, then accepted only if those checks succeed immediately.

Microsoft's runner image installation script documents the SDK feature selection and quiet/no-restart pattern; Windows Installer error codes describe the busy and reboot results. A passing SDK check establishes SDK environment readiness, not a complete Chromium build or release.

--- METRICS ---

• Files Extracted: 50
• Estimated Token Budget: ~66733 tokens
• Canonical Reference: https://codewiki.google/github.com/browseros-ai/BrowserOS