Codakey
Play
← Back to BrowserOS

How to Deploy & Use BrowserOS

BrowserOS Deployment and Usage Guide

1. Prerequisites

System Requirements:

  • Operating System: macOS, Windows, or Linux (Debian/Ubuntu recommended)
  • Hardware: Modern CPU with AVX2 support (for local AI models), 8GB+ RAM recommended
  • Disk Space: 2GB+ for installation, additional space for AI models if running locally

Development Prerequisites (for building from source):

AI Provider Accounts (choose one or more):

  • OpenAI API key (for GPT models)
  • Anthropic API key (for Claude models)
  • Google AI API key (for Gemini models)
  • OpenRouter API key (alternative provider)
  • Ollama (for local models, no API key required)
  • LM Studio (for local models)

2. Installation

Option A: Download Pre-built Binaries (Recommended)

macOS:

# Download the .dmg file
curl -L -o BrowserOS.dmg https://files.browseros.com/download/BrowserOS.dmg

# Mount the disk image
hdiutil attach BrowserOS.dmg

# Drag BrowserOS.app to Applications folder
# Eject the disk image
hdiutil detach /Volumes/BrowserOS/

Windows:

  1. Download BrowserOS_installer.exe
  2. Run the installer and follow the setup wizard

Linux (AppImage):

# Download the AppImage
wget https://files.browseros.com/download/BrowserOS.AppImage

# Make it executable
chmod +x BrowserOS.AppImage

# Run BrowserOS
./BrowserOS.AppImage

Linux (Debian/Ubuntu):

# Download the .deb package
wget https://cdn.browseros.com/download/BrowserOS.deb

# Install with dpkg
sudo dpkg -i BrowserOS.deb

# Install dependencies if needed
sudo apt-get install -f

Option B: Build from Source

# Clone the repository
git clone https://github.com/browseros-ai/BrowserOS.git
cd BrowserOS

# Install Chromium build dependencies (Linux example)
# See Chromium documentation for macOS/Windows setup
sudo apt-get install git curl python3 python3-pip
sudo ./build/install-build-deps.sh

# Sync and build Chromium (this will take several hours)
gclient sync
gn gen out/Default
autoninja -C out/Default chrome

# Build BrowserOS-specific components
cd packages/browseros
npm install
npm run build

# The built binary will be at: out/Default/chrome

3. Configuration

Initial Setup

  1. First Launch:

    • Launch BrowserOS from your Applications folder or start menu
    • Import Chrome data when prompted (optional)
    • The browser will open with familiar Chrome interface

  2. Configure AI Providers:

    Navigate to Settings → BrowserOS → AI Providers or go to chrome://settings/browseros

    Supported Providers:

    • BrowserOS (Default): Built-in models
    • OpenAI: GPT-4, GPT-5, o1, o3 series
    • Anthropic: Claude Opus, Sonnet, Haiku
    • Google Gemini: Gemini Pro, Flash, Nano
    • Ollama: Local models (Llama, Mistral, etc.)
    • OpenRouter: Unified API for multiple providers
    • Custom: Self-hosted or compatible endpoints

    Configuration Example for OpenAI:

    Provider: OpenAI
API Key: sk-... (from platform.openai.com)
Model: gpt-4.1 (or gpt-5, o1-mini, etc.)
Base URL: https://api.openai.com/v1 (default)

    Configuration Example for Ollama (Local):

    Provider: Ollama
API Key: (leave blank)
Model: llama3.2:latest
Base URL: http://localhost:11434

    Environment Variables (Alternative):

    # Set API keys via environment (useful for automation)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_AI_API_KEY="AIza..."

  3. Configure MCP Server (Optional):

    To use BrowserOS as an MCP server with Claude Code or other MCP clients:

    # Enable MCP server in settings
# Default port: 3000
# Available tools: 31 browser automation tools

4. Build & Run

Development Build

# Set up development environment
cd BrowserOS/packages/browseros

# Install dependencies
npm install

# Build in development mode
npm run dev

# Or watch for changes
npm run watch

# Run tests
npm test

Production Build

# Full Chromium build with BrowserOS patches
cd BrowserOS

# Apply BrowserOS patches to Chromium
./scripts/apply_patches.sh

# Build optimized version
gn gen out/Release --args="is_debug=false is_official_build=true"
autoninja -C out/Release chrome

# Package for distribution
cd packages/browseros
npm run package

# Output: .dmg (macOS), .exe (Windows), .AppImage/.deb (Linux)

Running with Custom Configuration

# Run with specific AI provider
./BrowserOS --ai-provider=openai --ai-model=gpt-4.1

# Run with custom config file
./BrowserOS --config=./browseros-config.json

# Enable debug logging
./BrowserOS --enable-logging --v=1

5. Deployment

Desktop Deployment

macOS:

  • Use the .dmg for distribution
  • Sign with Apple Developer certificate for Gatekeeper compatibility
  • Notarize using xcrun notarytool

Windows:

  • Use the .exe installer
  • Sign with Authenticode certificate
  • Consider MSI packaging for enterprise deployment

Linux:

  • AppImage: Single executable, works across distributions
  • .deb package: For Debian/Ubuntu-based systems
  • Snap/Flatpak: For universal Linux distribution

Enterprise Deployment

Group Policy / MDM:

  • Configure AI provider settings via policy templates
  • Distribute API keys securely via enterprise key management
  • Use --policy-configuration-file flag for centralized control

Docker Container (for testing/CI):

FROM ubuntu:22.04

# Install dependencies
RUN apt-get update && apt-get install -y \
    wget \
    libgtk-3-0 \
    libnss3 \
    libxss1 \
    libasound2

# Download BrowserOS AppImage
RUN wget https://files.browseros.com/download/BrowserOS.AppImage \
    && chmod +x BrowserOS.AppImage

# Run in headless mode for automation
CMD ["./BrowserOS.AppImage", "--headless", "--remote-debugging-port=9222"]

Cloud Deployment Considerations

While BrowserOS is primarily a desktop application, you can deploy the MCP server component:

# Run MCP server standalone
cd packages/browseros-mcp
npm start

# Environment variables for cloud deployment
export MCP_PORT=3000
export ALLOWED_ORIGINS="https://your-domain.com"
export API_KEY="your-secure-token"

6. Troubleshooting

Common Issues

1. BrowserOS won't start:

# Check system requirements
# Verify you have AVX2 support:
grep avx2 /proc/cpuinfo  # Linux
sysctl -a | grep machdep.cpu.features  # macOS

# Clear corrupted profile
rm -rf ~/.config/BrowserOS  # Linux
rm -rf ~/Library/Application\ Support/BrowserOS  # macOS

2. AI features not working:

# Verify API keys are set
# Check provider status in chrome://settings/browseros

# Test API connectivity
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# For Ollama, ensure it's running
curl http://localhost:11434/api/tags

3. Build failures:

# Ensure all Chromium dependencies are installed
./build/install-build-deps.sh --no-arm --no-chromeos-fonts

# Clear build cache
rm -rf out/
gn clean out/Default

# Check for sufficient RAM (16GB+ recommended for building)
free -h

4. MCP server connection issues:

# Verify MCP server is running
curl http://localhost:3000/health

# Check firewall settings
sudo ufw allow 3000/tcp  # Linux

# Enable debug logging
./BrowserOS --mcp-debug --mcp-port=3000

5. Extension compatibility:

  • BrowserOS supports Manifest V2 extensions (unlike Chrome)
  • If an extension doesn't work, try loading it unpacked
  • Check extension permissions in chrome://extensions

Getting Help

Debug Information

To collect debug information:

# Run with verbose logging
./BrowserOS --enable-logging --v=2

# Generate debug report
# Navigate to: chrome://settings/help
# Click "Report an issue"

# Check browser logs
# Linux: ~/.config/BrowserOS/chrome_debug.log
# macOS: ~/Library/Logs/BrowserOS/chrome_debug.log
# Windows: %LOCALAPPDATA%\BrowserOS\chrome_debug.log
← Project overviewView alternatives to BrowserOS →