SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-10-19

How to Run Headless Chromium for AI Agents on VPS

Headless Chromium for AI agents fit fail from small /dev/shm, sandbox flags, missing fonts, or leaked processes. Set limits and protect the control endpoint.

Wetin you dey run

Headless browser for VPS na Chromium wey no get window, and your code dey control am instead of person. For server, na long-running process tree wey your agent dey talk to through local socket. To install am na one command. The real work na everything wey come after that. You go limit wetin browser fit collect from the machine, and you go keep the control endpoint away from public internet.

This guide assume say you don already choose the tool and now you need operate am. If you still dey compare crawlers and extractors, start with self-hosted Firecrawl alternatives then come back. Everything below dey use Playwright's Chromium, because Playwright ships its own browser build and its own dependency installer. So, the same commands dey work for bare Ubuntu VPS and inside container. The commands pin Playwright 1.62, wey be the release wey dey current for August 2026.

Install Chromium without guessing at dependencies

npm i -D playwright@1.62.0
npx playwright install --with-deps chromium

--with-deps dey run apt for the shared libraries and fonts wey Chromium need, and e go ask for root when e reach there. The browser build itself dey download go ~/.cache/ms-playwright for the user wey run the command. This matter for server, because service user usually no be the user wey you dey log in as. Install the system packages once as admin with sudo npx playwright install-deps chromium, then set PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers for both the install command and the service unit so everybody fit share one copy. Service wey no fit see its browser go fail for launch with message wey name the path wey e search.

Pin the Playwright version. Each release dey tied to one browser build, so unpinned npm update fit change the browser under service wey dey run. Playwright 1.62 dey current for August 2026. As of October 17, 2026 the latest release na 1.64.1, so read the release notes before you move the pin. For ARM64 servers, note say 1.63 rename the browser folders, and this matter for the AppArmor profile wey dey further down.

Two Chromium builds dey exist, and dem no be the same program. For headless mode, Playwright dey use the headless shell by default. Na smaller binary wey only fit run headless. Plain install dey download am beside the full browser, while npx playwright install --with-deps --only-shell dey install only the shell. The full browser na wetin you get with the chromium channel, wey Playwright's browser docs call "the real Chrome browser, and is thus more authentic, reliable, and offers more features". Use the shell for bulk fetching. Use the full browser when site dey behave differently and you need find out why.

Why headless browser dey crash for container

Docker dey give each container 64 MB /dev/shm. Docker documentation talk am clearly: "If you omit the size entirely, the system uses 64m". Chromium dey pass rendered content between its processes through that shared memory area, so one heavy page fit fill am. Renderer go then die, and your client go report say target crash, even though the page dey work fine for your laptop. Confirm the size from inside the container before you change anything.

df -h /dev/shm

Two real fixes dey, and dem na alternatives, no be pair wey you need use together. --ipc=host go put the container for host IPC namespace, so e go use the host's /dev/shm, wey normally be half of RAM. Playwright's Docker guide recommend am, because without am "Chromium can run out of memory and crash". The cost be say you lose IPC isolation between container and host. --shm-size=1g keep the private namespace and simply make the mount bigger.

docker run --rm -it --init --ipc=host --user pwuser mcr.microsoft.com/playwright:v1.62.0-noble /bin/bash

The --disable-dev-shm-usage flag na the answer wey you go find for most search results, but e dey do something different: e move those files from /dev/shm go temporary directory. If /tmp dey on disk, you don change crash to slower rendering and disk writes. If /tmp na tmpfs, the data go return to RAM, and the limit na only the tmpfs size limit. The kernel documentation set that limit by default to half of physical RAM, and tmpfs pages fit move go swap. Na one way browser fit chop small VPS. Set /dev/shm properly instead.

Wetin --no-sandbox really cost

Chromium dey isolate every renderer inside sandbox wey dey use Linux user namespaces. That sandbox na the boundary between hostile page and your server. When e no fit start, Chromium refuse to run, and the log get line like this:

Failed to move to new namespace: PID namespaces supported, Network namespace supported, but failed: errno = Operation not permitted

The usual advice na --no-sandbox. Chromium security pages talk plainly about the price: "We do not encourage this as it will significantly reduce your security, and may prevent Chromium from working properly." Agent wey dey follow links dey browse open web by definition, and na exactly there dem go test that reduced security. Find the real cause.

Two causes dey cover almost every case. Running browser as root disables the sandbox, because e no fit drop privilege wey e already get. Na why Playwright image ship with ordinary user called pwuser. For Ubuntu 24.04 and later, AppArmor dey restrict unprivileged user namespaces, and e go deny Chromium binary for path wey no shipped profile cover. Playwright download under ~/.cache/ms-playwright na exactly that kind path. Check both:

id -u
sysctl kernel.apparmor_restrict_unprivileged_userns
sudo dmesg | grep -i userns_create

A 1 from sysctl plus kernel line wey contain apparmor="DENIED" operation="userns_create" confirm the second cause. Allow that one binary inside /etc/apparmor.d/pw-chromium. This one keep the restriction active for everything else on the box:

abi <abi/4.0>,
include <tunables/global>

profile pw-chromium /{home/*/.cache/ms-playwright,opt/pw-browsers}/*/chrome-*/{chrome,headless_shell,chrome-headless-shell} flags=(unconfined) {
  userns,
}

Load am with sudo apparmor_parser -r /etc/apparmor.d/pw-chromium. For x86-64, Playwright dey put the complete browser for chrome-linux64/chrome and the shell for chrome-headless-shell-linux64/chrome-headless-shell. For ARM64, Playwright 1.62 and earlier use one chrome-linux folder wey hold both chrome and headless_shell. From 1.63, ARM64 follow the x86-64 pattern with chrome-linux-arm64/chrome and chrome-headless-shell-linux-arm64/chrome-headless-shell. The chrome-* glob cover all these layouts, and the /opt/pw-browsers branch cover shared install wey dem make with PLAYWRIGHT_BROWSERS_PATH. The path still hold browser revision, so e change every time you upgrade Playwright. The globs above go continue to work across that change. Profile wey you write against one exact path fit silently stop matching, and browser go start failing again after update wey look unrelated.

Why screenshots dey blank or full of boxes

Blank screenshot, or one wey full of empty rectangles, normally na font problem, no be rendering bug. install-deps dey pull working base: fonts-liberation, fonts-freefont-ttf, fonts-noto-color-emoji, fonts-unifont, fonts-ipafont-gothic for Japanese, fonts-wqy-zenhei for Chinese, fonts-tlwg-loma-otf for Thai. Noto CJK no dey inside that set, so Korean and some other scripts go fall back to any font wey fontconfig fit find. Ask fontconfig instead of guessing:

fc-match "sans-serif:lang=ko"
fc-match "sans-serif:lang=ar"
fc-list | wc -l

If language wey you need resolve to unifont or fallback wey no get real glyphs, install fonts-noto-core and fonts-noto-cjk, then run the check again. Fontconfig dey cache its results, so restart the browser after you install fonts. Stripped image wey no get fonts at all dey log Fontconfig error: Cannot load default config file when e start, and e render every page empty.

Locale and time zone dey separate from fonts, and dem change wetin page talk, no be only how e look. Container normally get LANG unset and TZ for UTC, so sites go serve English and print UTC timestamps, while your agent go report times wey no match wetin person for that country dey see. Set dem per browser context instead of per machine, so one browser fit serve tasks for different regions.

const context = await browser.newContext({
  locale: 'en-GB',
  timezoneId: 'Europe/Paris',
});

Wetin make leaked browser processes push the box go swap

Two different problems dey share the name "zombie". True zombie na process wey don finish but e parent never call wait(). E hold PID entry and nothing else, so e no dey use memory. You go collect dem when browser dey run as PID 1 for container, because PID 1 no get default reaper. Docker --init flag fix exactly this one, by running small init wey "forwards signals and reaps processes". For Compose, na init: true be the same thing.

The leak wey really dey push your box go swap different: na live Chromium processes wey nobody close. E fit happen when task throw error between newContext() and close(), or when person kill the controlling script and e leave browser tree orphaned. The worst case na code wey dey launch fresh browser for every request. Count dem:

pgrep -c -f 'headless_shell|chrome'
ps -eo pid,ppid,rss,etime,comm --sort=-rss | head -20

That count suppose return to e idle value between tasks. If e dey increase over one day, the fix dey inside your code, no be for launch flags: close the context inside finally block, close the browser for SIGTERM, and recycle the browser after fixed number of tasks instead of making one run for one month. Under systemd, stop or restart dey kill everything for the unit cgroup, so sudo systemctl restart browser.service na reliable reset. Browser wey person start by hand inside terminal multiplexer no get this guarantee, and e orphans go outlive the session.

How much RAM one browser context need

Ask the question well, because “one browser” no be one process. Chromium dey run browser process, GPU process, utility processes, and one renderer process for each site. Site isolation still gives cross-site iframes their own renderer. A BrowserContext na separate cookie jar and storage area inside that same process tree, so second context cheap. Second page no be cheap, because e starts renderer processes, and page wey get plenty ads fit start several.

So wetin you need measure na peak memory for the whole process tree under your own workload. Figure from another person blog no get value here, because na the pages wey your agent opens go decide the answer. Measure for the machine wey you go use, against the sites wey you go visit:

sudo systemd-run --unit=browser-probe -p MemoryMax=2G -p MemorySwapMax=0 -p WorkingDirectory=/srv/agent /usr/bin/node worker.js
systemctl status browser-probe

For Ubuntu 24.04, the Memory: line for that output dey report both current and peak use for the unit. Run the worker with one page at a time, record the peak, then repeat with two pages open to see the real cost of second page. Concurrency na arithmetic: take total RAM, subtract wetin the rest of the machine need, keep few hundred MB headroom, then divide by the measured peak per worker. To size the machine underneath this setup, see how much RAM and CPU agent VPS need.

Enforce that number for two places. For your code, use fixed worker pool or semaphore, so burst of agent requests go queue instead of launching browsers. For the OS, use cgroup limit, so bug for the queue no go bring the machine down with am:

[Service]
MemoryMax=2G
MemorySwapMax=0
TasksMax=512
Restart=always

MemorySwapMax=0 matter pass wetin e first look like. Without am, the cgroup fit push pages go swap as e dey near the limit. The machine fit remain up, but every request go slow, and that one hard to diagnose pass clean failure. Swap only dey delay the end: systemd documentation talk say if usage “cannot be contained under the limit, out-of-memory killer is invoked inside the unit”. If swap cap na zero, this go happen as soon as browser process tree reach MemoryMax, systemd go restart the unit, and sshd go survive. The same controls for Compose na mem_limit, shm_size and init, and setting memory limits in Docker Compose cover dem.

Keep the browser endpoint off the public internet

Playwright fit run the browser as a server and give your agent one WebSocket URL:

const { chromium } = require('playwright');
const server = await chromium.launchServer({ port: 3000 });
console.log(server.wsEndpoint());

That endpoint no get login. Playwright API documentation talk am directly: "Any process or web page (including those running in Playwright) with knowledge of the wsPath can take control of the OS user." The default host na localhost, "accepting connections only from the loopback interface", and the docs warn say if you pass an explicit address like 0.0.0.0, e "exposes the browser RPC to anything that can reach the listening port". Chrome own --remote-debugging-port worse. The DevTools protocol no get any authentication and e depend completely on binding to loopback.

Check wetin you actually publish, and check am from another machine plus the VPS:

ss -ltnp

Anything wey dey on a browser port bound to 0.0.0.0 na a finding. Remember say most providers get separate network firewall for their control panel, and your ufw rules no know anything about am. Reach the endpoint from another machine through an SSH tunnel or private VPN instead:

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

The risk here pass person stealing browser time. Browser wey you fit control na request-forgery machine wey dey inside your network. Anybody wey reach that socket fit make am fetch http://127.0.0.1:8080, your database admin page, or the cloud metadata address for 169.254.169.254, then read the response from the page. Your firewall go see request wey come from the VPS itself, and e allowed. Treat the control endpoint like shell access on that box.

MCP servers get the same pattern. npx @playwright/mcp@latest --headless --port 8931 serve over HTTP on localhost, and --host 0.0.0.0 na the flag wey turn local tool into public one. The project README talk am plainly: Playwright MCP "is not a security boundary". Keep the port on loopback and make the agent reach am through the same tunnel.

Pages wey your agent dey read na untrusted input

Agent wey dey browse open web dey feed text wey strangers write into model wey still dey hold your instructions. Page fit carry text wey dem address to the model, tell am make e abandon the task, call tool, or post data go URL. The model receive both as text, so e no get reliable way to know whether na page words or your own instructions. Design the setup so hostile page get small thing to work with.

  • Run the browser under its own OS user, without SSH keys and cloud credentials for its environment.
  • Use fresh context for every task, and --isolated with Playwright MCP, so session for one site no dey available to the next page.
  • Keep origin allowlist where the job allow am. Playwright MCP dey take --allowed-origins and --blocked-origins as semicolon-separated lists.
  • Require human step before any action wey go change state, like sending mail or spending money.

Better still, keep the whole browser for machine wey you fit throw away and rebuild. Na the same reason as running coding agents for disposable VM. If the agent's real job na search instead of open-ended browsing, narrower tool dey safer than full browser: search skill wey your own SearXNG dey back dey return results without ever loading the hostile page.

FAQ

Chromium dey crash for Docker but dey work fine for the same VPS directly, why?

Because container get 64 MB /dev/shm by default, while host get much bigger one. Chromium dey pass rendered content through that shared memory area, so heavy page fit fill am and renderer go die. Run df -h /dev/shm inside container to confirm, then start am either with --ipc=host, wey dey use host shared memory, or with --shm-size=1g, wey dey make the container own shared memory bigger. --disable-dev-shm-usage only move the problem go /tmp.

--no-sandbox safe if VPS no dey run anything else?

No. Sandbox na wetin dey stop malicious page from reaching the rest of the machine, and Chromium security pages talk about the flag say: "We do not encourage this as it will significantly reduce your security, and may prevent Chromium from working properly." Agent wey dey follow links dey browse open web. Fix the cause instead: no run browser as root, and for Ubuntu 24.04 add an AppArmor profile wey get userns, for browser binary path, so unprivileged user namespaces fit work for that one program.

How many browsers I fit run for small VPS?

Measure am; no just copy number. Chromium dey start one renderer process for each site, so answer depend on the pages wey you open. Run one worker under systemd-run with MemoryMax set, read the peak from the Memory: line inside systemctl status, then divide your free RAM by that peak and keep headroom. Enforce the result two times: use queue for your code and MemoryMax for the unit file, so burst of requests go wait instead of making the machine swap.

My agent fit connect to browser from another machine?

Yes, but never bind the port to 0.0.0.0. Playwright server endpoint and Chrome DevTools port dey accept any client wey fit reach dem, with no password. Keep listener for 127.0.0.1 and carry the connection through SSH tunnel or private VPN. Verify with ss -ltnp for server and check the port from outside. Also check your provider separate network firewall.

Why my screenshots blank when page clearly don load?

Missing fonts. If no font cover the page script, text go render as empty boxes or no render at all, so page wey get mostly images go come back looking blank. Run fc-match "sans-serif:lang=ko" for each language wey you scrape, install fonts-noto-core and fonts-noto-cjk when answer na generic fallback, then restart browser so fontconfig fit reload its cache. Container wey no get any font at all dey log Fontconfig error: Cannot load default config file for startup.

Dis article help you?

#headless-browser#playwright#chromium#ai-agents#automation