sitespeed.io: a real-browser web performance harness you run yourself

The gap sitespeed.io fills: measurement you host yourself

Most page-speed testing happens in someone else's browser on someone else's network, and the result is a score you cannot reproduce. sitespeed.io takes the opposite position. The README describes it as an Open Source web performance tool that drives a real browser, Firefox, Chrome, Edge or Safari, loads your page, and hands back an HTML report with Core Web Vitals, a video of the load, the HAR waterfall and the Coach's advice. The project has existed since 2012, is MIT licensed, and the README states plainly that you own all your data and there is nothing to sign up for.

The audience is narrow and specific. It is for the engineer who already knows that a single run is noise and wants five iterations with a median. It is for the team that wants the same measurement to run on a pull request and again on an hourly schedule, using one tool instead of two. It is not for the marketer who wants a letter grade for a slide. The report is dense: Core Web Vitals scored against Google's p75 thresholds, First Visual Change, Speed Index, Last Visual Change, a scrubable filmstrip, long-task and CPU analysis. That density is the product.

How a run actually flows: browser, Browsertime, plugins, output

The command line entry point is bin/sitespeed.js, and package.json exposes it as the sitespeed.io binary. The repository is laid out around a plugin model: lib/ holds the implementation, lib/plugins/html/ holds the Pug templates and Sass sources that build the report, and the CSS is compiled by npm scripts (build:css-light and build:css-dark run sass and cleancss over lib/plugins/html/src/sass/main-light.scss). The report you open in a browser is generated locally from that template set, which is why it works with no network connection to a service.

The browser work is delegated. The Dockerfile starts from sitespeedio/webbrowsers:chrome-153.0-firefox-155.0-edge-152.0, so the image carries the browser versions rather than inheriting whatever is on the host. Inside the container, SITESPEED_IO_BROWSERTIME__XVFB and SITESPEED_IO_BROWSERTIME__DOCKER are set, which tells the underlying Browsertime layer to run headless under a virtual display. The image also installs libnss3-tools, net-tools, build-essential and iproute2, and writes a sudoers rule allowing /usr/sbin/tc, /usr/sbin/route and /usr/sbin/ip without a password, which is what the network throttling path needs to shape traffic.

There is a second binary, sitespeed.io-wpr, pointing at bin/browsertimeWebPageReplay.js. The Dockerfile copies a WebPageReplay binary, a certificate and key, and a deterministic.js script into /webpagereplay/, then runs wpr installroot against that certificate. That is the deterministic-replay path: serve recorded responses instead of hitting the live network, so run-to-run variance drops. It is a meaningful architectural choice, and it is also the part of the tool that needs the most setup.

Installing sitespeed.io with Docker or npm

The README gives two installation routes. Docker is described as the easiest, because the image ships with Firefox, Chrome, Edge and their dependencies. The command mounts the current directory so results land somewhere you can find them:

docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io https://www.sitespeed.io/

After it finishes, look in the directory you ran it from. The HTML report is written there, and the README's examples show a summary tab and a per-URL metrics tab.

The npm route is shorter to type but pushes dependency management onto you:

npm i -g sitespeed.io

Then run it against a URL. The README notes that you need a browser installed locally, plus FFmpeg and Python if you want video and visual metrics:

sitespeed.io https://www.example.com

For any measurement you intend to act on, the README recommends multiple iterations and reports the median, because single runs are noisy:

sitespeed.io https://www.example.com --browser chrome -n 5

The same invocation works for mobile. Real Android phones over USB use --android, and real iPhones over USB, added in version 40.0, use the Safari binary with the iOS flag:

sitespeed.io https://www.example.com -b safari --safari.ios

The README points to separate setup guides for Android and iOS, and says --help lists the full flag set. Treat --help as the authoritative list rather than any flag you have seen in a blog post.

Where sitespeed.io gets in your way

The npm install is not self-contained. Video and visual metrics depend on FFmpeg and Python being present, and the README says so in the installation section rather than burying it. If those are missing you do not get a clear failure at install time; you get a run without the visual numbers, which is exactly the part that distinguishes sitespeed.io from a timing-only tool. This is the first thing to verify on a new machine.

Network throttling is the second rough edge. The Dockerfile grants passwordless sudo for tc, route and ip so the throttle path can shape traffic inside the container. That works because the container is yours. Running the npm install on a shared host, or in a CI runner where you do not control sudoers, is a different situation, and the repository's own Dockerfile is the clearest statement that throttling expects elevated network privileges.

Third, the deterministic WebPageReplay path is not a default. It requires the extra binary, the certificate installed into the browser trust store, and the wpr installroot step. If your goal is a quick audit, ignore it. If your goal is stable regression numbers across many runs, it is the difference between measuring your page and measuring the internet.

Finally, the report is a static artifact. The README does not document a rollback or a way to re-open a previous run from the CLI, and there is no built-in history store. History is the job of the Graphite or InfluxDB sink plus Grafana, which means you are operating a time-series database if you want trends.

sitespeed.io against Lighthouse and hosted speed tests

The obvious alternative is Lighthouse, which is also open source and also drives Chrome. The difference in approach is scope. Lighthouse is a single-page audit that produces a score and a set of opportunities, and it is tightly bound to Chrome's DevTools protocol. sitespeed.io is a harness: it drives four browser families including Safari on a real iPhone over USB, keeps a video and a filmstrip of the load, emits a HAR waterfall rendered with waterfall-tools, and is designed from the start to run on a schedule and ship metrics to a time-series database. If you want a score, Lighthouse is less machinery. If you want the raw artifacts, the video and the HAR, and a path to a Grafana dashboard, sitespeed.io is the shorter route.

Hosted speed tests are the other comparison, and the difference is ownership. A hosted test runs on infrastructure you do not control, against a network path you cannot inspect, and the data lives with the vendor. sitespeed.io runs where you tell it to run, and the README's claim that you own all your data is a direct consequence of the architecture: the report is generated locally from Pug templates, and the metrics go to a database you operate. The cost is that you now operate that database. The README's own live example at dashboard.sitespeed.io is sitespeed.io feeding Graphite and visualised with Grafana, which is a fair picture of the work involved.

Maintenance, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-09-16. Releases are frequent: v42.7.0 on 2026-09-11, v42.6.0 on 2026-08-06, v42.5.1 on 2026-07-29. That cadence is the maintenance cost. A pinned Docker tag is the cheap option, because the image bundles specific browser builds (chrome-153.0, firefox-155.0, edge-152.0 in the Dockerfile shown here). Moving to a newer sitespeed.io image moves the browsers with it, and browser upgrades are where web performance tooling tends to break, not in the metric definitions.

The npm path has a different cost profile. package.json ships an npm-shrinkwrap.json, so the dependency tree is pinned by the maintainers, but you are still installing a global CLI on a machine that also needs a browser, FFmpeg and Python. Version 42.x is ESM ("type": "module"), which matters if you were planning to require() it from an older CommonJS script.

The licence is MIT. That is permissive and short: it allows use, modification and redistribution with the copyright notice and permission notice retained, and it comes with no warranty. It says nothing about the licences of the browsers, FFmpeg or the WebPageReplay binary that the Docker image bundles, and the repository does carry a tools/check-licenses.js script and a check-licenses npm script, which suggests the maintainers track that. If you redistribute the image inside a product, review those bundled components separately. This is a description of the licence text, not legal advice.

Editorial conclusion

Adopt sitespeed.io if you want the measuring instrument itself: a CLI that drives a real browser, writes an HTML report you can open offline, and can push the same numbers to Graphite or InfluxDB on a schedule. Skip it if you need a hosted dashboard with no infrastructure, or if nobody on the team will own the browser, FFmpeg and Python dependencies that video and visual metrics require. Before committing, run the Docker image against one URL of your own with -n 5, confirm the report opens from the mounted volume, and check whether you actually get visual metrics or only the timing numbers.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sitespeedio/sitespeed.io on GitHub