# How to Deploy Browserless With xCloud One Click Apps

> Deploy Browserless on xCloud from One Click Apps: pick a server, copy the API token, take a first screenshot and connect Puppeteer or Playwright.

You can run [Browserless](https://www.browserless.io/) on your own server with xCloud without writing a Docker Compose file. Click **New Site**, pick **Browserless** in the app catalog, choose a server, enter a site title, choose **Demo Site** or **Go Live**, and click **Next**. xCloud starts Browserless, serves it over HTTPS and generates your API token. This guide walks through each screen up to your first screenshot and a Puppeteer or Playwright connection.

**Who this is for:** developers who need a headless browser for scraping, PDFs, screenshots or automated tests, without running Chromium on their own machine. For server sizes and prices, see [Browserless hosting on xCloud](/browserless-hosting/).

## What the Browserless app includes

| Part | What you get |
|---|---|
| Browserless | The official Browserless 2.57.3 Chromium image. Only Chromium is included, not Firefox or WebKit. |
| Web address | The API on your domain, behind xCloud's Nginx with an SSL certificate. WebSocket connections work through the same address. |
| API token | A generated 48-character token. Every API and WebSocket request must include it. |
| Stored data | None. Browserless has no database and no saved files, and each session starts with a clean browser. |

## Check the licence first

As of November 2026, Browserless is licensed under SSPL-1.0 or the Browserless commercial licence. Browserless says that closed-source commercial sites, applications and CI pipelines need a commercial licence from browserless.io. The One Click App does not include one, so choosing and following a licence is up to you. Read the [Browserless licence](https://github.com/browserless/browserless/blob/v2.57.3/LICENSE) before you use it in a product. This is not legal advice.

## Before you start

- An xCloud account that can create sites.
- An **Nginx** server. xCloud installs Docker on it if it isn't there yet. An existing server needs at least **2 GB RAM, 2 CPU cores and 8 GB of free disk**. You can also create a new server during setup.
- For **Go Live**: a domain you can point at the server. For a first try, **Demo Site** needs no domain.

## Step 1: Find Browserless in the app catalog

From the xCloud dashboard, click **New Site**. On **What would you like to host today?**, type **Browserless** in the search box, then click the **Browserless** card.

![The Browserless card in the xCloud app catalog after searching for Browserless](/_landing/docs/deploy-browserless-with-xcloud-image-1.png)

The Browserless page opens. It shows **Runs on Nginx, Docker** and **Recommended: 2 GB RAM · 2 vCPU · 8 GB disk**.

## Step 2: Choose where Browserless will run

Under **Where should it run?**, follow the path that fits your account:

- **Use an existing server:** click the server's card, then click **Continue**. Each card shows the server's RAM, CPU and free disk.
- **Use a new server:** click **Deploy on a new server** and finish creating the server. After the server is ready, xCloud brings you back to this page to finish the install. If it doesn't, open **New Site → Browserless** again.
- **No compatible server:** the page shows **No compatible server yet.** Use **Create Managed Server** or **Connect a Provider** to add one. After the server is ready, xCloud brings you back to this page to finish the install. If it doesn't, open **New Site → Browserless** again.

![An existing Nginx server selected under Where should it run? on the Browserless install page](/_landing/docs/deploy-browserless-with-xcloud-image-2.png)

A server that is too small can't be selected. Click **1 server cannot run this app** under the server list to see the reason, for example **Needs 2 GB RAM, server has 1.8 GB.**

## Step 3: Add the site title and choose a domain

The **Install Browserless Into** form opens. Browserless has no settings of its own in this form.

1. Enter a **Site Title**, for example `Browserless`. **Add Tag (optional)** helps you group sites.
2. Under **Domain Setup**, choose one:
   - **Demo Site:** xCloud gives you a test domain, shown under **Domain Name**. Click **Regenerate** for a different one. Use this to try Browserless first.
   - **Go Live:** enter your own domain and point its DNS at the server.
3. Click **Next**.

![Demo Site selected under Domain Setup in the Install Browserless Into form](/_landing/docs/deploy-browserless-with-xcloud-image-3.png)

## Step 4: Wait for the setup to finish

xCloud shows a progress page with each stage: checking the server and DNS, installing Docker, setting up the app, SSL, HTTPS, Nginx and monitoring. The Browserless image takes about 3.7 GB of disk, so the download can take a few minutes. You can leave this page; the setup keeps running.

![The Setting Up Your Site progress page with its nine setup stages while xCloud installs Browserless](/_landing/docs/deploy-browserless-with-xcloud-image-4.png)

If a stage fails, open **Recent Events** on the site, click **View** on the failed event, and fix what it reports. If you chose **Go Live**, check your DNS first. Then try again, or contact support with the event output.

## Step 5: Copy your API token

When the setup is done, open the site's **Site Overview** page. The **Browserless Credentials** card shows the **API base URL**, **API token**, **Puppeteer WebSocket URL** and **API docs**. Click **Copy** next to **API token**. Click the eye icon if you want to see it first.

![The API token field on the Browserless Credentials card on Site Overview](/_landing/docs/deploy-browserless-with-xcloud-image-5.png)

The **Puppeteer WebSocket URL** also contains your token, so treat both values like a password. Keep them out of logs, shared files and code that runs in a visitor's browser.

## Step 6: Take your first screenshot

Run this from your terminal. Use your domain in place of `example.com` and your token in place of `YOUR_API_TOKEN`:

```bash
curl -X POST "https://example.com/screenshot?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.org"}' -o example.png
```

You get a PNG of the page in `example.png`. To get a PDF or the page's HTML instead, send the same request to `/pdf` or `/content`.

To send the token as a header instead of in the address, use `Authorization: Bearer YOUR_API_TOKEN`. A request with a missing or wrong token gets `401 Bad or missing authentication.`

## Step 7: Connect Puppeteer or Playwright

Use the **Puppeteer WebSocket URL** from the credentials card in both. It looks like `wss://example.com?token=YOUR_API_TOKEN`.

Puppeteer, with the `puppeteer-core` package:

```js
const puppeteer = require('puppeteer-core');

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://example.com?token=YOUR_API_TOKEN',
});
const page = await browser.newPage();
await page.goto('https://example.org');
console.log(await page.title());
await browser.disconnect();
```

Playwright:

```js
const { chromium } = require('playwright');

const browser = await chromium.connectOverCDP('wss://example.com?token=YOUR_API_TOKEN');
const context = browser.contexts()[0] || await browser.newContext();
const page = await context.newPage();
await page.goto('https://example.org');
console.log(await page.title());
await browser.close();
```

Each script prints the page's title. Run them inside an `async` function. Your own code doesn't need a local Chromium, because the browser runs on your server.

## Find the other API endpoints

Open the **API docs** address from the credentials card. It is your domain followed by `/docs/`, and it is the one part of Browserless you can read without a token. **Browser REST APIs** lists the endpoints such as screenshots and PDFs.

![Browser REST APIs in the menu of the Browserless API docs page](/_landing/docs/deploy-browserless-with-xcloud-image-7.png)

Browserless lists some extras, such as BrowserQL and session replay, under its paid cloud and Enterprise plans. This guide doesn't cover them.

## Change the limits or the token

Open the site in xCloud and click **Environment** in the site menu. Edit the value, then click **Save & Redeploy**. The button becomes active once you edit the file, and the container restarts briefly.

![The Save & Redeploy button on the site's Environment page for Browserless](/_landing/docs/deploy-browserless-with-xcloud-image-6.png)

| Setting | Starts at | What it does |
|---|---|---|
| `TOKEN` | Generated | Your API token. Enter a new value to replace it. The old token stops working after the redeploy, so update your apps too. |
| `CONCURRENT` | `5` | How many browser sessions can run at the same time. Plan for roughly 500 MB of RAM per busy session, so raise this only on a larger server. |
| `QUEUED` | `10` | How many requests can wait for a free session. Requests after that are refused with a `429` error. |
| `TIMEOUT` | `60000` | The longest a session can run, in milliseconds. `60000` is one minute. |

**Never leave `TOKEN` empty.** An empty value turns off the token check, and anyone can then use your browser. Leave the other lines in the file as they are.

## Update and back up Browserless

- **Update:** your site stays on Browserless 2.57.3, because the app's `docker-compose.yml` names that exact version. **App Actions → Update** pulls that same version again. To move to a newer one, read the [Browserless release notes](https://github.com/browserless/browserless/releases), then find that version and its `sha256:` digest on the [Browserless image page](https://github.com/browserless/browserless/pkgs/container/chromium). Open the **Compose** page, as described in [Update a One Click App and edit its Docker Compose](/docs/update-a-one-click-app-and-edit-its-docker-compose-in-xcloud/), and replace both on the `image:` line.
- **Back up:** Browserless keeps no data, so there is nothing of its own to restore. Your token and limits are in the site's environment file. To keep a copy of your settings, see [Back up and restore Docker apps](/docs/backup-and-restore-docker-apps/).

## Common mistakes

- Opening the site address and thinking the install failed. The site root, which **Visit Site** opens, returns `404` because Browserless has no dashboard. Use `/docs/` or send a request with your token.
- Sending a request without the token. It gets a `401` error, except on `/docs/`.
- Forgetting to update your apps after you change `TOKEN`. Copy the new value from the credentials card.
- Raising `CONCURRENT` on a small server. Heavy pages can then run the server out of memory.
- Keeping the old address in your code after you [go live from the demo site](/docs/how-to-go-live-from-demo-site/). Use your new domain in your code.

## Frequently asked questions

### Do I need to write a Docker Compose file to deploy Browserless on xCloud?

No. The Browserless One Click App already defines the container and generates the API token. You pick Browserless in the app catalog, choose a server, enter a site title, choose Demo Site or Go Live, and click Next.

### What server does Browserless need on xCloud?

An Nginx server. xCloud installs Docker on it if it isn't there yet. An existing server needs at least 2 GB RAM, 2 CPU cores and 8 GB of free disk. The install page shows this as **Recommended: 2 GB RAM · 2 vCPU · 8 GB disk**.

### Why does my Browserless site show a 404 page?

That is normal. Browserless has no dashboard, so the site root returns 404 even with a valid token. Open /docs/ on your domain to read the API docs, or send a request with your token to check that it works.

### Can I use Browserless for a commercial project?

It depends on the licence you choose. As of November 2026, Browserless is licensed under SSPL-1.0 or a commercial licence. Browserless says closed-source commercial sites, applications and CI pipelines need a commercial licence from browserless.io. The One Click App does not include one. This is not legal advice.

## Related guides

- [Use One Click App templates in xCloud](/docs/how-to-use-one-click-app-templates-in-xcloud/)
- [Update a One Click App and edit its Docker Compose](/docs/update-a-one-click-app-and-edit-its-docker-compose-in-xcloud/)
- [Back up and restore Docker apps](/docs/backup-and-restore-docker-apps/)
- [Go live from a demo site](/docs/how-to-go-live-from-demo-site/)

If you run into any issues while deploying Browserless, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/).