Scrape.ly Browser

The Scrape.ly browser is a hosted Chromium your Actor's browsers can run on instead of inside the run container. It has anti-bot fingerprinting, solves Cloudflare Turnstile challenges, and routes traffic through its own residential proxy.

It's off by default. You turn it on per Actor, rebuild, and your Playwright or Puppeteer code connects to it without changes.

Turn it on

11. Enable it for the Actor

In the dashboard, open the Actor and go to Settings → Scrapely Browser. Turn on Use Scrapely browser and confirm. Only the Actor's owner can change it.

Or with the API:

curl -X PUT "https://api.scrape.ly/v2/actors/<actorId>/browser-patch" \
  -H "Authorization: Bearer $SCRAPELY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"browserPatchEnabled": true}'

22. Rebuild

The setting is applied when the Actor is built, so start a new build: scrapely push, Builds → Build, or the build API. Existing builds keep working as they were.

33. Run it

Runs of the new build connect every browser launch to the Scrape.ly browser. The build log shows which mode a build uses:

[Scrapely Build] Browser patch: on (remote browser)

On and off at a glance

Builds made before this setting existed have browserPatched: null and count as on. Rebuild with the setting off to move them to local browsers.

What changes in the build

With the setting on, the build:

• Removes browser binary downloads from the Dockerfile: playwright install, pyppeteer-install, PLAYWRIGHT_BROWSERS_PATH downloads, Puppeteer's postinstall download, and Apify's check-playwright-version.mjs guard. The Playwright and Puppeteer packages and OS-package browsers (apt-get install chromium) stay.
• Replaces each playwright install with mkdir -p of the browsers directory (PLAYWRIGHT_BROWSERS_PATH, else Playwright's default), so later steps that touch it, such as chmod -R a+rX /ms-playwright, still work.
• Makes sure the image loads the redirect. scrapely/actor-node* and scrapely/actor-python* images already do, through NODE_OPTIONS and sitecustomize. Other images get a small preload for Node.js or Python and nothing else.
• Never edits your stored source.

It works the same whether the account-level Transform actors setting is on or off.

What gets redirected

On the platform, the SDK patches every launch path so it connects to the browser in CDP_URL: Playwright uses chromium.connectOverCDP(), Puppeteer uses puppeteer.connect({ browserWSEndpoint }). Actors that never import the SDK are covered too, through the image preload.

Choose the location and fingerprint

The Scrape.ly browser never takes a proxy URL. Pick where its traffic exits, and how it looks, with a browser configuration:

import { Actor, PlaywrightCrawler } from 'scrapely';

await Actor.main(async () => {
    const browserConfiguration = await Actor.createBrowserConfiguration({
        countryCode: 'US',
        state: 'California',
        os: 'windows',
    });

    const crawler = new PlaywrightCrawler({
        browserConfiguration,
        async requestHandler({ page }) {
            await Actor.pushData({ title: await page.title() });
        },
    });
    await crawler.run(['https://example.com']);
});

• Input aliases. Pass your Actor input straight in: browserCountry, browserState, and browserCity fill countryCode, state, and city. Explicit options win.
• Precedence. The location comes from the browser configuration, then the country and subdivision of a platform ProxyConfiguration on the crawler, then the run default.
• Validation. Invalid values throw (JavaScript) or raise ValueError (Python) when you create the configuration, before any browser starts.
• Sessions. Proxy groups and session IDs don't apply. Each browser connection is a fresh browser session, and the first page that launches a browser fixes its location.
• Same code everywhere. The option is accepted locally and in builds with the setting off, and ignored there.

Connect over CDP yourself

Every run gets CDP_URL, whatever the setting. Connecting to it directly uses the Scrape.ly browser even in a build with the setting off, and bills browser credits:

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(process.env.CDP_URL);

To set the location on a direct connection, add the CDP URL parameters from the table above to the URL.

• The URL identifies the run. The browser accepts it only while the run is READY, RUNNING, ABORTING, or TIMING-OUT, and only if the account running the Actor has a positive balance.
• It carries the run's default exit country as proxy_country (US).

Pricing

The Scrape.ly browser is billed in browser credits, on top of the run's compute units.

• Who pays: the account that runs the Actor. For a Store Actor that's the user, not the developer.
• What counts: session time in 30-second blocks (rounded up, at least one block) and the browser's proxy traffic per MB (rounded up, at least 1 MB). That traffic is part of the credits and is never billed again as proxy GB.
• Price: your price per credit is under Billing → Pricing.
• Spending cap: browser credits count toward the run's maxTotalChargeUsd. When the cap is reached, the run is stopped.

Where to see it:

Local runs

• scrapely run and other local runs have no CDP_URL, so browsers launch on your machine, as in plain Crawlee. The browser configuration is ignored.
• setCdpUrl(url) (JavaScript) or set_cdp_url(url) (Python) points the SDK at a CDP endpoint you run yourself. The Scrape.ly browser only accepts connections from platform runs.

Troubleshooting

Related: Browser patch API, JavaScript environment, Python environment, Proxy.