Deploy Browserless

Deploy and Host Browserless on Railway

Browserless is a headless Chromium service that can be accessed through an API. It is suitable for automation, scraping, testing, screenshots, PDF generation, and AI agents without requiring Chrome to run inside every application.

About Hosting Browserless

Browserless runs Chromium as a remote browser service on Railway. Applications connect to it through Puppeteer, Playwright, WebSocket, CDP, or HTTP APIs, while Browserless manages the browser process and session lifecycle.

This architecture separates browser execution from application logic. Your applications do not need to install or maintain Chromium locally, and multiple services can share the same Browserless deployment.

Important: The Root URL Is Not a Homepage

After deployment, Railway may automatically open:

https://<your-domain>/

Browserless does not provide a normal web homepage at /.

Seeing this message is expected:

No route or file found for resource GET: /

Adding your token to the root URL does not change this:

https://<your-domain>/?token=<TOKEN>

The root path is not an API operation or dashboard.

Your Browserless deployment is working as long as the service is healthy and its API endpoints respond correctly.

Use these URLs instead:

Common Use Cases

• Browser automation with Puppeteer or Playwright
• Web scraping and JavaScript-rendered content extraction
• Screenshot and PDF generation
• End-to-end browser testing
• AI agents that need browser access
• Website monitoring and automated browser workflows

Getting Started

After deployment:

1. Open the Browserless service in Railway.
2. Go to Variables.
3. Copy the generated TOKEN.
4. Copy your Railway public domain.
5. Do not use / as the Browserless API endpoint.
6. Use /docs/, a REST endpoint, or a WebSocket connection depending on your workload.

Check That Browserless Is Running

Open:

https://<your-domain>/active

Railway also uses this endpoint as the service health check.

Open the API Documentation

Open:

https://<your-domain>/docs/

This is the easiest way to explore the API after deployment.

Using the HTTP API

Browserless REST endpoints are generally called using POST requests.

Simply pasting the API URL into your browser sends a GET request, which is not how endpoints such as /screenshot, /pdf, and /content are intended to be used.

Screenshot Example

curl -X POST \
  "https://<your-domain>/screenshot?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "fullPage": true,
      "type": "png"
    }
  }' \
  --output screenshot.png

Browserless returns the generated image directly. The official Screenshot API uses POST /screenshot with the token supplied as a query parameter.

PDF Example

curl -X POST \
  "https://<your-domain>/pdf?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "format": "A4",
      "printBackground": true
    }
  }' \
  --output output.pdf

Rendered HTML Example

curl -X POST \
  "https://<your-domain>/content?token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

Connecting with Puppeteer

Browserless can also be controlled through a WebSocket connection rather than REST.

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint:
    "wss://<your-domain>?token=<TOKEN>",
});

const page = await browser.newPage();

await page.goto("https://example.com");

console.log(await page.title());

await browser.close();

Connecting with Playwright

import { chromium } from "playwright-core";

const browser = await chromium.connect(
  "wss://<your-domain>/chromium/playwright?token=<TOKEN>"
);

const page = await browser.newPage();

await page.goto("https://example.com");

console.log(await page.title());

await browser.close();

Browserless vs Local Chromium

Browserless is useful when multiple applications, automation workflows, or AI agents need browser access from shared infrastructure.

Authentication

Browserless access is protected using the TOKEN generated by this template.

The token is normally provided as a query parameter:

?token=<TOKEN>

For example:

POST https://<your-domain>/screenshot?token=<TOKEN>

or for WebSocket connections:

wss://<your-domain>?token=<TOKEN>

Do not share this token publicly.

Sessions and Queue

Browserless can execute multiple browser sessions while queuing additional requests when capacity is full.

Health Check

Browserless exposes:

/active

on port:

3000

Use /active, not /, when checking whether the Browserless service is online.

Dependencies for Browserless Hosting

• Browserless Chromium — remote Chromium runtime and browser API
• Railway Compute — hosts the Browserless service
• Authentication Token — protects API access
• Puppeteer, Playwright, or HTTP Client — controls the remote browser

No PostgreSQL, Redis, MySQL, or persistent volume is required for the standard deployment.

Documentation

• Browserless Documentation: https://docs.browserless.io/
• Browserless REST APIs: https://docs.browserless.io/rest-apis/intro
• Browserless GitHub: https://github.com/browserless/browserless
• Puppeteer: https://pptr.dev/
• Playwright: https://playwright.dev/

Why Deploy Browserless on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Browserless on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.