Deploy and Host Browserless on Railway

Browserless runs headless Chromium as a service: connect Puppeteer or Playwright over WebSocket, or call plain REST endpoints to render a screenshot, produce a PDF, scrape content, or run arbitrary browser automation. This template deploys Browserless v2.55 with token authentication enabled and concurrency limits set.

About Hosting Browserless

Running headless Chrome yourself is unpleasant: the system dependency list is long, zombie browser processes accumulate, and one runaway page can consume every core on the box. Browserless wraps Chromium in a supervised HTTP and WebSocket API that kills sessions on timeout and queues work beyond a set concurrency, which is what makes it deployable rather than merely runnable.

Concurrency is the setting that matters most on shared infrastructure, and it is the one most deployments leave at default. This template sets CONCURRENT to 3 with a queue depth of 10 and a 60-second session timeout, so a burst of requests queues instead of spawning unbounded Chromium processes until the instance is killed. Raise CONCURRENT as you scale the service up; each concurrent session wants roughly 300–500MB.

Authentication is on. Browserless will run without a token, and an unauthenticated instance is a serious liability — anyone who finds the URL gets a general-purpose browser running inside your infrastructure, able to reach your private services and fetch arbitrary URLs from your IP. This template generates a 48-character TOKEN at deploy, and ALLOW_FILE_PROTOCOL is left off so sessions cannot read local files via file://.

No volume is attached, by design: browser sessions are ephemeral and nothing here is worth persisting.

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.

• Authenticated by default — a generated token is required; requests without it are rejected with 401.
• Bounded concurrency — a queue instead of unbounded Chromium processes competing for the instance.
• file:// disabled — sessions cannot read the container filesystem.
• Current Chromium — Browserless v2.55, shipping Chrome 149.
• Drop-in for Puppeteer and Playwright — point browserWSEndpoint or connectOverCDP at your domain.

Common Use Cases

• Screenshot and PDF generation — render invoices, reports, or social preview images from HTML.
• Scraping JavaScript-heavy pages — fetch content that only exists after client-side rendering.
• End-to-end test runners — give CI a persistent browser backend instead of installing Chrome per job.

Dependencies for Browserless Hosting

• No database or volume required.
• Roughly 300–500MB RAM per concurrent browser session; size the instance for your CONCURRENT setting.

Deployment Dependencies

• Browserless — upstream project (SSPL / commercial)
• Browserless documentation — REST endpoints, WebSocket connection, and options
• ghcr.io/browserless/chromium — the image this template deploys

Implementation Details

One service, no datastore:

Confirm it is up and that auth is enforced — the first call returns 401, the second returns the browser version:

curl -o /dev/null -w "%{http_code}\n" https:///json/version
curl "https:///json/version?token=$TOKEN"

Render a screenshot over REST:

curl -X POST "https:///screenshot?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "options": {"type": "png"}}' \
  -o shot.png

Or drive it from Puppeteer:

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://?token=${process.env.TOKEN}`,
});

Other endpoints include /pdf, /content, /scrape, and /function. Keep the token secret — it is the only thing standing between the public internet and a browser inside your infrastructure.