Headless Server Setup

Set up BotBrowser on headless Ubuntu servers for stable production automation with consistent fingerprint protection.

Prerequisites

• Ubuntu 20.04 or later (x86_64 or arm64).
• BotBrowser Ubuntu binary installed via dpkg or the install script. See Installation Guide.
• A profile file (.enc for production). Download from GitHub Releases .
• Root or sudo access for installing system packages.

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

Quick Start

1. Install required system packages

sudo apt-get update
sudo apt-get install -y \
    libnss3 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libgbm1 \
    libxkbcommon0 \
    libgtk-3-0 \
    libpangocairo-1.0-0 \
    libpango-1.0-0 \
    libwayland-client0 \
    libwayland-server0 \
    libdbus-1-3 \
    libatspi2.0-0 \
    libasound2 \
    libxss1 \
    fonts-liberation \
    xvfb

2. Set up a virtual display

BotBrowser requires a virtual display on headless servers, even when running in headless mode. Start Xvfb on display :10.0:

Xvfb :10 -screen 0 1920x1080x24 &
export DISPLAY=:10.0

3. Launch BotBrowser

DISPLAY=:10.0 chromium-browser \
    --headless \
    --no-sandbox \
    --user-data-dir="$(mktemp -d)" \
    --bot-profile="/path/to/profile.enc" \
    --proxy-server=socks5://user:pass@proxy.example.com:1080 \
    --remote-debugging-port=9222

4. Verify the instance is running

curl http://localhost:9222/json/version

How It Works

On a headless server, BotBrowser needs a few components that are normally present on desktop systems:

1. System libraries. Chrome depends on GTK, NSS, ALSA, and other shared libraries. Without them, the binary crashes immediately on startup.

2. Virtual display (Xvfb). Even in --headless mode, BotBrowser requires an X11 display server. Xvfb provides a virtual framebuffer that satisfies this requirement without a physical monitor. The DISPLAY=:10.0 environment variable must be set for every BotBrowser process.

3. GPU rendering. Servers typically lack a physical GPU. BotBrowser uses SwiftShader (a software-based GPU renderer bundled with the browser) automatically when no hardware GPU is available. This provides consistent WebGL and WebGPU output across server environments.

4. Profile-based fingerprinting. All fingerprint properties (screen resolution, fonts, GPU info, etc.) come from the profile file, not from the server hardware. This means a Windows profile running on an Ubuntu server produces identical fingerprint output.

Common Scenarios

Running multiple instances

Use separate user data directories and debugging ports for each instance:

for i in 1 2 3; do
    DISPLAY=:10.0 chromium-browser \
        --headless \
        --no-sandbox \
        --user-data-dir="/tmp/bb-instance-$i" \
        --bot-profile="/path/to/profile.enc" \
        --remote-debugging-port=$((9222 + i)) &
done

Systemd service for persistent operation

Create /etc/systemd/system/botbrowser.service (requires the Xvfb service defined in the next section):

[Unit]
Description=BotBrowser Instance
After=network.target xvfb.service
Requires=xvfb.service
 
[Service]
Type=simple
User=botbrowser
Environment=DISPLAY=:10.0
ExecStart=/usr/bin/chromium-browser \
    --headless \
    --no-sandbox \
    --user-data-dir=/var/lib/botbrowser/data \
    --bot-profile=/var/lib/botbrowser/profile.enc \
    --remote-debugging-port=9222
Restart=on-failure
RestartSec=5
 
[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable botbrowser
sudo systemctl start botbrowser

Dedicated Xvfb systemd service

For production, run Xvfb as a separate service so it starts before BotBrowser:

Create /etc/systemd/system/xvfb.service:

[Unit]
Description=X Virtual Frame Buffer
After=network.target
 
[Service]
Type=simple
ExecStart=/usr/bin/Xvfb :10 -screen 0 1920x1080x24 -ac
Restart=always
 
[Install]
WantedBy=multi-user.target

Then update the BotBrowser service to depend on it:

[Unit]
Description=BotBrowser Instance
After=network.target xvfb.service
Requires=xvfb.service

Monitoring with health checks

Create a simple health check script:

#!/bin/bash
response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:9222/json/version)
if [ "$response" != "200" ]; then
    echo "BotBrowser is not responding, restarting..."
    systemctl restart botbrowser
fi

Add to cron for periodic checks:

*/5 * * * * /usr/local/bin/bb-healthcheck.sh

Troubleshooting / FAQ

Next Steps

• Docker Deployment. Containerized setup with orchestration and scaling.
• Performance Optimization. Reduce resource usage and improve speed.
• Screenshot Best Practices. Capture screenshots correctly on headless servers.
• CLI Flags Reference. Complete list of all available flags.

Related documentation: Installation Guide | Playwright Guide | Advanced Features

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