### Why Kimi K2.5? 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 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](https://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** The base URL for the Kimi API (`https://api.moonshot.ai/v1`) is pre-filled automatically when you select the Moonshot AI provider template. --- ## Cloud Providers Connect to powerful AI models using your API keys. Your keys stay on your machine — requests go directly to the provider.

Gemini Flash is fast and free. Google gives you 20 requests per minute at no cost. **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**

Claude Opus 4.5 gives the best results for Agent Mode. **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**

GPT-5 is OpenAI's most capable model for both chat and agent tasks. **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**

Access 500+ models through one API. **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**

Use OpenAI models hosted on your own Azure subscription for enterprise compliance and data residency. **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**

Access Claude, Llama, and other models through your AWS account with IAM-based authentication. **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**

Connect to any provider that implements the OpenAI-compatible API format (e.g., Together AI, Fireworks, Groq, Perplexity). **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** Most newer AI providers support the OpenAI-compatible API format. Check your provider's docs for the base URL and available model IDs. --- ## Local Models Run AI completely offline with Ollama or LM Studio. Includes recommended models, context length setup, and configuration steps. --- ## Switching Between Models Use the model switcher in the Assistant panel to change providers anytime. The default provider is highlighted. Use local models for sensitive work data. Switch to Claude for agent tasks that need complex reasoning. --- ### Browseros Features Chatgpt Pro Oauth (`docs/browseros/features/chatgpt-pro-oauth.mdx`) --- title: "ChatGPT Pro / Plus" description: "Use your ChatGPT subscription to power BrowserOS" --- 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 **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 | Model | Context Window | |-------|---------------| | `gpt-5.5` | 1.05M | | `gpt-5.4` | 400K | | `gpt-5.4-mini` | 400K | | `gpt-5.4-nano` | 400K | | `gpt-5.3-codex` | 400K | | `gpt-5.3-codex-spark` | 128K | | `gpt-5.2-codex` | 400K | | `gpt-5.2` | 200K | | `gpt-5.1-codex` | 400K | | `gpt-5.1-codex-max` | 400K | | `gpt-5.1-codex-mini` | 400K | | `gpt-5.1` | 200K | 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. The Codex models (e.g., `gpt-5.3-codex`) are optimized for code and reasoning tasks — ideal for complex browser automation workflows that involve form filling, data extraction, and multi-step navigation. ## Reasoning Settings 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 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`) --- title: "Connect Apps" description: "Connect 40+ apps to BrowserOS so the assistant can work with your email, calendar, projects, and more" --- 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.

## How It Works BrowserOS uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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 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. Ask the assistant something like "What's on my calendar today?" or "Send an email to Sarah." The assistant detects the app is not connected and shows a card explaining why connecting it would help. You get two choices: **Connect** or **Do it manually**. - **Connect**: Opens a sign-in page. Authorize the app and the assistant continues with full integration access. - **Do it manually**: The assistant skips the integration and navigates to the app's website directly using browser automation. Once connected, the app stays linked for all future conversations. If you chose to skip, the assistant remembers and will not ask again. {/* Smart app connection prompt in chat

*/} See [Smart Nudges](/browseros/features/smart-nudges#app-connection) 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 Click **Connect Apps** in the sidebar. Click **Add built-in app** and select the app you want Complete the OAuth sign-in when prompted Connected Apps settings page

## 40+ Supported Apps BrowserOS connects to over 40 apps across every category you need. | App | What you can do | |-----|----------------| | **Gmail** | Send, read, and search emails, manage drafts and labels | | **Outlook Mail** | Send, read, and manage emails | | **Resend** | Send transactional and marketing emails | | App | What you can do | |-----|----------------| | **Google Calendar** | Create events, find free time, manage calendars | | **Outlook Calendar** | Schedule meetings, manage events | | **Cal.com** | Schedule meetings, manage availability | | App | What you can do | |-----|----------------| | **Slack** | Post messages, manage channels | | **Discord** | Send messages, manage servers | | **WhatsApp** | Send messages, manage conversations | | **Microsoft Teams** | Chat, meet, and collaborate | | App | What you can do | |-----|----------------| | **GitHub** | Manage repos, issues, and pull requests | | **GitLab** | Manage repos, issues, and merge requests | | **Vercel** | Deploy and manage web applications | | **Postman** | Test and manage APIs | | **Cloudflare** | Manage domains, DNS, and security | | **Supabase** | Manage databases and backend services | | App | What you can do | |-----|----------------| | **Linear** | Create issues, manage cycles and projects | | **Jira** | Create issues, manage sprints | | **Asana** | Organize and track team projects | | **Monday** | Manage work and team collaboration | | **ClickUp** | Manage tasks, projects, and workflows | | App | What you can do | |-----|----------------| | **Notion** | Create pages, manage databases | | **Google Docs** | Create and edit documents | | **Google Sheets** | Create and edit spreadsheets | | **Google Drive** | Upload, download, and manage files | | **Google Forms** | Create and manage forms and surveys | | **Confluence** | Create and manage documentation | | **Airtable** | Manage bases, tables, and records | | App | What you can do | |-----|----------------| | **Dropbox** | Store and share files | | **OneDrive** | Store and sync files with Microsoft | | **Box** | Manage and share enterprise files | | App | What you can do | |-----|----------------| | **Figma** | Access and manage design files | | **Canva** | Create and manage designs | | App | What you can do | |-----|----------------| | **Salesforce** | Manage leads, contacts, and opportunities | | **HubSpot** | Manage contacts, deals, and marketing | | App | What you can do | |-----|----------------| | **Shopify** | Manage products, orders, and store | | **Stripe** | Manage payments and subscriptions | | App | What you can do | |-----|----------------| | **PostHog** | Query analytics, manage feature flags | | **Mixpanel** | Analyze user behavior and metrics | | App | What you can do | |-----|----------------| | **Zendesk** | Manage support tickets and customers | | **Intercom** | Manage customer messaging and support | | App | What you can do | |-----|----------------| | **Brave Search** | Search the web privately | | **Exa** | AI-powered semantic web search | | **Mem0** | Store and retrieve AI memory | | App | What you can do | |-----|----------------| | **LinkedIn** | Post updates, manage connections | | **YouTube** | Access video info and transcripts | | **WordPress** | Manage websites and blog content | ## Example Prompts The assistant figures out which apps to use based on what you ask. Just describe what you want in plain language. - What's on my calendar today? - Schedule a meeting with Sarah tomorrow at 2pm - When is my next meeting with the marketing team? - Block off Friday afternoon for focus time - Show me unread emails from my manager - Draft a reply to the last email from John thanking him for the update - Find emails about the Q4 budget from last week - Send an email to the team with the meeting notes - Post a message to #general saying I'll be out tomorrow - What's the latest message in #engineering? - Send a DM to Sarah asking if she's free for lunch - Summarize what was discussed in #product today - Create a new Linear issue for the homepage redesign - What are my open tasks in Jira? - Move the "Launch campaign" task to complete in Asana - Add a comment to the latest ClickUp task - Add "Review Q4 report" to my Notion tasks database - Create a new page in my Projects database for the website redesign - What are my open tasks in Notion? - Update the status of the "Launch campaign" task to complete ## Cross-App Workflows 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. "Find action items in my latest emails and add them to my Notion tasks" "Check my calendar for tomorrow, then draft an email to John summarizing what we're meeting about" "Test the checkout flow on our staging site, file a Linear issue if anything is broken, and post a summary to #engineering on Slack" "Pull my open deals from Salesforce and create a summary spreadsheet in Google Sheets" "Check the latest pull requests on our main repo and post a daily summary to #dev-updates on Slack" "Find all receipts in my Gmail from this month and organize them in a Google Sheet" ## Add a Custom MCP Server 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. MCP has a growing ecosystem of servers. Browse [MCP servers on GitHub](https://github.com/modelcontextprotocol/servers) to find integrations for databases, APIs, and more. ### Connect to OAuth-Protected Remote Servers Some remote MCP servers (like Atlassian Jira, GitHub, etc.) require OAuth authentication. Use [mcp-remote](https://www.npmjs.com/package/mcp-remote) and [supergateway](https://github.com/supercorp-ai/supergateway) to handle the OAuth flow locally: ```bash 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. Keep the terminal running while you use BrowserOS. The local server handles authentication and proxies requests to the remote MCP server. ```bash npx -y supergateway --stdio "npx -y mcp-remote https://mcp.atlassian.com/v1/sse" --port 8000 ``` Then add `http://localhost:8000/sse` as a custom MCP. ```bash npx -y supergateway --stdio "npx -y mcp-remote https://api.githubcopilot.com/mcp/sse" --port 8001 ``` Then add `http://localhost:8001/sse` as a custom MCP. ## Privacy and Security All apps use OAuth sign-in. BrowserOS never sees or stores your passwords. Apps are only accessed when you ask. Nothing runs in the background. Connect or disconnect any app at any time from Settings. Your authentication tokens are managed securely and stored locally on your machine. --- ### Browseros Features Cowork (`docs/browseros/features/cowork.mdx`) --- title: "Cowork" description: "Give the agent controlled access to local files and commands alongside browser automation" --- 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:

## Why Cowork? 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: Read documents and data files, write reports, markdown, HTML, and other outputs Make targeted edits to existing files with surgical string replacement Execute shell commands within the sandboxed folder Search file contents with regex or literal patterns across your project Find files by glob pattern, with smart filtering of build directories List directory contents with file sizes, sorted and organized 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 Click the **Cowork** dropdown next to the prompt input Select a recent folder or click **Choose a different folder** Allow BrowserOS to access that folder when prompted Select a folder for the agent to operate in

Select a folder for the agent to operate in

The agent is sandboxed to your selected folder. It cannot access files outside of it. Cowork is available in **Agent Mode** only. In Chat Mode, the agent works with browser tabs only. To disable file access, select **No folder** and the agent will work with browser tabs only. ## Filesystem Tools Cowork provides 7 filesystem tools that the agent can use alongside browser automation: Read a file from the filesystem. Returns text content with line numbers, or image data for image files (PNG, JPG, GIF, WEBP, BMP, SVG, ICO). Supports pagination through large files with `offset` and `limit` parameters. | 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. Create or overwrite a file. Automatically creates parent directories if they don't exist. | Parameter | Type | Description | |-----------|------|-------------| | `path` | string (required) | File path relative to working directory | | `content` | string (required) | Complete file content to write | Make a targeted edit by replacing an exact string match. If the exact match fails, a whitespace-tolerant fuzzy match is attempted. Preserves original line endings (CRLF, CR, LF) and BOM. | 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. Execute a shell command and return its output. Commands run in `sh`/`bash` on Unix or `cmd` on Windows. | 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. Find files matching a glob pattern. Searches recursively while skipping common build directories (`node_modules`, `.git`, `dist`, `build`, `.next`, `coverage`, `__pycache__`, and more). | 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. Search file contents using regex or literal string matching. Skips binary files and files over 2MB. | 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) | List directory contents. Shows directories first (with trailing `/`), then files with human-readable sizes. | 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 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: Opens the site and identifies top stories Clicks into each story and reads discussion threads Creates an HTML report summarizing the findings Writes the report to your selected folder Agent researching Hacker News and generating an HTML report

Agent researching Hacker News and generating an HTML report

## Example Use Cases > Go through my Downloads folder and organize files by type: documents, images, videos, archives. > Research key trends about [topic] on Reddit, Twitter, and LinkedIn. Create an HTML report with your findings. > Visit these 10 product pages, extract the name, price, and description, and save the results as a markdown file. > Find the top posts from these 5 subreddits today and compile them into a daily digest document. > Search my project for all TODO comments, list them with file paths and line numbers, then create a summary markdown file. > Grep through the log files in this folder for errors from the last 24 hours and write a summary of what went wrong. ## Security The agent can only access the folder you select. No parent directories, no path traversal. Select **No folder** to instantly disable file access All file operations happen locally on your machine --- ### Browseros Features Github Copilot Oauth (`docs/browseros/features/github-copilot-oauth.mdx`) --- title: "GitHub Copilot" description: "Use your GitHub Copilot subscription to power BrowserOS" --- 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 **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 ### Free Tier | Model | Context Window | |-------|---------------| | `gpt-5-mini` | 128K | | `claude-haiku-4.5` | 128K | | `gpt-4o` | 64K | | `gpt-4.1` | 64K | ### Copilot Pro / Pro+ | Model | Context Window | |-------|---------------| | `claude-sonnet-4.6` | 200K | | `claude-opus-4.6` | 200K | | `gemini-2.5-pro` | 1M | | `gemini-3-pro-preview` | 1M | | `gpt-5.4` | 400K | | `gpt-5.3-codex` | 400K | | `gpt-5.2-codex` | 400K | | `grok-code-fast-1` | 128K | GitHub Copilot is the most versatile provider — one subscription gives you access to models from OpenAI, Anthropic, Google, and xAI. Great if you want to switch between models for different tasks. ## Disconnecting 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`) --- title: "Bring Your Local Model" description: "Run AI models locally with Ollama or LM Studio for free, private, offline use" --- BrowserOS works great with local models for Chat Mode. Run models completely offline — your data never leaves your machine. ## Context Length **Ollama defaults to 4,096 tokens of context — this is too low for BrowserOS.** Below 15K tokens, the context overflows and the agent gets stuck in a loop constantly trying to recover. Only Chat Mode will work at low context lengths. Set at least **15,000–20,000 tokens** for local models to function properly. Set context length when starting Ollama: ```bash 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](https://docs.ollama.com/context-length) for more details. --- ## Setup The easiest way to run models locally. Download from [ollama.com](https://ollama.com) and install it. ```bash ollama pull qwen/qwen3-4b ``` ```bash OLLAMA_CONTEXT_LENGTH=20000 ollama serve ``` 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** Nice GUI if you don't want to use the terminal. Download from [lmstudio.ai](https://lmstudio.ai) and install it. Open LM Studio → **Developer** tab → load a model. It runs a server at `http://localhost:1234/v1/`. 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** --- ## Recommended Models Pick a model based on your available RAM/VRAM. Smaller models are faster but less capable. ### Lightweight (under 5 GB) Good for machines with 8 GB RAM. Fast responses, suitable for simple chat tasks. | Model | Publisher | Params | Quant | Size | |-------|-----------|--------|-------|------| | `qwen/qwen3-4b` | Qwen | 4B | 4bit | 2.28 GB | | `mistralai/ministral-3-3b` | Mistral | 3B | Q4_K_M | 2.99 GB | | `deepseek-r1-distill-qwen-7b` | lmstudio-community | 7B | Q4_K_M | 4.68 GB | | `deepseek-r1-distill-llama-8b` | lmstudio-community | 8B | Q4_K_M | 4.92 GB | ### Mid-range (10–15 GB) Needs 16+ GB RAM. Better reasoning, handles longer conversations well. | Model | Publisher | Params | Quant | Size | |-------|-----------|--------|-------|------| | `openai/gpt-oss-20b` | OpenAI | 20B | MXFP4 | 12.11 GB | | `mistralai/magistral-small` | Mistral | 23.6B | 4bit | 13.28 GB | | `mistralai/devstral-small-2-2512` | Mistral | 24B | 4bit | 14.12 GB | ### Heavy (60+ GB) For workstations with 64+ GB RAM. Closest to cloud model quality. | Model | Publisher | Params | Quant | Size | |-------|-----------|--------|-------|------| | `openai/gpt-oss-120b` | OpenAI | 120B | MXFP4 | 63.39 GB | Start with `qwen/qwen3-4b` if you're unsure — it's small, fast, and surprisingly capable for its size. --- ### Browseros Features Scheduled Tasks (`docs/browseros/features/scheduled-tasks.mdx`) --- title: "Scheduled Tasks" description: "Run the BrowserOS agent automatically on a schedule" --- 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:

## Creating a Scheduled Task There are two ways to create a scheduled task: from a conversation or from the settings page. ### From a conversation 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](/browseros/features/smart-nudges#schedule-suggestion) for more details. ### From settings Click **Scheduled Tasks** in the sidebar. Click the **New Task** button to open the creation dialog. - **Name**: A friendly name for your task - **Prompt**: What you want the agent to do (any natural language instruction) - **Schedule type**: Daily at a specific time, every N hours, or every N minutes - **Enable**: Toggle on to start running immediately Click **Create**. The task will run at the next scheduled time automatically. Create scheduled task dialog

## Schedule Types Runs once a day at a specific time you choose (e.g., every morning at 8:00 AM). Runs every N hours (e.g., every 2 hours, every 6 hours). Set an interval from 1 to 24 hours. Runs every N minutes (e.g., every 15 minutes, every 30 minutes). Set an interval from 1 to 60 minutes. ## Example Use Cases > Every morning at 8am, check my Google Calendar and send me a summary of today's events. For each meeting, do a quick Google search on the attendees and include their LinkedIn summary. > Every day, go to LinkedIn and accept up to 25 pending connection requests. > Check the price of this Amazon item every hour. If it drops below $50, place the order. > Every morning at 9am, visit these 5 competitor websites and check for new product announcements or pricing changes. Summarize what is new. > Every evening at 6pm, check the top posts on Hacker News and r/programming. Create a brief summary of the most interesting discussions. > Check my Google Calendar for tomorrow's meetings, then post a summary to my Slack channel, and create a Notion page with prep notes for each meeting. Your scheduled task prompts can be as complex as you want. If you have [connected apps](/browseros/features/connect-mcps) like Google Calendar, Slack, Notion, or Gmail, your scheduled tasks can work across all of them. ## Viewing Results 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 Scheduled task results

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. Scheduled task output showing a daily news briefing

Scheduled task output showing a daily news briefing

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 BrowserOS uses your browser's built-in alarm system to trigger tasks at the right time. If your laptop was closed at the scheduled time, the task runs as soon as you open BrowserOS again. A hidden browser window opens automatically. The task runs there so it never interrupts whatever you are working on. You will not see anything happen on screen. The agent runs your prompt with full access to browser automation and any connected apps. It can navigate pages, fill forms, extract data, and interact with your services. When the task finishes, the result is saved and appears on your New Tab page and in the task's run history. The hidden window closes automatically. BrowserOS needs to be open for scheduled tasks to run. Tasks have a 10-minute timeout. If a task takes longer than that, it will be marked as failed and you can retry it. ## Cloud Sync 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](/browseros/features/sync-to-cloud) for more details. ## Privacy All tasks run on your machine in a hidden browser window. Nothing is sent to external servers. Enable, disable, edit, or delete any task at any time. You decide what runs and when. --- ### Browseros Features Smart Nudges (`docs/browseros/features/smart-nudges.mdx`) --- title: "Smart Nudges" description: "BrowserOS suggests app connections and task scheduling at the right moment" --- 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 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. For example: "Send Sarah an email with the meeting notes." Gmail is not connected yet, so the agent cannot send emails through the integration. The card explains why connecting the app would help and gives you two choices: **Connect** or **Do it manually**. - **Connect**: Opens a sign-in page for the app. Once you authorize, the agent continues with full integration access. - **Do it manually**: The agent skips the integration and uses browser automation instead (navigates to the website directly). ### What happens after you choose The app is added to your connected list. The agent uses the integration for this and all future conversations. You can manage connected apps in [Connect Apps](/browseros/features/connect-mcps). The agent remembers your choice and will not ask about this app again. It uses browser automation to complete the task instead. If you declined an app but change your mind later, you can connect it anytime from the [Connect Apps](/browseros/features/connect-mcps) settings page. ### Supported apps 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](/browseros/features/connect-mcps) for the full list. ## Schedule Suggestion 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. For example: "Here are the top 5 tech headlines from today." News gathering, price monitoring, report building, data tracking, and similar tasks that do not need your real-time input are good candidates. The card suggests a name and schedule. For example: "Run this automatically? 'Morning News Briefing' - daily at 09:00." - **Schedule this task**: Opens the Scheduled Tasks page with the details pre-filled. Review and confirm to create the task. - **Maybe later**: Dismisses the card. You can always create the scheduled task manually later. ### You can also ask directly You do not have to wait for the agent to suggest it. Just tell the agent you want to schedule the task: - "Schedule this to run every morning" - "Can this run daily at 8am?" - "Automate this task" - "Run this every hour" The agent will infer the task name, schedule type, and timing from your conversation and show the scheduling card immediately. ### What gets scheduled The scheduling card pre-fills the [Scheduled Tasks](/browseros/features/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 Nudges are designed to appear at the right moment without interrupting your workflow: | Nudge | When it appears | How often | |---|---|---| | App Connection | Before the agent starts working, when it detects an unconnected app | Once per app per conversation | | Schedule Suggestion | After the agent finishes a task that could be automated | Once per conversation | Nudges do not appear in: - **Scheduled tasks** running in the background - **Chat mode** (read-only, no browser automation) ## Privacy The agent only suggests a connection. No data is shared with the app until you explicitly authorize it. Declined apps are stored on your device. The agent will not ask about them again unless you reconnect from settings. --- ### Browseros Features Sync To Cloud (`docs/browseros/features/sync-to-cloud.mdx`) --- title: "Sync to Cloud" description: "Sign in to sync your conversations, settings, and automations across all your devices" --- 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? Without an account, everything stays on one device. Sign in and your data is backed up and available wherever you use BrowserOS. Open BrowserOS on a new device and your conversations, model settings, and scheduled tasks are already there. Chat history is saved to the cloud automatically. Clear your browser data or switch machines and everything is still available. Set up your AI models once. Your provider configurations sync across devices so you never re-enter the same setup twice. Create a scheduled task on your laptop and it appears on your desktop. Edits sync both ways. ## How to Sign In Open a new tab in BrowserOS to see the home page. Click **Sign In** in the sidebar to open the login page. Enter your email for a magic link, or sign in with Google. Click the link in your email (or complete Google sign-in). BrowserOS starts syncing your data immediately. Magic link sign-in means you never need to create or remember a password. Just enter your email and click the link. ## What Gets Synced Your full chat history syncs to the cloud as you go. Every message is saved in real time so you can pick up any conversation on another device. Locally, BrowserOS keeps your 50 most recent conversations. In the cloud, there is no limit. Your configured LLM providers (OpenAI, Anthropic, Google, Moonshot, Azure, Bedrock, and others) sync across devices. This includes the model name, provider type, base URL, temperature, and context window settings. **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. Your scheduled task configurations sync in both directions. Create a task on one device, edit it on another, and changes are merged automatically using timestamps to resolve conflicts. Only the schedule setup syncs (name, prompt, schedule type, and timing). Task run results and output stay on the device where the task ran. Your name, profile picture, and account preferences sync across devices. Information you provide during onboarding (role, company) is also saved to your profile. ## What Stays Local 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 BrowserOS uses a local-first approach. Your data is always saved on your device first, then synced to the cloud in the background. Every action (sending a message, adding a provider, creating a task) is saved locally first. BrowserOS works fully offline. When you are signed in, changes are automatically pushed to the cloud. New chat messages sync in real time. Provider and task changes sync whenever they are updated. When you sign in on a new device, BrowserOS pulls your conversations, model settings, scheduled tasks, and profile from the cloud and merges them with any local data. If the same scheduled task is edited on two devices before they sync, BrowserOS keeps the version with the most recent timestamp. ## Security Sensitive credentials like API keys, access keys, and tokens are excluded from cloud sync entirely. Sign-in uses magic links or Google OAuth. No passwords are stored. All synced data is tied to your user account and is not accessible to anyone else. If cloud sync fails (e.g., no internet), your local data is unaffected. Sync resumes automatically when connectivity is restored. --- ### Browseros Features Use With Claude Code (`docs/browseros/features/use-with-claude-code.mdx`) --- title: "MCP Clients (Claude Code, OpenClaw)" description: "Control your browser and 40+ apps from Claude Code, OpenClaw, Gemini CLI, or any MCP client" --- 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. Unlike Chrome DevTools MCP which requires setting up debug profiles and running separate servers, BrowserOS MCP works out of the box. Just copy the URL from settings and connect. ## Why Use BrowserOS with Claude Code? Claude tests your web app, reads console errors, and fixes the code — all in one loop. Gmail, Slack, GitHub, Jira, Notion, Google Sheets, and more — accessible directly from your AI agent. Extract your LinkedIn profile, tweets, or any authenticated page content. Fill forms, navigate multi-step workflows, and automate repetitive browser tasks. Full browser control: tabs, navigation, clicks, typing, screenshots, bookmarks, history, tab groups, and window management. Connect external services via OAuth — credentials are managed securely, never stored in BrowserOS. Wondering how BrowserOS MCP compares to Chrome DevTools MCP or other browser automation tools? See our [detailed feature comparison](/browseros/comparisons/chrome-devtools-mcp) covering 53 browser tools, 40+ app integrations, and why BrowserOS MCP gives developers more out of the box. ## Getting Started Navigate to `chrome://browseros/mcp` or click **Settings** → **BrowserOS as MCP** in the sidebar. Copy the Server URL shown on the page (e.g., `http://127.0.0.1:9239/mcp`). BrowserOS MCP settings page showing Server URL

BrowserOS MCP settings page showing Server URL

Use the tabs below to connect your preferred client. Add BrowserOS to Claude Code: ```bash claude mcp add --transport http browseros --scope user # Example: claude mcp add --transport http browseros http://127.0.0.1:9239/mcp --scope user ``` Start Claude Code and try it: ```bash claude > Open amazon.com in BrowserOS ``` Run `claude --dangerously-skip-permissions` to skip confirmation prompts for each browser action. To remove later: ```bash claude mcp remove browseros --scope user ``` Add BrowserOS to Gemini CLI: ```bash gemini mcp add local-server --transport http --scope user # Example: gemini mcp add local-server http://127.0.0.1:9239/mcp --transport http --scope user ``` Add BrowserOS to OpenAI Codex CLI: ```bash codex mcp add browseros --transport http # Example: codex mcp add browseros http://127.0.0.1:9239/mcp --transport http ``` Add BrowserOS to [OpenClaw](https://openclaw.ai/) by adding it to the `mcpServers` section in your `openclaw.json` config file: ```json { "mcpServers": { "browseros": { "url": "http://127.0.0.1:9239/mcp" } } } ``` Replace the URL with your BrowserOS MCP URL from settings. Open your Claude Desktop config file: ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` Add BrowserOS: ```json { "mcpServers": { "browseros": { "command": "npx", "args": ["mcp-remote", "http://127.0.0.1:9239/mcp"] } } } ``` 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 `. Restart Claude Desktop to connect. ## Connect from a Remote Machine 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](https://github.com/NousResearch) 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. Anyone who can reach this URL has full control of your browser, including every account you are signed into. Prefer a private tunnel like Tailscale over a public URL, and treat public tunnel URLs like passwords. All commands below use port `9239` — replace it with the port shown on your `chrome://browseros/mcp` settings page. Tailscale puts your laptop and VPS on a private network, so the MCP server is never exposed to the public internet and the URL never changes. 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. On the laptop, start a quick tunnel: ```bash cloudflared tunnel --url http://127.0.0.1:9239 ``` Cloudflare prints a URL like `https://random-words.trycloudflare.com`. On the VPS, connect your agent to `https://random-words.trycloudflare.com/mcp`. 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. On the laptop, start a tunnel: ```bash ngrok http 9239 ``` ngrok prints a URL like `https://abc123.ngrok-free.app`. On the VPS, connect your agent to `https://abc123.ngrok-free.app/mcp`. 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. The connection only works while your laptop is awake, BrowserOS is running, and the tunnel process is alive. If a remote agent that was working suddenly stops connecting, check those three first — and if you use ngrok or a Cloudflare quick tunnel, remember the URL rotates on every restart, so your agent may be pointing at a dead URL. Tailscale avoids this because its hostnames are stable. ## Example Prompts Extract structured data from any page you're logged into — no scraping setup needed. ``` Open my LinkedIn profile in BrowserOS and extract my work experience as JSON ``` Test your web app end-to-end without leaving the terminal — Claude navigates, interacts, and reports errors back. ``` In BrowserOS, go to localhost:3000, click the login button, and check for console errors ``` Capture visual snapshots of any page for debugging, documentation, or design review. ``` Take a screenshot of the current page in BrowserOS and save it to screenshots/ ``` Search through your real browsing history to find pages you visited earlier. ``` Search my BrowserOS history for "invoice" and list the recent matches ``` Access your email directly from the agent — read, search, and summarize without switching windows. ``` Read my latest Gmail messages and summarize them ``` Chain multiple services together in a single prompt — file issues, notify your team, and stay in flow. ``` Create a Linear issue for the bug I just found and post a summary to Slack ``` --- ## Browser Automation Tools BrowserOS exposes **53 browser automation tools** to MCP clients, organized into the following categories: | Tool | Description | |------|-------------| | `get_active_page` | Get the currently focused page/tab | | `list_pages` | List all open pages with title, URL, and tab ID | | `navigate_page` | Navigate to a URL, or go back/forward/reload | | `new_page` | Open a new tab (with optional background/hidden mode) | | `new_hidden_page` | Open a hidden tab for background automation | | `show_page` | Restore a hidden page to visible state | | `move_page` | Move a tab to a different window or position | | `close_page` | Close a tab | | Tool | Description | |------|-------------| | `take_snapshot` | Get accessibility tree with interactive element IDs | | `take_enhanced_snapshot` | Detailed accessibility tree with structural context | | `get_page_content` | Extract page as clean Markdown (headers, links, tables) | | `get_page_links` | Extract all links from a page with deduplication | | `get_dom` | Get raw HTML DOM with optional CSS selector scoping | | `search_dom` | Search DOM by text, CSS selector, or XPath | | `take_screenshot` | Capture page screenshot (PNG/JPEG/WebP, full-page option) | | `evaluate_script` | Execute JavaScript in the page context | | Tool | Description | |------|-------------| | `click` | Click an element by ID from snapshot | | `click_at` | Click at specific X,Y coordinates | | `hover` | Hover over an element | | `focus` | Focus an element (scrolls into view) | | `fill` | Type text into an input (with optional clear) | | `clear` | Clear text from input/textarea | | `check` | Check a checkbox or radio button | | `uncheck` | Uncheck a checkbox | | `select_option` | Select a dropdown option by value or text | | `press_key` | Press a key or key combination (Enter, Ctrl+A, etc.) | | `drag` | Drag an element to another element or coordinates | | `scroll` | Scroll page or element (up/down/left/right) | | `upload_file` | Upload files to a file input element | | `handle_dialog` | Accept or dismiss JavaScript dialogs | | Tool | Description | |------|-------------| | `save_pdf` | Print current page to a PDF file | | `save_screenshot` | Capture and save a screenshot to disk | | `download_file` | Click an element to trigger a download and save it | | Tool | Description | |------|-------------| | `list_windows` | List all browser windows | | `create_window` | Create a new browser window | | `create_hidden_window` | Create a hidden window for background tasks | | `close_window` | Close a window by ID | | `activate_window` | Focus and activate a window | | Tool | Description | |------|-------------| | `list_tab_groups` | List all tab groups | | `group_tabs` | Create a tab group with optional title and color | | `update_tab_group` | Update group title, color, or collapsed state | | `ungroup_tabs` | Remove tabs from groups | | `close_tab_group` | Close a group and all its tabs | | Tool | Description | |------|-------------| | `get_bookmarks` | List all bookmarks | | `create_bookmark` | Create a bookmark or folder | | `remove_bookmark` | Delete a bookmark or folder | | `update_bookmark` | Update bookmark title or URL | | `move_bookmark` | Move a bookmark to a different folder | | `search_bookmarks` | Search bookmarks by title or URL | | Tool | Description | |------|-------------| | `search_history` | Search browser history by text query | | `get_recent_history` | Get the most recent history items | | `delete_history_url` | Delete a specific URL from history | | `delete_history_range` | Delete history within a time range | --- ## 40+ External App Integrations 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 Your AI agent calls a tool like `gmail_search_messages` through the BrowserOS MCP. If this is your first time using that service, BrowserOS opens an OAuth login page in the browser. Log in and authorize access. Once authenticated, the tool runs and returns results to your agent. Future calls to the same service work automatically — no re-authentication needed. Your credentials are managed securely via OAuth and are **never stored in BrowserOS**. Tokens are refreshed transparently, and you can revoke access at any time from the service provider. ### Supported Services | Service | What you can do | |---------|----------------| | **Gmail** | Send, read, search emails, manage drafts and labels | | **Outlook Mail** | Send, read, and manage emails | | **Resend** | Send transactional and marketing emails | | Service | What you can do | |---------|----------------| | **Google Calendar** | Create events, find free time, manage calendars | | **Outlook Calendar** | Schedule meetings, manage events | | **Cal.com** | Schedule meetings, manage availability | | Service | What you can do | |---------|----------------| | **Slack** | Post messages, manage channels | | **Discord** | Send messages, manage servers | | **WhatsApp** | Send messages, manage conversations | | **Microsoft Teams** | Chat, meet, and collaborate | | Service | What you can do | |---------|----------------| | **GitHub** | Manage repos, issues, and pull requests | | **GitLab** | Manage repos, issues, and merge requests | | **Vercel** | Deploy and manage web applications | | **Postman** | Test and manage APIs | | **Cloudflare** | Manage domains, DNS, and security | | **Supabase** | Manage databases and backend services | | Service | What you can do | |---------|----------------| | **Linear** | Create issues, manage cycles and projects | | **Jira** | Create issues, manage sprints | | **Asana** | Organize and track team projects | | **Monday** | Manage work and team collaboration | | **ClickUp** | Manage tasks, projects, and workflows | | Service | What you can do | |---------|----------------| | **Notion** | Create pages, manage databases | | **Google Docs** | Create and edit documents | | **Google Sheets** | Create and edit spreadsheets | | **Google Drive** | Upload, download, and manage files | | **Google Forms** | Create and manage forms and surveys | | **Confluence** | Create and manage documentation | | **Airtable** | Manage bases, tables, and records | | Service | What you can do | |---------|----------------| | **Dropbox** | Store and share files | | **OneDrive** | Store and sync files with Microsoft | | **Box** | Manage and share enterprise files | | Service | What you can do | |---------|----------------| | **Figma** | Access and manage design files | | **Canva** | Create and manage designs | | Service | What you can do | |---------|----------------| | **Salesforce** | Manage leads, contacts, and opportunities | | **HubSpot** | Manage contacts, deals, and marketing | | Service | What you can do | |---------|----------------| | **Shopify** | Manage products, orders, and store | | **Stripe** | Manage payments and subscriptions | | Service | What you can do | |---------|----------------| | **PostHog** | Query analytics, manage feature flags | | **Mixpanel** | Analyze user behavior and metrics | | Service | What you can do | |---------|----------------| | **Zendesk** | Manage support tickets and customers | | **Intercom** | Manage customer messaging and support | | Service | What you can do | |---------|----------------| | **Brave Search** | Search the web privately | | **Exa** | AI-powered semantic web search | | **Mem0** | Store and retrieve AI memory | | Service | What you can do | |---------|----------------| | **LinkedIn** | Post updates, manage connections | | **YouTube** | Access video info and transcripts | | **WordPress** | Manage websites and blog content | --- ## Demo Videos ### Agentic coding workflow [](https://youtu.be/vcSxzIIkg_0) ### Browser automation with Claude Code [](https://youtu.be/rPFx_Btajj0) --- ### Browseros Features Vertical Tabs (`docs/browseros/features/vertical-tabs.mdx`) --- title: "Vertical Tabs" description: "Move your tabs to the side for a cleaner, more organized browsing experience" --- 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? 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: Tabs stack vertically with full-width labels, so you always know what is open — no squinting at favicons. Open 30, 50, or 100 tabs without the strip becoming unusable. The side panel scrolls naturally. The horizontal tab bar disappears, giving web pages more room on widescreen monitors. Combine vertical tabs with tab groups to visually separate work, research, and personal browsing. ## Enabling Vertical Tabs Toggle vertical tabs on or off from the Customization settings page. Go to `chrome://browseros/settings` in the address bar. In the left sidebar, select **Customization**. Flip the **Use Vertical Tabs** switch to on. The browser immediately moves your tabs to a side panel. Vertical tabs toggle in BrowserOS Customization settings

Vertical tabs toggle in BrowserOS Customization settings

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 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 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`) --- title: "n8n Integration" description: "Build AI workflows that control your browser" --- 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 - **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 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 ### 1. Install the MCP community node In n8n, go to **Settings → Community Nodes** and install `n8n-nodes-mcp`: Installing n8n-nodes-mcp community node

### 2. Create a workflow 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 n8n workflow with AI Agent and MCP Client

n8n workflow with AI Agent and MCP Client

### 3. Configure the AI Agent In the AI Agent node, set **Source for Prompt** to **Connected Chat Trigger Node**. AI Agent prompt configuration

### 4. Connect to BrowserOS Click on the MCP Client node and configure: - **Endpoint**: Your BrowserOS MCP URL (find it in Settings → BrowserOS as MCP) - **Server Transport**: `HTTP Streamable` MCP Client configuration with BrowserOS URL

MCP Client configuration with BrowserOS URL

### 5. Test it Save the workflow, click **Open chat**, and try: ``` open google.com in BrowserOS ``` Testing the workflow

## Troubleshooting 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`) --- title: "Has Agent Crashed?" description: "How to fix connection issues when the BrowserOS agent is not responding" --- If you see **"Failed to Fetch"** or **"Unable to connect to BrowserOS agent"**, your agent has been killed. Failed to fetch error

## Windows: Did you allow the BrowserOS Agent? 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. Allow BrowserOS Agent network access prompt

Allow BrowserOS Agent network access prompt

To fix this, go to **Windows Security → Allow an app through your network settings**, and make sure **BrowserOS Agent** is enabled. ## Fix It Open **Settings** from the sidebar, scroll to the MCP Server section, and click **Restart**. Wait a couple of minutes. Click Restart in MCP Server Settings

1. Open **Task Manager** — press `Ctrl + Shift + Esc` or right-click the taskbar and select **Task Manager**. 2. In the search bar at the top, type **browseros agent**. 3. Right-click **BrowserOS Agent** and select **End task**. 4. Reopen **BrowserOS** — the agent will restart automatically.

Search for BrowserOS Agent in Task Manager and restart it

If the agent still doesn't reconnect, end both **BrowserOS** and **BrowserOS Agent** in Task Manager, then reopen the app. Right-click BrowserOS in the Dock → **Quit**, then reopen the app. ## Still Not Working? The agent runs on port `9100` by default. If another application is using this port, BrowserOS cannot start the agent. Find the process: ```bash lsof -i :9100 ``` Kill it (replace `PID` with the process ID from above): ```bash kill -9 PID ``` Find the process: ```powershell netstat -ano | findstr :9100 ``` Kill it (replace `PID` with the process ID from above): ```powershell taskkill /PID PID /F ``` Then restart BrowserOS. Some firewalls may block local connections. Make sure your firewall allows connections to `127.0.0.1:9100`. **Windows users:** Antivirus software sometimes triggers a false positive. Try temporarily disabling your antivirus and restarting BrowserOS. ## Get Help If you're still experiencing issues, reach out: Get help from the community Join our Slack --- ### Browseros Update Linux (`docs/browseros/update/linux.mdx`) --- title: "Update on Linux" description: "How to update BrowserOS on Linux" --- Click the **BrowserOS Feedback** extension (bug icon) in the toolbar, then click **Check for Updates**. BrowserOS Feedback extension showing Check for Updates button

BrowserOS Feedback extension showing Check for Updates button

Download the Linux build from [GitHub Releases](https://github.com/browseros-ai/BrowserOS/releases). Extract and run the binary. Your settings and data will be preserved. --- ### Browseros Update Macos (`docs/browseros/update/macos.mdx`) --- title: "Update on macOS" description: "How to update BrowserOS on macOS" --- Go to **Settings > About BrowserOS** to see your current version. Settings page showing About BrowserOS section

Settings page showing About BrowserOS section

BrowserOS on macOS updates automatically. Restart your browser to apply pending updates. If auto-update isn't working, download from [browseros.com](https://browseros.com) or [GitHub Releases](https://github.com/browseros-ai/BrowserOS/releases). --- ### Browseros Update Windows (`docs/browseros/update/windows.mdx`) --- title: "Update on Windows" description: "How to update BrowserOS on Windows" --- Click the **BrowserOS Feedback** extension (bug icon) in the toolbar, then click **Check for Updates**. BrowserOS Feedback extension showing Check for Updates button

Download the Windows installer from [GitHub Releases](https://github.com/browseros-ai/BrowserOS/releases). Double-click the downloaded installer to start the update. You'll see a temporary folder appear — this is normal and expected on Windows. Temporary folder created by the installer

Temporary folder created by the installer

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

BrowserOS app appears on the desktop after installation

If BrowserOS was already running, close it completely and reopen it for the update to take effect. When BrowserOS opens, you may see a popup asking 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. Allow BrowserOS Agent network access prompt

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**. Your settings and data will be preserved after the update. --- ### Neo Mcp Claude Desktop (`docs/neo/mcp/claude-desktop.mdx`) --- title: "Claude Desktop and Cowork" description: "Give Claude Desktop, and Cowork inside it, a real browser via a one-file extension." keywords: ["Claude Desktop MCP", "Claude Cowork MCP", "BrowserOS neo Claude Desktop extension"] --- [Claude Desktop](https://claude.ai/download) and [Claude Cowork](https://claude.com/product/cowork) both run inside the same Claude app. A single BrowserOS neo extension gives them both a real browser to work in. ## Install Download BrowserOS neo from [browseros.com/agents](https://browseros.com/agents) if you haven't already. Launch it at least once so the local server is running. Head to the [releases page](https://github.com/browseros-ai/browserclaw-claude-desktop/releases) and grab the latest `browserclaw-.mcpb` file. This is the Claude Desktop extension package. Open Claude Desktop's Settings window and drag the `.mcpb` file onto it. Claude Desktop registers the extension and starts using BrowserOS neo's tools right away. The repo and the `.mcpb` file still carry the product's old name, BrowserClaw. Only the product was renamed, not the release artifacts, so download the file spelled exactly as above. ## Verify Open BrowserOS neo, then in Claude Desktop ask: ```text 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 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 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](https://github.com/browseros-ai/browserclaw-claude-desktop). ## Troubleshooting **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 A guided walkthrough from install to your first AI-driven session. The AI tools we support with one click today. --- ### Neo Mcp Manual (`docs/neo/mcp/manual.mdx`) --- title: "Manual URL setup" description: "Connect BrowserOS neo to any MCP-compatible AI tool by hand with the endpoint URL, and add the BrowserOS neo skill so your agent uses it well." keywords: ["BrowserOS neo manual MCP setup", "BrowserOS neo skill", "install browseros-neo skill", "Hermes MCP", "Vercel AI SDK MCP", "OpenClaw MCP"] --- 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: ```text http://127.0.0.1:9200/mcp ``` Now pick your AI tool below. The examples name the server `browseros-neo`, matching the one-click setup. The name is yours to choose, but whatever you pick is the name your AI tool will know the browser by. ## Install the skill The skill is one `SKILL.md` file, published from [the BrowserOS repository](https://github.com/browseros-ai/BrowserOS/tree/main/skills/browseros-neo). Most agents read skills from a shared `.agents/skills` directory, and the quickest way to put it there is the [skills.sh](https://skills.sh) CLI: ```bash npx skills add browseros-ai/browseros --skill browseros-neo ``` Keep the `--skill browseros-neo` flag. Without it the command installs every skill published from that repository, including several we use to work on BrowserOS itself, which have no business in your agent. 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 [Hermes Agent](https://hermes-agent.nousresearch.com) from Nous Research supports connecting to external HTTP MCP servers via its YAML config. Full details in [Hermes' MCP docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp). Open `~/.hermes/config.yaml` and add a `mcp_servers` entry: ```yaml 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: ```bash 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](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills). ## Vercel AI SDK The [Vercel AI SDK](https://ai-sdk.dev/) supports MCP tools via the `@ai-sdk/mcp` package. Full details in [the AI SDK MCP docs](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools). Point the client at BrowserOS neo's endpoint URL, pull the tools, and pass them into `streamText` or `generateText`. ```javascript 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: ```javascript 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](https://ai-sdk.dev/cookbook/guides/agent-skills) covers loading names and descriptions up front and fetching the full text on demand with a `loadSkill` tool. ## OpenClaw [OpenClaw](https://openclaw.ai) is an open-source personal AI assistant that can act as an MCP client. Full details in [OpenClaw's MCP docs](https://docs.openclaw.ai/cli/mcp). The fastest path is the CLI: ```bash openclaw mcp add browseros-neo --url http://127.0.0.1:9200/mcp --transport streamable-http ``` Or edit `~/.openclaw/openclaw.json` directly: ```json { "mcp": { "servers": { "browseros-neo": { "url": "http://127.0.0.1:9200/mcp", "transport": "streamable-http" } } } } ``` Verify the connection with the built-in doctor: ```bash 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: ```bash 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](https://docs.openclaw.ai/tools/skills). ## Any other MCP-compatible AI tool 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: ```text 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](https://github.com/orgs/browseros-ai/discussions) with the setup steps. ## Where to next A guided walkthrough from install to your first AI-driven session. The AI tools we support with one click today. --- ### Packages Browseros Bos Build Docs Build Cli (`packages/browseros/bos_build/docs/build-cli.md`) # Build CLI Reference Everything `browseros build` can do beyond the common invocations in [`../README.md`](../README.md). Run these from `packages/browseros`. ## Seeing and tweaking a plan 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. ```bash # 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` 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` 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` 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" 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: ```yaml # 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: ```bash 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: ```bash 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 A fresh machine needs nothing outside this package: ```bash 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 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 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: ```bash browseros product doctor # identity uniqueness + branding assets ``` --- ### Packages Browseros Bos Build Docs Docker Image (`packages/browseros/bos_build/docs/docker-image.md`) # 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`](../../docker/neo/README.md); this page is for building and publishing it. ## Where things live | Path | Role | |---|---| | `docker/neo/Dockerfile` | The image. Picks the `.deb` for each architecture from the version's public `release.json` and checks its sha256, so it builds without `bos_build` | | `docker/neo/entrypoint.sh` | Container supervisor: Xvnc, openbox, websockify, Neo restart loop, profile setup, clean shutdown | | `docker/neo/smoke.py` | End-to-end check from the host: viewer, MCP from outside the container, hosted tool set, an agent tab | | `bos_build/release/docker_image.py` | `build_image`: preflight that each architecture was published, tag policy, buildx invocation | | `bos_build/cli/release_docker.py` | `browseros release docker`, a thin wrapper | | `.github/workflows/release-docker.yml` | Dispatch workflow: build amd64, smoke test, push both architectures | ## Prerequisite: a Linux release with both architectures The image installs released packages. A version can be published only when its `releases/browserclaw//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 From `packages/browseros`: ```bash # 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_.deb`) supplies the version and platform itself; otherwise pass `--version`. ## Publish ```bash 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: ```bash uv run browseros release docker --version 0.52.0.1 --push [--latest] ``` ## First publish 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 - **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`) # 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 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. | Selection | Required Linux artifact keys | | --- | --- | | `x64` | `x64_appimage`, `x64_deb` | | `arm64` | `arm64_appimage`, `arm64_deb` | | `all` | all four keys above | 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. ```text 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 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 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 After this change is merged, dispatch from the default branch: ```sh 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: ```text BrowserOS_neo_v_arm64.AppImage BrowserOS_neo_v_arm64.deb ``` For standalone Linux builds using the existing published resources: ```sh 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 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`) # Nightly macOS CI The two manual entry workflows complete and publish one product each: | Workflow | Display name | Rolling prerelease | | --- | --- | --- | | `.github/workflows/nightly-macos-browseros.yml` | Nightly: BrowserOS (macOS arm64) | `nightly-browseros` | | `.github/workflows/nightly-macos-browserclaw.yml` | Nightly: BrowserOS neo (macOS arm64) | `nightly-browserclaw` | Dispatch either entry from `main`; neither has a schedule or release-shape inputs. ```bash 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 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. ```text 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. | Identity | Meaning | | --- | --- | | Source SHA | Frozen `main` commit used for artifact provenance and component builds | | Reservation SHA | Immutable source child containing the exact version overlay used by the browser build | | State SHA | Product PR head combining the reservation and current-main state with approved snapshots | | Merge SHA | Squash commit proving the product state became durable on `main` | 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 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 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 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: ```bash uv run browseros build --profile nightly-macos --product \ --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`) # 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](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 Both products use the same fixed sequence: ```text 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 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. ```bash 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: | Input | Values | Effect | | --- | --- | --- | | `platforms` | `all` (default), `macos`, `linux`, `windows` | native lanes to build; the others are skipped | | `macos_arch` | `universal` (default), `arm64` | macOS artifact set; non-default only when macOS is selected | | `linux_arch` | `all` (default), `x64`, `arm64` | Linux artifact set; default is accepted when Linux is skipped; `arm64` requires Linux | | `publication` | `alpha` (default), `draft-only` | component publication, see below | `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. ```bash # 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](linux-arm64.md) 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 The component workflows remain independently dispatchable and use main by default: ```bash 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: ```bash cd packages/browseros uv run browseros ota server promote --product browseros --publish uv run browseros ota server promote --product browserclaw --publish ``` ## Retry procedures Rerun failed jobs in the original full-release run: ```bash 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 The full workflows use the standard published-resource path. The equivalent local build is: ```bash 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 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. ```bash 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 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. | Workflow | Owned publication | | --- | --- | | `release-server.yml` | BrowserOS server release, versioned/`latest` resources, alpha OTA, version reflection | | `release-claw-server.yml` | BrowserOS neo server release, versioned/`latest` resources, alpha OTA, version reflection | | `release-claw-onboard.yml` | onboarding release and resources | | `release-extensions.yml` | extension CRX release, versioned object, alpha/bundled manifests, version reflection | | `release-extension-feeds.yml` | explicit extension manifest preview or publication | | `nightly-macos-browseros.yml` | BrowserOS nightly transaction, product alpha snapshots, and `nightly-browseros` | | `nightly-macos-browserclaw.yml` | BrowserOS neo nightly transaction, product alpha snapshots, and `nightly-browserclaw` | | `release-browseros.yml` | ordered BrowserOS component releases, native builds, browser draft | | `release-browserclaw.yml` | ordered BrowserOS neo component releases, native builds, browser draft | ## Required configuration 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`) # 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 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 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 | Piece | Owned code | Integration contract | | --- | --- | --- | | Source preparation | `steps/source/provision.py`, `steps/setup/git.py`, `steps/setup/clean.py`, `cli/source.py`, source/workspace helpers, macOS workspace script and its release/nightly callers; source preparation block in `build-browseros.yml` | Preserve planner/step names where practical; communicate any shared registration changes before editing | | Windows SDK | New Windows SDK setup module; its Windows-only registrations/planner integration; Windows prerequisite workflow block if needed | Do not change source-preparation blocks, Chromium patches, GN files, or the Chromium pin | | Integration and release | Combined main review, full Neo workflow dispatch, run/artifact verification, delegated repairs for additional failures | Merge both implementations before dispatch; a queued or component-only success does not prove full-release success | 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 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`) # 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 | Platform | Label | Image | Compute | Disk | | --- | --- | --- | --- | --- | | Linux x64 | `warp-custom-browseros-ubuntu-2204-x64-32x` | Ubuntu 22.04 | `Standard_D32alds_v7` | P40, 2048 GB | | Windows x64 | `warp-custom-browseros-windows-2025-x64-32x` | Windows Server 2025 | `Standard_D32as_v5` | P30, 1024 GB | | macOS arm64 | `warp-macos-26-arm64-12x` | macOS 26 | M4 Pro, 12 vCPU / 44 GB | 500 GB | 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) 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 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/" \ -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 gh api "orgs/browseros-ai/actions/runner-groups//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: ```bash 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 `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](linux-arm64.md). 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 Cache key: `chromium-src---v2-`. 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): | Phase | Cold (first run / pin bump) | Warm | | --- | --- | --- | | Checkout + sync | 40-70 min | restore 3-10 min + sync 5-15 min | | Compile + package | 2.5-6 h (per platform) | same — out/ is rebuilt per run | | Total | ~4-7 h | ~3-6 h | 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) - **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 ```bash # 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 --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 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 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` A job no runner ever picked up shows `runner_id: 0` and empty steps: ```bash gh run view --json jobs --jq '.jobs[] | {name, status}' gh api repos/browseros-ai/BrowserOS/actions/jobs/ \ --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 /@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`) # 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 - [ ] 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 - [ ] 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\\`. ## Silent Fresh Install - [ ] 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 - [ ] 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`) # 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: ```powershell 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](https://learn.microsoft.com/en-us/windows/apps/windows-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--` 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](https://github.com/actions/runner-images/blob/main/images/windows/scripts/build/Install-VisualStudio.ps1) documents the SDK feature selection and quiet/no-restart pattern; [Windows Installer error codes](https://learn.microsoft.com/en-us/windows/win32/msi/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

Live dashboard

One-click connect

Replay every session

BrowserOS, the AI browser for humans

Live dashboard Your new tab shows every agent working right now: which site it's on, what it's doing, how far along. Docs
One-click connect Automatically connects to every harness. We built tools optimized for web use! Docs
Replay every session Every session is saved as a scrubbable video on your disk with a step-by-step action timeline. Rewind and see exactly what happened. Docs

Nikhil	Nithin	Dani