A self-hosted browser automation API lets your application control browser processes running on infrastructure you manage, usually through REST endpoints or a browser protocol such as Chrome DevTools Protocol (CDP) over WebSocket. It can keep browser traffic and captured page data within your network boundary, but you take responsibility for endpoint security, capacity, updates, and reliability. Browserless is one documented example—not a template for every self-hosted service.
What a self-hosted browser automation API does
Ordinary browser automation runs a browser alongside the code that controls it. A browser automation API separates those roles: a browser server runs elsewhere, and your application sends it work over a network. Depending on the product, the client may call REST endpoints for tasks such as screenshots or PDFs, or connect to a browser over WebSocket using CDP, Playwright, or Puppeteer.
In a self-hosted deployment, that browser server runs in infrastructure your organization controls: for example, a cloud account, private network, on-premises environment, or Kubernetes cluster. Your application still needs network access to the service. Self-hosting changes who operates the browser infrastructure; it does not automatically mean the browser runs on the same machine as your app or that all browser activity is isolated from the public internet.
Browserless describes its open-source Docker image as a headless browser server for Puppeteer and Playwright. Its image includes browser options such as Chromium, Chrome, Firefox, WebKit, and Edge, plus a multi-browser image. Its documentation lists Linux/amd64 and Linux/arm64 support, with Chrome and Edge available only on amd64; the ARM multi image includes Chromium, Firefox, and WebKit. See the Browserless open-source Docker deployment documentation for the currently documented image and setup details.
#1 Best Overall
When running browser automation yourself makes sense
The strongest reason to self-host is control over where browser sessions run and how they reach other systems. That may matter when a browser must access internal applications, traffic must stay within a VPC or on-premises network, or your team needs to apply its own network policies. Browserless describes its self-hosted sessions as staying in the customer’s infrastructure; that is the vendor’s description, not an independent audit.
Self-hosting is less attractive when you do not want to operate browser processes as a service. Browser workloads are resource-intensive and variable: a page with heavy scripts, large images, or long-running requests can consume more time and memory than a simple page. You must account for concurrency, queuing, timeouts, monitoring, scaling, browser updates, and recovery from failed sessions.
- Consider self-hosting when data location, internal network access, or direct control of infrastructure is a firm requirement and your team can operate the service.
- Consider a managed service when you prefer not to patch, scale, secure, and monitor browser infrastructure yourself, or when you need vendor-managed proxy capabilities.
- Check the exact deployment when a workflow depends on a particular endpoint, browser, protocol, proxy, or license. A vendor’s cloud feature set may not be available in its self-hosted image.
How to run Browserless in Docker
Browserless provides an open-source Docker image through GitHub Container Registry. Its quickstart shows the basic pattern: start the service, publish its port, set a token, and connect a compatible client. The example below uses the documented Browserless image name and environment-variable pattern; confirm the current image tag and browser variant in the vendor’s deployment guide before using it in production.
1. Start the browser service with authentication
For a local development setup, the command pattern is:
docker run -d
--name browserless
-p 3000:3000
-e TOKEN=replace-with-a-long-random-secret
-e CONCURRENT=5
ghcr.io/browserless/chromiumUse a randomly generated secret rather than the example value, and store production credentials in your deployment’s secret manager. Browserless warns: “If you don’t set TOKEN, Browserless does not generate one for you.” Without a token, endpoints—including /function—remain unauthenticated. Do not expose the service to an untrusted network without authentication and suitable network controls.
The example sets a concurrency limit of five as a configuration illustration, not a capacity recommendation. The right limit depends on the workload and the machine. In a production deployment, restrict inbound access to trusted clients, terminate public TLS at an appropriately configured gateway or reverse proxy, and avoid publishing the browser port broadly.
2. Connect a Playwright client over CDP
Browserless documents a Playwright connection over CDP. The following Node.js example uses Playwright’s CDP connection method and a tokenized endpoint. Install the client package with npm install playwright; use the matching Browserless browser image and endpoint for the browser you selected.
const { chromium } = require('playwright');
const token = process.env.BROWSERLESS_TOKEN;
if (!token) throw new Error('Set BROWSERLESS_TOKEN');
(async () => {
const browser = await chromium.connectOverCDP(
`ws://localhost:3000?token=${encodeURIComponent(token)}`
);
try {
const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
const page = await context.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded', timeout: 30000 });
await page.screenshot({ path: 'example.png', fullPage: true });
await context.close();
} finally {
await browser.close();
}
})();For a remote deployment, replace localhost with the service hostname and use wss:// when the connection is protected by TLS. Keep the token out of source control, logs, and client-side code. Browserless emphasizes matching the Docker image, browser type, and endpoint when connecting Playwright; its GitHub documentation provides connection guidance.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute3. Use REST when the task is an API operation
Browserless’s API reference covers REST endpoints as well as WebSocket connections for CDP, Playwright, and Puppeteer. REST responses can be JSON or binary content, depending on the endpoint. In its self-hosted Enterprise documentation, the deployment host and port default to http://localhost:3000, with the token configured through TOKEN. Consult the Browserless API reference for the endpoint, request format, and response type needed by your workflow.
Do not assume a route documented for Browserless cloud exists in a self-hosted image. In particular, verify endpoint availability and license terms before designing an application around a feature.
Secure the endpoint and its network access
A browser server is a powerful networked component: it can visit URLs, execute page JavaScript, and potentially reach services visible from its host. Authentication is necessary, but it is not the entire security model. Apply network restrictions so only authorized applications can reach the service, and consider what destinations a submitted URL should be allowed to access.
- Set a strong
TOKENand rotate it if it is exposed. - Do not leave an unauthenticated endpoint reachable from the internet or an untrusted network.
- Use a reverse proxy or gateway for TLS and access controls where appropriate; Browserless’s self-hosting guidance recommends a reverse proxy.
- Disable unused features and protect tokens and keys, as Browserless advises in its self-hosting guidance.
- Restrict network egress or apply URL validation if users can submit arbitrary destinations. This reduces the risk that browser jobs reach internal services they should not access.
- Keep browser images and the host runtime updated, and monitor service health and resource use.
Browserless Enterprise describes controls for network policies and configuration. The exact security options vary by deployment and license; review the documentation for the edition you plan to run rather than assuming every control applies to the open-source image.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Understand feature and licensing boundaries
Browserless distinguishes shared cloud, private deployment, and self-hosted Docker. The vendor operates the shared cloud and private deployments; with self-hosted Docker, the customer operates the infrastructure. Browserless says managed residential proxies are included in cloud and private options, while self-hosted customers bring their own proxy.
Browserless identifies these six advanced REST endpoints as cloud-only: /unblock, /smart-scrape, /search, /map, /crawl, and /agent/run. It points to /scrape for structured extraction and /content for rendered HTML as self-hosted alternatives. Verify the current endpoint list against the Browserless product and deployment information before committing to an architecture, because availability is specific to deployment and offering.
Licensing also affects whether self-hosting is appropriate. Browserless says its open-source image is licensed under SSPL-1.0 and is free for open-source projects, prototyping, and evaluation; it says closed-source commercial products or closed-source CI use require a commercial license. The vendor describes separate commercial-license and Enterprise offerings, with differing use rights and features. These descriptions are not a substitute for reading the applicable license: confirm the precise terms for your use, and ask the vendor if the boundary is unclear.
Plan capacity, queues, and reliability
Browserless publishes illustrative self-hosted sizing guidance, not independent benchmark results. Its undated product guidance, accessed in 2026, pairs 5–10 concurrent sessions with 2 CPU and 4 GB RAM; 10–20 sessions with 4 CPU and 8 GB RAM; and 20–50 sessions with 8+ CPU and 16+ GB RAM. Actual capacity depends on page complexity, wait behavior, browser choice, memory limits, and the mix of concurrent jobs.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Browserless illustrative concurrency | Vendor’s suggested resources | How to interpret it |
|---|---|---|
| 5–10 sessions | 2 CPU · 4 GB RAM | Undated Browserless sizing guidance accessed in 2026; not an independently tested benchmark. |
| 10–20 sessions | 4 CPU · 8 GB RAM | Undated Browserless sizing guidance accessed in 2026; validate against your workload. |
| 20–50 sessions | 8+ CPU · 16+ GB RAM | Undated Browserless sizing guidance accessed in 2026; validate against your workload. |
Set realistic navigation and job timeouts, cap concurrency, and decide what should happen when a queue is full. Browserless documents controls for concurrency and timeouts, and describes load balancing across containers. These mechanisms can help distribute work, but they do not remove the need to size the whole deployment or define behavior when a browser or container fails. Track queue depth, job duration, timeouts, process restarts, and memory pressure so capacity problems can be distinguished from target-site failures.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common deployment problems
Connection refused or the client cannot reach the service
Check that the container is running, its port is published, and the client is using the correct hostname and port. From another machine, localhost means that machine, not the Docker host. Confirm firewall, routing, and reverse-proxy rules as well.
Unauthorized requests or token failures
Check that the client sends the token in the format required by the endpoint and that the value matches the container’s TOKEN. Avoid including unescaped token characters in a URL; encode query parameters. If you changed a secret, ensure the service and client were both updated.
Playwright reports a protocol or browser error
Verify that the client method matches the server endpoint and protocol, that the selected image includes the intended browser, and that the connection path follows the corresponding Browserless documentation. A CDP connection is not interchangeable with every generic WebSocket route.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Jobs time out or the queue grows
Separate slow target pages from server saturation by checking job duration alongside CPU, memory, and queue depth. Adjust navigation waits and timeouts to fit the page, reduce concurrency if the host is under pressure, or add capacity and distribute work. More concurrency can worsen latency when the machine is already resource-constrained.
A cloud API route returns an error in self-hosted mode
Confirm whether the route is supported by your self-hosted edition. The six cloud-only routes listed above are not made available merely by running the browser image yourself; use a documented self-hosted alternative where it meets the need, or select a deployment that includes the required capability.
When you only need screenshots, PDFs, or a capture API
If your requirement is a screenshot endpoint rather than a browser server you operate, ScreenshotNeo is a managed website screenshot API and MCP server. A single GET request accepts a URL and returns a PNG, JPEG, WebP, or PDF. The example below uses cURL; the API details and supported parameters are in the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpEquivalent Python and Node.js examples:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo is an alternative to operating a general-purpose browser server when your task is capture. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletters, and chat widgets; those cleanup steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. It also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to try it without a credit card.
Decide using your constraints, not just the API
Before deployment, list the network boundaries, browser protocols, REST routes, proxy needs, expected concurrency, and license requirements your application actually has. Self-hosting is a sound fit when control over infrastructure outweighs the cost of operating it. If what you need is a capture endpoint rather than control of browser processes, a managed screenshot API may be the simpler fit.
Frequently Asked Questions
Can I self-host Browserless?
Yes. Browserless documents an open-source Docker image for self-hosted browser automation. The image, supported APIs, and licensing terms depend on the deployment and use case.
Does self-hosting Browserless include its cloud-only REST endpoints?
No. Browserless identifies six advanced REST endpoints as cloud-only; check its current deployment documentation for availability.
Free tools Windows power users keep installed
One-click scans. No signup required.
Can I connect Playwright to a self-hosted browser server?
Browserless documents Playwright connections over CDP. Match the client method, image, browser type, and endpoint, and follow the deployment-specific connection guidance.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
