Self-Hosting Your Browser Infrastructure

BrowseFleet is fully open-source and designed to run on your own infrastructure. Self-hosting gives you complete control over your data, eliminates per-session cloud costs, and lets you customize the system for your specific needs.

This guide covers everything you need to get BrowseFleet running in production on your own servers.

Why Self-Host

Self-hosting makes sense in several scenarios:

Cost. If you run more than 50 concurrent browser sessions consistently, self-hosting is significantly cheaper than any cloud browser API. A $200/month server can run 50+ concurrent sessions, which would cost $500+ on BrowseFleet's cloud or more on competitors.

Data privacy. All browser traffic flows through your infrastructure. No third party sees your scraped data, cookies, or authentication credentials. This matters for compliance-sensitive industries and when handling personal data.

Customization. You can modify the BrowseFleet source code to add custom features, change default behaviors, or integrate with internal systems. This is not possible with cloud-only services.

Latency. Run BrowseFleet close to your target websites or your application servers to minimize network latency.

No rate limits. Cloud plans have concurrency limits and daily request caps. Self-hosted BrowseFleet has no artificial limits. Your only constraint is hardware.

Docker Setup

BrowseFleet runs as a single Docker container with no external dependencies.

# Pull the latest image
docker pull browsefleet/browsefleet:latest

# Run with default configuration
docker run -d \
  --name browsefleet \
  -p 3000:3000 \
  -e API_KEY=bf_your_secret_key \
  browsefleet/browsefleet:latest

For production, use Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  browsefleet:
    image: browsefleet/browsefleet:latest
    container_name: browsefleet
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - API_KEY=bf_your_secret_key
      - MAX_CONCURRENT_SESSIONS=50
      - SESSION_TIMEOUT=300
      - STEALTH_DEFAULT=full
      - LOG_LEVEL=info
    volumes:
      - browsefleet-data:/data
    shm_size: '2gb'
    deploy:
      resources:
        limits:
          memory: 16G
          cpus: '8'

volumes:
  browsefleet-data:

The shm_size setting is critical. Chrome uses /dev/shm for shared memory, and the default Docker allocation (64MB) is too small. Set it to at least 2GB for production workloads.

docker compose up -d

Verify the installation:

curl http://localhost:3000/health
# {"status": "ok", "version": "1.0.0", "sessions": 0}

Resource Planning

Each browser session consumes approximately: - RAM: 150-300MB idle, up to 500MB for complex pages - CPU: 0.1-0.5 cores per active session - Disk: 50-100MB for profile data (if using cookie persistence)

Use these numbers to plan your infrastructure:

These are conservative estimates. BrowseFleet manages browser lifecycle aggressively. Idle sessions are suspended, crashed browsers are cleaned up, and memory is reclaimed when sessions close.

Add 20-30% headroom above your expected peak concurrency to handle spikes without degradation.

Configuration

BrowseFleet is configured via environment variables:

# Authentication
API_KEY=bf_your_secret_key

# Session limits
MAX_CONCURRENT_SESSIONS=50
SESSION_TIMEOUT=300          # seconds
MAX_SESSION_DURATION=3600    # seconds

# Stealth
STEALTH_DEFAULT=full         # none, basic, full

# CAPTCHA solving (optional)
CAPTCHA_API_KEY=your_2captcha_key
CAPTCHA_PROVIDER=2captcha

# Proxy (optional default proxy)
DEFAULT_PROXY=socks5://user:pass@proxy:1080

# Logging
LOG_LEVEL=info               # debug, info, warn, error

For CAPTCHA solving, you need a 2captcha API key. The CAPTCHA solving feature is optional. If not configured, CAPTCHAs will not be solved automatically.

Monitoring and Alerting

BrowseFleet exposes a /metrics endpoint compatible with Prometheus:

curl http://localhost:3000/metrics

Key metrics to monitor:

browsefleet_active_sessions - Current number of active browser sessions. Alert when this approaches MAX_CONCURRENT_SESSIONS.

browsefleet_session_duration_seconds - Histogram of session durations. Unusually long sessions may indicate leaked sessions that are not being closed properly.

browsefleet_memory_usage_bytes - Total memory used by the BrowseFleet process and its browser instances. Alert at 80% of available RAM.

browsefleet_request_errors_total - Counter of failed requests by error type. A spike in errors indicates a systemic issue.

A basic Grafana dashboard showing these four metrics gives you sufficient visibility for most deployments.

Scaling Strategies

When a single BrowseFleet instance is not enough:

Vertical scaling. The simplest approach: use a larger server. BrowseFleet scales well on a single machine up to about 100 concurrent sessions. Beyond that, you hit diminishing returns due to Chrome's memory overhead.

Horizontal scaling with a load balancer. Run multiple BrowseFleet instances behind a load balancer. Each instance manages its own pool of browser sessions. The load balancer distributes session creation requests across instances. Use sticky sessions so that once a session is created on an instance, subsequent requests for that session go to the same instance.

# docker-compose with multiple instances
services:
  browsefleet-1:
    image: browsefleet/browsefleet:latest
    environment:
      - MAX_CONCURRENT_SESSIONS=50
    shm_size: '2gb'

  browsefleet-2:
    image: browsefleet/browsefleet:latest
    environment:
      - MAX_CONCURRENT_SESSIONS=50
    shm_size: '2gb'

  nginx:
    image: nginx
    ports:
      - "3000:3000"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

Kubernetes. For large-scale deployments, run BrowseFleet as a Kubernetes Deployment with horizontal pod autoscaling based on active session count. This is the most operationally complex option but provides the best scalability.

Start with a single instance and scale as your needs grow. Most teams never need more than one instance.