Chrome / Web

Overview

The ZeroGPU browser SDK turns the browsers running your website or Chrome extension into on-device inference nodes on the ZeroGPU network. It downloads a small model, registers the device, and serves inference tasks locally, in a Web Worker so your page’s main thread stays responsive. There are two ways to integrate:

You’re building	Use
A website or web app	The always-latest loader script from `js-sdk.zerogpu.ai`, or the npm package
A Chrome extension (Manifest V3)	The npm package, vendored into your extension with the `zerogpu` CLI. MV3 doesn’t allow remotely hosted code.

Building a Telegram Mini App? See Telegram Mini Apps.

Requirements

A modern desktop or mobile browser with WebAssembly, IndexedDB (for the model cache), and Web Workers.
An SDK key (zgpu-sdk-…) from the Edge Operator Portal.
Websites with a strict Content Security Policy: allow blob: workers, or host the worker yourself and set overrides.inference.workerUrl.
Chrome extensions: Manifest V3, plus Node.js and npm at build time only. Nothing from node_modules ships in your extension.

Installation

Website
Chrome extension

Add the loader to your page. It always resolves the latest released SDK, so you never pin or bump versions:

<script async src="https://js-sdk.zerogpu.ai/dist/loader.js"></script>

Or install from npm if you bundle your own JavaScript:

npm install @zerogpu/browser-extension-sdk

npm install @zerogpu/browser-extension-sdk
npx zerogpu init

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', host permissions 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

Website
Chrome extension

Script tag (auto-init). The SDK starts as soon as edgeOperatorKey is present:

<script
  async
  src="https://js-sdk.zerogpu.ai/dist/loader.js"
  edgeOperatorKey="zgpu-sdk-your-key"
></script>

Manual init. Load the loader without a key and call initZeroGpuSdk. Calls made before the SDK finishes loading are queued and replayed:

<script async src="https://js-sdk.zerogpu.ai/dist/loader.js"></script>
<script>
  ZeroGpuSdk.initZeroGpuSdk({
    edgeOperatorKey: 'zgpu-sdk-your-key'
  });
</script>

ESM:

import { initZeroGpuSdk } from '@zerogpu/browser-extension-sdk';

const zerogpu = await initZeroGpuSdk({
  edgeOperatorKey: 'zgpu-sdk-your-key',
});

Option	Description
`edgeOperatorKey`	Your SDK key. Required.
`appUserId`	Optional stable user identifier for your own reporting.
`customParams`	Up to three reporting slots, `cust_param1`–`cust_param3`. Values only; no personal data. Script tag: `data-cust-param1`…`3`.
`overrides.telemetry.enableConsoleLogs`	Log SDK activity to the console (redacted). Script tag: `enableConsoleLogs="true"`.
`overrides.inference.workerUrl`	Same-origin worker URL for pages whose CSP forbids `blob:` workers.

Open the generated offscreen.js and add your SDK key:

offscreen.js

import { initZeroGpuOffscreen } from "./vendor/zerogpu/zerogpu-offscreen.js";

initZeroGpuOffscreen({
  edgeOperatorKey: "zgpu-sdk-your-key",
  enableConsoleLogs: true
});

Option	Required	Description
`edgeOperatorKey`	yes	Your SDK key.
`enableConsoleLogs`	no	Log SDK activity to the offscreen console.
`inferenceWorker`	no	Run inference in the SDK’s worker. Default `true`.
`appUserId`	no	A stable identifier for the current user.
`customParams`	no	`{ cust_param1, cust_param2, cust_param3 }` reporting slots.

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. On start, the SDK collects coarse device capabilities (platform, CPU cores, approximate memory, battery level, connection type), downloads and caches its assigned model in IndexedDB, registers with the ZeroGPU device registry, and opens a WebSocket for tasks.

Start contributing compute

Websites: the SDK starts when it’s initialized with your SDK key and keeps contributing while the page is open.
Chrome extensions: the SDK runs in a background offscreen document and starts automatically whenever your extension loads.

Stop / pause

Website
Chrome extension

initZeroGpuSdk returns a handle. Call shutdown() to stop gracefully:

await zerogpu.shutdown();

Shutdown lasts until the page initializes the SDK again; there is no separate pause call.

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.Add the opt-out link to an extension page you already show, such as your popup:

<a data-zerogpu-settings>Resource sharing</a>
<script src="vendor/zerogpu/zerogpu-settings-link.js"></script>

Or control it from your service worker:

await ZeroGpuBackground.getZeroGpuConsent();
await ZeroGpuBackground.setZeroGpuConsent(false); // stops the SDK, stays off

If your consent flow requires an explicit yes first, write false on install and flip it when the user agrees.

Device lifecycle

On websites, the handle’s status is one of starting, running, degraded, shutdown, or error. Subscribe to changes:

zerogpu.on('degraded', ({ code, message }) => { /* resource pressure */ });
zerogpu.on('recovered', () => { /* back to normal */ });
zerogpu.on('shutdown', ({ code }) => { /* the SDK stopped */ });

initZeroGpuSdk never throws: if the SDK can’t run on a device, status reports it instead of breaking your page. 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

Website
Chrome extension

index.html

<!doctype html>
<html>
  <head>
    <script
      async
      src="https://js-sdk.zerogpu.ai/dist/loader.js"
      edgeOperatorKey="zgpu-sdk-your-key"
      enableConsoleLogs="true"
    ></script>
  </head>
  <body>
    <!-- your app -->
  </body>
</html>

Open the page and check the console: with enableConsoleLogs on, you’ll see the SDK register the device, load a model, and become ready.

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.

Check your setup at any time:

npx zerogpu doctor

After each SDK update, run npx zerogpu vendor (or wire it into prebuild) and republish your extension.

Troubleshooting

Symptom	Fix
Rejected at registration / `401`	The SDK key is wrong or inactive. Check it in the Edge Operator Portal.
`Inference worker unavailable; models run on the main thread`	Websites: your CSP blocks `blob:` workers; set `overrides.inference.workerUrl`. Extensions: the vendored worker is missing or stale; run `npx zerogpu vendor`.
Extension: CSP error mentioning `'wasm-unsafe-eval'`	Your manifest’s CSP must allow `'wasm-unsafe-eval'`. Re-run `npx zerogpu init` or `npx zerogpu doctor`.
Extension: import fails / runtime files missing	Run `npx zerogpu vendor` and confirm `vendor/zerogpu/` exists.
Extension: model download blocked	Allow the model host in your manifest’s host permissions; `npx zerogpu doctor` flags this.
Extension: out of date after an update	`npx zerogpu doctor` reports drift; run `npx zerogpu vendor`.
Website pinned to an old SDK	You’re loading `zerogpu-browser-sdk.umd.js` directly. Use `dist/loader.js` instead.

Get Started

Models

Guides

Platform

Edge Providers

Overview

Requirements

Installation

Initialization

Authentication

Register device

Start contributing compute

Stop / pause

Device lifecycle

Example integration

Troubleshooting

​Overview

​Requirements

​Installation

​Initialization

​Authentication

​Register device

​Start contributing compute

​Stop / pause

​Device lifecycle

​Example integration

​Troubleshooting

Overview

Requirements

Installation

Initialization

Authentication

Register device

Start contributing compute

Stop / pause

Device lifecycle

Example integration

Troubleshooting