---
title: "Deploy Browserless"
description: "Headless browser API for automation, scraping, testing, and AI agents."
category: "Automation"
url: https://railway.com/deploy/browserless-railway-template
---

# Deploy Browserless

Headless browser API for automation, scraping, testing, and AI agents.

**[Deploy Browserless on Railway](https://railway.com/template/browserless-railway-template)**

- **Creator:** INF Labs
- **Category:** Automation
- **Total deploys:** 1

## Template content

### browserless-chromium https://devicons.railway.app/browserless

- **Image:** ghcr.io/browserless/chromium:latest
- **Public domain:** Yes

## Documentation

# 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:

```text
https://<your-domain>/
```

Browserless does **not** provide a normal web homepage at `/`.

Seeing this message is expected:

```text
No route or file found for resource GET: /
```

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

```text
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:

| Purpose           | URL                                                   |
| ----------------- | ----------------------------------------------------- |
| API Documentation | `https://<your-domain>/docs/`                         |
| Debugger          | `https://<your-domain>/debugger/?token=<TOKEN>`       |
| Health Check      | `https://<your-domain>/active`                        |
| Screenshot API    | `POST https://<your-domain>/screenshot?token=<TOKEN>` |
| PDF API           | `POST https://<your-domain>/pdf?token=<TOKEN>`        |
| Content API       | `POST https://<your-domain>/content?token=<TOKEN>`    |

## 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:

```text
https://<your-domain>/active
```

Railway also uses this endpoint as the service health check.

### Open the API Documentation

Open:

```text
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

```bash
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

```bash
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

```bash
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.

```javascript
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

```javascript
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

| Capability                         | Browserless | Local Chromium |
| ---------------------------------- | :---------: | :------------: |
| Remote browser API                 |    ✅ Yes    |      ❌ No      |
| Puppeteer support                  |    ✅ Yes    |      ✅ Yes     |
| Playwright support                 |    ✅ Yes    |      ✅ Yes     |
| Shared by multiple apps            |    ✅ Yes    |      ❌ No      |
| Built-in session queue             |    ✅ Yes    |      ❌ No      |
| Central concurrency control        |    ✅ Yes    |      ❌ No      |
| Chromium required inside every app |     ❌ No    |      ✅ Yes     |
| Browser scales separately from app |    ✅ Yes    |      ❌ No      |

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:

```text
?token=<TOKEN>
```

For example:

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

or for WebSocket connections:

```text
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.

| Practice                            | Impact                   |
| ----------------------------------- | ------------------------ |
| Close sessions after completion     | ✅ Saves resources        |
| Limit concurrency                   | ✅ Prevents overload      |
| Use the built-in queue              | ✅ Handles request spikes |
| Leave sessions running indefinitely | ❌ Avoid                  |

## Health Check

Browserless exposes:

```text
/active
```

on port:

```text
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.

## Similar templates

- [N8N Main + Worker](https://railway.com/deploy/n8n-main-worker) — Deploy and Host N8N with Inactive worker.
- [Evolution API with n8n](https://railway.com/deploy/evolution-api-with-n8n) — Automate WhatsApp workflows with Evolution API, n8n, and Postgres.
- [Postgres Backup](https://railway.com/deploy/postgres-s3-backups) — Cron-based PostgreSQL backup to bucket storage

Open this page in a browser: https://railway.com/deploy/browserless-railway-template