Skip to main content

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 the zerogpu 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_modules ships 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.
Heads up: this setup adds a broad host permission (<all_urls>) to your manifest. The SDK requires it. When people install your extension, Chrome will note that it can access data on all websites. The SDK never reads or changes browsing data.
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 generated offscreen.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
Both are optional and need @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 this to your settings page, usually in the popup, to allow end users to opt out of ZeroGPU at any time:
popup.html
The script fills in the link from your extension’s ID at load time, so the same two lines work in an unpacked build and a published one. Style the link to match your UI.

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:
If your consent flow requires an explicit yes first, write 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

  1. Go to chrome://extensions, turn on Developer mode, and click Load unpacked.
  2. On your extension’s card, open Inspect views: offscreen.html.
  3. With enableConsoleLogs: true, watch the SDK start, register the device, load a model, and become ready.
Check your setup at any time:
To pick up new SDK versions, see Keep the SDK up to date. Once the device is online, check that it’s eligible and earning.

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 in vendor/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 .github/dependabot.yml so a pull request opens whenever a new SDK version ships:
.github/dependabot.yml
Using Renovate instead? Add a 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.
The version range in 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.

Chrome Web Store submission

When you submit, paste this justification for the “offscreen” permission:

Troubleshooting