Skip to main content

Getting Started

  1. Choose Your Deployment Option

    Browserless Enterprise can be deployed in several ways:

    • Self-hosting Enterprise Docker Image: Run Browserless in your own infrastructure using our Docker images
    • Private Deployment: Custom-tailored deployments for your specific needs

  2. Set Up Your Environment

    Choose from one of the options below:

    a. Docker Quick Start

    The fastest way to get started with Browserless Enterprise is using our Docker image:

    docker run \
      --rm \
      -p 3000:3000 \
      -e "CONCURRENT=10" \
      -e "TOKEN=YOUR_API_TOKEN" \
      ghcr.io/browserless/chromium

    Visit Docker Quick Start for more detailed instructions.

    b. Private Deployment

    For custom deployments, our team will work with you to set up Browserless in our environment according to your specific requirements. Contact us to discuss your needs.

  3. Connect Your Application

    Once your Browserless Enterprise instance is running, you can connect your application using Puppeteer, Playwright, or other supported libraries.

    a. Docker Quick Start

    // Puppeteer example
    const browser = await puppeteer.connect({
      browserWSEndpoint: "ws://localhost:3000?token=YOUR_API_TOKEN",
    });

    // Playwright example
    const browser = await playwright.chromium.connectOverCDP(
      "ws://localhost:3000?token=YOUR_API_TOKEN"
    );

    b. Private Deployment

    // Puppeteer example
    const browser = await puppeteer.connect({
      browserWSEndpoint: “wss://chrome.browserless.io?token=YOUR_API_TOKEN”,
    });
    // Playwright example
    const browser = await playwright.chromium.connectOverCDP(
      “wss://chrome.browserless.io?token=YOUR_API_TOKEN”
    );

Understanding the Browser Endpoint​

The browser endpoint is the WebSocket URL that your application uses to connect to the Browserless instance. It follows this format:

ws://[HOST]:[PORT]?token=[YOUR_API_TOKEN]
  • HOST: Your Browserless server address (e.g., localhost for local deployments)
  • PORT: The port your Browserless instance is running on (default: 3000)
  • TOKEN: Your authentication token (see below for how to get one)

Getting Your Token​

Your token is used to authenticate requests to your Browserless Enterprise instance. You can:

  1. Set it during Docker startup (recommended for development):

    docker run -e "TOKEN=YOUR_API_TOKEN" ghcr.io/browserless/chromium

  2. Use environment variables in your deployment configuration

    # Set environment variables in your deployment
    export BROWSERLESS_TOKEN="YOUR_API_TOKEN"
    export BROWSERLESS_CONCURRENT="10"
    export BROWSERLESS_TIMEOUT="30000"

    # Or in a .env file
    BROWSERLESS_TOKEN=YOUR_API_TOKEN
    BROWSERLESS_CONCURRENT=10
    BROWSERLESS_TIMEOUT=30000

  3. Contact our team for enterprise token management and rotation policies.