BotBrowser Installation Guide

This guide provides step-by-step installation, troubleshooting, and deployment options across operating systems. Usage remains subject to the project Legal Disclaimer and Responsible Use Guidelines.

Choosing a Build

BotBrowser ships in two builds. Both share the same fingerprint protection model, profile format, CLI flag surface, and CDP commands.

• Standard Build is the default public release. Use this build for long-running sessions, interactive workflows, and scenarios that exercise the full browser feature surface. Available on the Releases page; the instructions on this page describe Standard Build installation.
• Trimmed Build (ENT Tier3) is a separately built distribution tuned for short-session, high-concurrency automation. Linux x64 benchmark: 62% lower wall time, 85% faster per-context creation, 68% lower CPU peak versus Standard. Trimmed Build is not on the public Releases page; it is distributed through the enterprise channel. Product overview: TRIMMED_BUILD.md. Full performance table: BENCHMARK.md#trimmed-build. Access: Enterprise  or Pricing .

Profiles, automation code, and CLI flags from Standard Build work unchanged on Trimmed Build, so you can build against Standard locally and switch to Trimmed in production.

Download & Installation

1. Download Installer

Get the Standard Build installer for your OS from the Releases page. (Trimmed Build is distributed through the enterprise channel; see Choosing a Build.)

2. Windows Installation

Quick Install (PowerShell)

# Install latest version
iwr -Uri "https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.ps1" -OutFile "$env:TEMP\install_botbrowser.ps1"; & "$env:TEMP\install_botbrowser.ps1"
 
# Install specific Chrome version
iwr -Uri "https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.ps1" -OutFile "$env:TEMP\install_botbrowser.ps1"; & "$env:TEMP\install_botbrowser.ps1" -Version 146
 
# Install to custom directory
iwr -Uri "https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.ps1" -OutFile "$env:TEMP\install_botbrowser.ps1"; & "$env:TEMP\install_botbrowser.ps1" -InstallDir "D:\BotBrowser"

Note: Requires 7-Zip for extraction.

Manual Installation

1. Extract the downloaded .7z archive
2. Run chrome.exe from the extracted folder

Common Windows Issues & Solutions

Windows Command-Line Example

CMD:

chrome.exe --bot-profile="C:\absolute\path\to\profile.enc" --user-data-dir="%TEMP%\botprofile_%RANDOM%"

PowerShell:

.\chrome.exe --bot-profile="C:\absolute\path\to\profile.enc" --user-data-dir="$env:TEMP\botprofile_$(Get-Random)"

Note: CMD uses %VAR% syntax while PowerShell uses $env:VAR. The %RANDOM% variable only works in CMD; use $(Get-Random) in PowerShell.

3. macOS Installation

Quick Install (Script)

# Install latest version
curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash
 
# Install specific Chrome version
curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash -s -- 146
 
# Download only, don't install
curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash -s -- --download

The script auto-detects your Mac’s architecture (Apple Silicon or Intel), fetches the latest release via the GitHub API, and installs to /Applications/.

Manual Installation

1. Open the downloaded .dmg file
2. Drag Chromium.app into your Applications folder or any desired location
3. If you see the error:

   "Chromium" is damaged and can't be opened

   Run:

   xattr -rd com.apple.quarantine /Applications/Chromium.app

Common macOS Issues & Solutions

macOS Command-Line Example

/Applications/Chromium.app/Contents/MacOS/Chromium \
  --user-data-dir="$(mktemp -d)" \
  --bot-profile="/absolute/path/to/profile.enc"

4. Ubuntu Installation (ENT Tier1)

Note: Ubuntu/Linux binaries require an ENT Plan Tier 1 or higher subscription.

Quick Install (Script)

# One-line install (auto-detects architecture: x86_64 or arm64)
curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash
 
# Install specific Chrome version
curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash -s -- 146
 
# Download only, don't install
curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash -s -- --download

Docker / CI

RUN curl -sL https://raw.githubusercontent.com/botswin/BotBrowser/main/scripts/install_botbrowser.sh | bash

No hardcoded URLs needed. The script uses the GitHub Releases API to always fetch the latest build for your platform.

Manual Installation

1. Install via dpkg:

   sudo dpkg -i botbrowser_<version>_amd64.deb

2. If dependencies are missing, run:

   sudo apt-get install -f

Required Dependencies

# Essential libraries
sudo apt-get update
sudo apt-get install -y \
    libnss3 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libgbm1 \
    libxkbcommon0 \
    libgtk-3-0

Ubuntu Command-Line Example

chromium-browser \
  --user-data-dir="$(mktemp -d)" \
  --bot-profile="/absolute/path/to/profile.enc"

Docker Deployment

For containerized deployment with full isolation and scalability:

Quick Docker Setup

# Pull the latest BotBrowser Docker image
docker pull botbrowser/botbrowser:latest
 
# Run with profile mounting
docker run -d \
  --name botbrowser-instance \
  -v path/to/profiles:/app/profiles \
  -p 9222:9222 \
  botbrowser/botbrowser:latest \
  --bot-profile="/absolute/path/to/profile.enc" \
  --remote-debugging-port=9222

Docker Compose Deployment

For production environments, see the complete Docker deployment guide with:

• Multi-instance orchestration
• Proxy configuration
• Volume management
• Health checks
• Scaling configurations

First Launch Verification

Basic Functionality Test

After installation, verify BotBrowser is working correctly:

# Test basic launch (replace with your executable path)
chrome.exe --bot-profile="C:\\absolute\\path\\to\\profile.enc" --version
 
# Test with remote debugging
chrome.exe --bot-profile="C:\\absolute\\path\\to\\profile.enc" --remote-debugging-port=9222
 
# Verify remote debugging is active
curl http://localhost:9222/json/version

Profile Validation

Ensure your profiles are working correctly:

# Check profile file permissions (Linux/macOS)
ls -la ./profiles/*.enc
 
# Test profile loading
chrome.exe --bot-profile="C:\\absolute\\path\\to\\profile.enc" --headless --dump-dom https://httpbin.org/user-agent

Security Considerations

Firewall Configuration

BotBrowser may need network access for:

• Profile validation and updates
• Remote debugging (if enabled)
• Proxy authentication
• Timezone/locale auto-detection

Recommended Firewall Rules

# Allow outbound HTTPS (profile updates)
ufw allow out 443
 
# Allow remote debugging port (if used)
ufw allow 9222
 
# Allow proxy connections (if used)
ufw allow out on <proxy-port>

Profile Security

• Store profile files (.enc) in secure directories with appropriate permissions
• Never commit profiles to version control systems
• Use temporary user data directories (--user-data-dir) to avoid persistent data
• Regularly update profiles from trusted sources

Installation Support

Getting Help

If you encounter installation issues:

1. Check the troubleshooting table above for common solutions
2. Verify system requirements match your OS version
3. Test with a matching profile package. BotBrowser 150 and newer profiles are available through subscription or support at support@botbrowser.io or @botbrowser_support; legacy demo profiles remain in the profiles directory for older evaluation lines.
4. Contact support with detailed error messages

Contact Information

Reporting Installation Issues

When reporting installation problems, please include:

• Operating system and version
• BotBrowser version
• Complete error messages
• Steps to reproduce the issue
• System specifications (RAM, disk space, etc.)

Related Documentation

• Main README - Project overview and quick start
• Guides  - Step-by-step guides for proxy, fingerprint, identity, platform emulation, and deployment
• CLI Flags Reference - Complete command-line options
• Profile Configuration - Advanced profile customization
• Docker Guide - Containerized deployment
• Advanced Features - Detailed feature documentation

Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.