> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerogpu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser

> Contribute compute from the browsers visiting your website with the ZeroGPU browser SDK.

## Overview

The ZeroGPU browser SDK turns the browsers running your website or web app 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.

Add it with the always-latest loader script from `js-sdk.zerogpu.ai`, or install the npm package if you bundle your own JavaScript.

Building a Chrome extension instead? See [Chrome Extension](https://docs.zerogpu.ai/edge/sdk/chrome-extension.md). Building a Telegram Mini App? See [Telegram Mini Apps](https://docs.zerogpu.ai/edge/sdk/telegram.md).

## 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](https://edge.zerogpu.ai).
* **Websites with a strict Content Security Policy:** allow `blob:` workers, or host the worker yourself and set `overrides.inference.workerUrl`.

## Download

| Source | |
| - | - |
| **CDN** | `https://js-sdk.zerogpu.ai/dist/loader.js` (always the latest release) |
| **npm** | [`@zerogpu/browser-extension-sdk`](https://www.npmjs.com/package/@zerogpu/browser-extension-sdk) |
| **GitHub** | [github.com/zerogpu](https://github.com/zerogpu) |

## Installation

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

```html theme={null}
<script async src="https://js-sdk.zerogpu.ai/dist/loader.js"></script>
```

Or install from npm if you bundle your own JavaScript:

```bash theme={null}
npm install @zerogpu/browser-extension-sdk
```

## Initialization

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

```html theme={null}
<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:

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

**ESM:**

```ts theme={null}
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`. |
| `appId` | Optional. Your app's ID from the Edge Operator Portal. Script tag: `data-app-id`. See [App ID and app name](#app-id-and-app-name-optional). |
| `appName` | Optional. Your app's display name. Script tag: `data-app-name`. |
| `externalAppId` | Optional. A native ID for your app, such as your domain. Script tag: `data-external-app-id`. |

### App ID and app name (optional)

Pass the app ID and name from the [Edge Operator Portal](https://edge.zerogpu.ai) so the inference this browser serves is attributed to your app. Copy the ID from your app's row on **My Apps**.

```html theme={null}
<script
  async
  src="https://js-sdk.zerogpu.ai/dist/loader.js"
  edgeOperatorKey="zgpu-sdk-your-key"
  data-app-id="your-app-id"
  data-app-name="My App"
></script>
```

With `initZeroGpuSdk`, pass `appId` and `appName` instead. Both are optional: leaving them unset never affects registration or inference, and ZeroGPU then uses the app your SDK key belongs to.
\| `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. |

## 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 starts when it's initialized with your SDK key and keeps contributing while the page is open.

## Stop / pause

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

```ts theme={null}
await zerogpu.shutdown();
```

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

## Device lifecycle

The handle's `status` is one of `starting`, `running`, `degraded`, `shutdown`, or `error`. Subscribe to changes:

```ts theme={null}
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

```html index.html theme={null}
<!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.

Once the device is online, [check that it's eligible and earning](https://docs.zerogpu.ai/edge/verify.md).

## 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` | Your CSP blocks `blob:` workers; set `overrides.inference.workerUrl`. |
| Pinned to an old SDK | You're loading `zerogpu-browser-sdk.umd.js` directly. Use `dist/loader.js` instead. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.