Skip to content
apiscreenshotGitHub
← Blog

Self-hosting a screenshot API with Docker

A self-hosted screenshot API is one container with a real Chromium inside. What decides how far it goes is CPU, not memory: on 15 Nov 2026 we ran this API’s server against 18 real sites and each full-page shot cost about 13 CPU-seconds and 230 MB of RAM. And a real Chrome on your own box is no free pass past bot walls: on a list of 28 URLs the server got a clean shot of 19 at the first try, where our Cloudflare install got 23.

The numbers below come from our own runs. How we measured is at the end.

Run it

This starts the API on port 3000 with a key of your own:

API_KEY=$(openssl rand -hex 32); echo "Your API key: $API_KEY"
docker run -d --restart unless-stopped -p 3000:3000 -e API_KEY="$API_KEY" \
  -v api-screenshot-cache:/var/cache/api-screenshot \
  ghcr.io/matbrons/api-screenshot

The image runs on amd64 and arm64 and holds Node, Chromium and fonts for most scripts and emoji. The volume keeps the cache of finished shots when you replace the container; leave it out if you don’t need it.

Take a shot:

curl -H "Authorization: Bearer $API_KEY" \
  "http://localhost:3000/screenshot?url=https://www.theguardian.com/international&full_page=true" \
  -o shot.png

Without API_KEY the server refuses every shot with not_configured. A key under 16 characters is refused too. That matters on a VPS: a screenshot API on an open port is a free browser for anyone who finds it.

How many shots one box handles

On our machine (a shared server with 16 vCPUs and 31 GB of RAM, Chrome 157; details below) the server took 6.7 full-page shots a minute one at a time, 11.9 with two at once and 19.3 with four. Each step up added about 230 MB of RAM and the same 13 CPU-seconds per shot. So the cores run out first.

Shots at once Shots a minute Median seconds a shot RAM in use, median (peak) CPU cores busy
1 6.7 8.1 535 MB (1.5 GB) 1.4
2 11.9 9.1 774 MB (1.7 GB) 2.5
4 19.3 9.6 1.2 GB (2.0 GB) 4.5

Same 18 URLs at each level, all full-page, all 18 clean every time. With nothing to do, the server and its browser hold 320 MB.

Two things stand out:

  • A shot uses more than one core. Chromium lays out, scrolls and paints on several threads, so one shot at a time kept 1.4 cores busy. Stripe’s homepage alone took 48 CPU-seconds for a 16-second shot.
  • The peak is set by the heaviest page, not the average. Most shots added 200 to 300 MB. Shopify’s homepage, 10,206 px tall, briefly took the total to 1.5 GB with only one shot running.

What that means for a 2 vCPU, 4 GB VPS

This is an estimate from the numbers above, not a run on such a server. At 13 CPU-seconds a shot, two cores give at most about 9 full-page shots a minute (2 × 60 ÷ 13), and in practice fewer, a few hundred an hour. Memory is not the limit: two shots at once peaked at 1.7 GB here, well inside 4 GB.

So keep MAX_CONCURRENCY at its default of 2 on a box like that. Raising it to 4 adds no throughput when the cores are already full. It only makes each shot slower and brings more of them near the 30-second timeout.

Shots from the cache cost no browser at all. A repeated request within a day (the default cache_ttl) comes back at once with x-cache: HIT.

Same URLs, Cloudflare and Docker side by side

We sent the same 28 URLs to our Cloudflare install and to the server, one at a time, full page, cache off. Cloudflare’s browser announces itself as a bot to every site, with signed headers, from Cloudflare’s addresses. The server runs a desktop Chrome from its own data-centre address. Here is what came back:

Site Cloudflare Server
example.com, MDN, Python docs clean clean
Wikipedia clean blocked: rate_limited (clean on a retry 20 minutes later)
Hacker News clean error_page: HTTP 503, twice
Notion, Shopify, HubSpot, Allbirds, Zalando, GitHub, Stripe, Apple, Vercel, Linear, BBC, The Guardian, Le Monde, Spiegel, CNN clean clean
Reddit blocked: captcha blocked: access_denied
Medium blocked: bot_check blocked: captcha
G2 clean blocked: captcha
Forbes blocked: captcha blocked: captcha
Zillow blocked: captcha blocked: captcha
IKEA clean blocked: bot_check
The New York Times blocked: captcha timeout (clean on a second try)
Walmart clean clean
Clean 23 of 28 19 of 28 (21 with a second try)

On the 18 pages both shot clean, the server took a median 8.8 seconds a shot and Cloudflare 11.4.

A blocked answer is HTTP 422 with a reason. The API never returns a picture of a captcha with a 200, so you can tell a missing shot from a real one in code.

Cloudflare came out ahead on this list, which we didn’t expect. Neither got past Reddit, Medium, Forbes or Zillow. G2 and IKEA let Cloudflare’s browser through and turned the server away, and Wikipedia and Hacker News refused the server’s address but not Cloudflare’s. The server got the New York Times on a second try, where Cloudflare got a captcha. Both shot Walmart clean, though it shows a press-and-hold check to many automated browsers.

So sites judge the address as much as the browser. Ours is a data-centre address shared with other work, and that may count against it. A desktop Chrome on your own box doesn’t get you past walls by itself. What the server has, and Cloudflare’s browser can’t use, is proxies of your own: one on a home or mobile address may get past some of the rest.

Where it breaks

In our runs a single box failed in five ways. Each one shows up as a clear error, not a bad picture.

  • CPU. With the cores full, shots queue. The server runs MAX_CONCURRENCY shots at once, lets 20 more wait, and answers busy (HTTP 503) to the next.
  • The timeout. The default timeout is 30 seconds for the whole capture. The New York Times took longer on the first try and came back as timeout (HTTP 504); on a second try it came through in 14 seconds. Raise timeout per request, up to MAX_TIMEOUT_SECONDS (60 by default).
  • Your server’s address. Sites judge the address too. From our machine, Hacker News answered the browser with HTTP 503 twice, and Wikipedia answered 429 once, then a normal page 20 minutes later. The API reports those as error_page and blocked with reason: rate_limited.
  • Very tall pages. Spiegel’s homepage is 32,304 px tall. A full-page shot stops at full_page_max_height (10,000 by default) and Chromium can’t draw past 16,384 device pixels, so the x-truncated: true header tells you it was cut.
  • Shared memory in containers. Docker gives a container 64 MB of /dev/shm, which crashes Chromium on big pages in many setups. This image starts Chromium with --disable-dev-shm-usage, so you don’t need --shm-size.

Your own proxies

For sites that block your server’s address, send the browser’s traffic through proxies of your own:

docker run -d -p 3000:3000 -e API_KEY="$API_KEY" \
  -e PROXY_URLS="http://user:pass@proxy1.example.com:8080,http://user:pass@proxy2.example.com:8080" \
  -e BROWSER_LANGUAGE=nl-NL -e BROWSER_TIMEZONE=Europe/Amsterdam \
  ghcr.io/matbrons/api-screenshot

PROXY_URL takes one proxy (http://, https:// or socks5://); PROXY_URLS takes a list, and each shot uses the next one. When a page comes back blocked, retry (1 by default, up to 2) tries again through a proxy not yet used for that shot. A proxy that fails is rested for 30 seconds, then longer each time, up to 10 minutes. Set the language and time zone to match where the proxies are. The proxy’s login never appears in logs or error messages.

We didn’t test with proxies, so we have no numbers on how many walls they get you past.

Safe on an open port

A screenshot API loads any URL it is given, so without a guard anyone could point it at your private network, or at the cloud metadata address that hands out credentials. On a server all of the browser’s traffic goes through a small proxy inside the API. It looks up each host itself, refuses private, local and metadata addresses, and connects only to the public address it checked. That covers redirects, every request the page makes, WebSockets, and names that point a public domain at 127.0.0.1. With your own proxies set, the checks still run on your server first, and the proxy is only given addresses that passed.

Each shot runs in a fresh incognito context, so no cookies or storage carry over between requests.

No telemetry, MIT

The API sends nothing home. The only outside fetch it makes on its own is the public ad, tracker and cookie filter lists (EasyList, EasyPrivacy and the EasyList Cookie List), at start and once a day; FETCH_BLOCKLISTS=false turns that off. The code is MIT, with its source on GitHub.

Cloudflare or Docker?

  • Pick Cloudflare for no server at all. It is one click, and on our list it got past more bot walls than our server did. The free plan covers a few dozen full-page shots a day; how many, measured, is in our other post.
  • Pick Docker when you need your own proxies, every connection checked on your side, or many shots without a clock on browser time. Plan on about 13 CPU-seconds a shot.

The same API, options and error codes run on both, so you can start on one and move.

How we measured

The server runs on 15 Nov 2026, 17:32 to 17:56 UTC; the Cloudflare run on 16 Nov 2026, 00:00 to 00:15 UTC, right after its daily minutes reset. Sites can answer differently at another hour, so read the side by side as one sample.

  • The server: this API’s Node server (the same engine as the 0.1.1 image), run without Docker with npm start, Google Chrome 157 and MAX_CONCURRENCY=4. The machine is a shared server with 16 AMD EPYC (Rome) vCPUs and 31 GB of RAM, with other work running on it, so the time per shot is rougher than the CPU-seconds, which don’t depend on the neighbours. It is not a VPS, and the Docker image runs Debian’s Chromium where we ran Chrome.
  • Throughput: the 18 ordinary pages that came back clean from the server in the side by side, sent 1, 2 and 4 at a time, all full-page with fresh=true so the cache didn’t count. RAM is the memory in use by the server and its browser processes, sampled twice a second. CPU is their total CPU time divided by the number of shots.
  • Side by side: 28 URLs, one at a time, full page, fresh=true, default options. Cloudflare: our install on a workers.dev address, on the free plan, a new browser per shot, requests at least 30 seconds apart. Seconds are the whole request as the caller sees it. Server: as above, from the shared server’s own data-centre address, no proxy.

Sources