INSTALLATION.md

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.

Download & Installation

1. Download Installer

Get the installer for your OS from the Releases page.

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

Issue	Solution
Profile file permission errors	Ensure .enc file has read permissions
BotBrowser won't start or crashes	Check that your OS and Chromium version match the build; update BotBrowser to the latest release
Antivirus blocking execution	Add BotBrowser directory to antivirus exclusions

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

Issue	Solution
"Chromium" is damaged	Run xattr -rd com.apple.quarantine /Applications/Chromium.app
Permission denied	Ensure you have admin rights and the app is in Applications folder
Gatekeeper blocking	Go to System Preferences > Security & Privacy and allow the app

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 demo profiles from the profiles directory
4. Contact support with detailed error messages

Contact Information

Email	support@botbrowser.io
Telegram	@botbrowser_support

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.