Overview
The ZeroGPU browser SDK turns the browsers running your Chrome extension into on-device inference nodes on the ZeroGPU network. It runs in a background offscreen document: it downloads a small model, registers the device, and serves inference tasks locally in a Web Worker. Manifest V3 doesn’t allow remotely hosted code, so the SDK is installed from npm and vendored into your extension with thezerogpu CLI.
Building a website instead? See Browser. Building a Telegram Mini App? See Telegram Mini Apps.
Requirements
- A Manifest V3 Chrome extension.
- Node.js and npm at build time only. Nothing from
node_modulesships in your extension. - An SDK key (
zgpu-sdk-…) from the Edge Operator Portal.
Download
Installation
npx zerogpu init copies the SDK runtime into vendor/zerogpu/, creates offscreen.html, offscreen.js, and background.js (it never overwrites your files), and adds what the SDK needs to manifest.json: the offscreen and storage permissions, a CSP entry allowing 'wasm-unsafe-eval', a host permission (<all_urls>) for model downloads, and an externally_connectable entry for the ZeroGPU settings page.
Using your own service worker? Merge the generated background.js snippet into it, and add "prebuild": "zerogpu vendor" to your build scripts.
Initialization
Open the generatedoffscreen.js and add your SDK key:
offscreen.js
App ID and app name (optional)
Pass the app ID and name from the Edge Operator Portal so the inference this browser serves is attributed to your extension. Copy the ID from your app’s row on My Apps.offscreen.js
@zerogpu/browser-extension-sdk 0.5.1 or later. Leaving them unset never affects registration or inference; ZeroGPU then uses the app your SDK key belongs to.
Add the opt-out link
Add this to your settings page, usually in the popup, to allow end users to opt out of ZeroGPU at any time:popup.html
Authentication
The SDK authenticates with your SDK key (zgpu-sdk-…), passed as edgeOperatorKey. The key can only join devices to your fleet; it can’t call the inference API or spend credits. Still, inject it at build time rather than committing it.
Register device
Registration is automatic. When the SDK starts with your SDK key, it checks the device can run a model, downloads one, and connects the device to ZeroGPU. Models are cached, so later starts are faster. To match the device to a model, the SDK shares coarse device information, such as platform, CPU cores, approximate memory, and battery level.Start contributing compute
The SDK runs in a background offscreen document and starts automatically whenever your extension loads.Stop / pause
Users must be able to turn resource sharing off. New installs are opted in; while a user is opted out, the offscreen document is never created, so nothing starts or connects. The choice persists across restarts. Turn it off with the opt-out link, or control it from your service worker:false on install and flip it when the user agrees.
Device lifecycle
Before downloading models, the SDK checks memory and storage, and blocks downloads when the battery is below 20% and the device isn’t charging.Example integration
- Go to
chrome://extensions, turn on Developer mode, and click Load unpacked. - On your extension’s card, open Inspect views: offscreen.html.
- With
enableConsoleLogs: true, watch the SDK start, register the device, load a model, and become ready.
Keep the SDK up to date
Manifest V3 extensions can’t change their code at runtime, so your users get a new SDK version when you publish a new build of your extension. Whenever the SDK version changes, the runtime invendor/zerogpu/ must be refreshed with npx zerogpu vendor.
1
Re-vendor on every build
Add a
prebuild script to package.json, so every build copies the installed SDK runtime into your extension:package.json
2
Let Dependabot open update PRs
Add Using Renovate instead? Add a
.github/dependabot.yml so a pull request opens whenever a new SDK version ships:.github/dependabot.yml
renovate.json with { "extends": ["config:recommended"] }.3
Merge, bump, and republish
When the update PR lands, bump
"version" in manifest.json and publish the new build. The Chrome Web Store then updates installed users automatically.package.json controls which updates the bot proposes:
Prefer to update by hand? Run
npm update @zerogpu/browser-extension-sdk, then npx zerogpu vendor and npx zerogpu doctor, and republish. With no build tooling at all, npx -p @zerogpu/browser-extension-sdk zerogpu vendor refreshes vendor/zerogpu/ without adding a dependency.

