# Emulated Chromium

> The emulated Chromium browser extension.dev hosts, what it opens, what leaves your machine, and what it costs.

Canonical: https://docs.extension.dev/browsers/emulated-chromium
This page as Markdown: https://docs.extension.dev/browsers/emulated-chromium.md
Section: Browsers
Siblings: [Emulated Chromium limits](https://docs.extension.dev/browsers/limits.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# Emulated Chromium

Emulated Chromium is a browser extension.dev builds and hosts at
`browsers.extension.land/chromium/`. It runs your extension inside a web
page, with a toolbar, a tab strip, an address bar, a popup, an options page,
a side panel and a background service worker. Reach for it when you want a
dev session in a tab instead of a browser profile on disk.

## Quick start

```bash
extension dev --browser chromium-emulator
```

The command prints the address and opens it in your default browser. The
`extension` CLI is the Extension.js framework, documented at
[extension.js.org](https://extension.js.org). Everything after the address is
this engine.


## How it works

The same engine renders the live previews on
[templates.extension.dev](https://templates.extension.dev). This page is
about the address a developer opens from a terminal.

Nothing of your extension leaves your machine. Three things arrive from the
hosted origin: the page, its script and stylesheet, and a table of engine
behavior pinned by digest. The page reads your build from the dev server on
your own loopback address. The lane runs no relay, so a fetch your extension
makes goes straight from the page.

The session lives in the fragment of the address, after the `#`. A fragment
is never sent in a request line and never in a `Referer`, so the loopback
address and the session id do not reach the origin's logs.

The page reads the files index your dev server publishes, then reads each
file and checks it against the digest the index promised. A file that does
not match is refused by path, and the build already running is kept.

The page sits on a public address and reads a server on your machine. Chrome
gates that behind the local network access site permission. The first run
can be refused with no dialog, and the page names the permission when that
happens. Allow local network access for the site, and reload.

It costs nothing. The build is compiled by your machine and the extension
runs in your own browser tab. The platform serves a page and a table of
behavior, and charges only for runs on its own machines, which this is not.

Emulated Chromium is not a shipped browser. Content scripts reach only the
pages it serves itself, there is no inspector for your extension, and a
handful of namespaces answer with stand-in data. The full list is one page:
[Emulated Chromium limits](/browsers/limits).

## Reference

| Direction | What moves |
| --- | --- |
| From the hosted origin | The page, its script and stylesheet, and the table of engine behavior |
| From your machine | Nothing. The page reads your build from the dev server on loopback |
| Between them | Nothing. No relay, so your extension's fetches leave straight from the page |

| Address | What it serves |
| --- | --- |
| `browsers.extension.land/chromium/` | The engine page a dev session opens |
| `browsers.extension.land/chromium/version.json` | The engine version |
| `browsers.extension.land/chromium/terms` | The terms of use |

## When it fails

- **The page says it cannot reach your dev server**: Chrome refused local network access, possibly with no dialog. Allow it for the site in the page's site settings and reload.
- **A file was refused by path**: its bytes did not match the digest your dev server listed. The build already running stays, and the page reports that the last reload was not applied.

## Next

- [Emulated Chromium limits](/browsers/limits) for what does not work here and how each line is kept true
- [Share an unpublished build for review](/share/unpublished-build-for-review) for the same engine behind a share link