---
title: GPU Device Sharing
description: The single shared WebGPU device model — one device brokered by the kernel with per-app budgets and barriers.
updated: 2026-06-05
---

# GPU Device Sharing

The whole OS runs against a **single** WebGPU device shared by the shell and every app. This page explains the model and where it lives. It expands the notes in `webgpu-os/docs/ARCHITECTURE.md`.

## Why one device

WebGPU devices are expensive and the browser already runs GPU work in a dedicated process. The OS follows the same principle: one device, brokered by the kernel, with per-app budgets and barriers — rather than each app creating its own device.

> **Design rule:** the GPU service is user-space, not "in the kernel." The kernel mediates the device (scheduling, memory protection, fan-out); validation, shader compilation, and pipeline creation happen above it. See [Architecture Overview](architecture-overview.md).

## Key components

| Concern | Component |
| --- | --- |
| Device acquisition + sharing | `kernel/GpuDeviceBroker.js` |
| Adapter/device info | `kernel/GpuInfo.js` |
| VRAM accounting | `kernel/VRAMTracker.js` |
| Virtual GPU abstraction | `engine/core/gpu/VirtualGPU.js` (VGPU) |
| Multi-queue submission | `engine/core/gpu/VGPUMultiQueue.js` |
| Resource barriers | engine VGPU resource-barrier enforcement |
| Device recovery | `engine/core/gpu/GpuRecovery.js` |
| Canvas bootstrap | `engine/core/gpu/WebGpuCanvasBootstrap.js` |

## The model

```mermaid
flowchart TD
  canvas[WebGPU canvas] --> broker[GpuDeviceBroker\nsingle device]
  broker --> vgpu[VirtualGPU / VGPU]
  vgpu --> mq[VGPUMultiQueue\nper-app tick budgets]
  vgpu --> barriers[Resource barriers]
  broker --> vram[VRAMTracker]
  broker -. device-lost .-> appA[App A]
  broker -. device-lost .-> appB[App B]
  broker -. device-lost .-> shell[Shell]
```

- **Single device** — acquired once by the broker and handed to the VGPU abstraction.
- **Frame-loop ownership** — the kernel owns the `requestAnimationFrame` loop and allocates **per-app tick budgets**; apps do not each spin their own loop.
- **Multi-queue + barriers** — concurrent GPU work is ordered through `VGPUMultiQueue` and resource-barrier enforcement so apps don't corrupt each other's state.
- **VRAM tracking** — `VRAMTracker` accounts for allocations so the OS can show usage (e.g. the **GPU Manager** app) and enforce limits.

## device-lost fan-out

When the browser raises WebGPU's `device-lost`, the broker **fans the event out** to every app and the shell so each can release and rebuild GPU resources. Recovery logic lives in `engine/core/gpu/GpuRecovery.js`. Apps should treat their GPU resources as reconstructable and listen for the fan-out rather than assuming the device is permanent.

## What an app should assume

- It shares the device; it must respect its tick budget and not block the frame loop.
- GPU resources can be lost at any time; handle the `device-lost` fan-out.
- Heavy compute belongs in WebGPU compute passes, scheduled through the VGPU layer.

## See also

- [Boot Sequence](boot-sequence.md) — when the device is acquired.
- Engine **API Reference** — `core/gpu/*`.
- WebGPU OS **API Reference** — `kernel/GpuDeviceBroker`, `kernel/VRAMTracker`, `kernel/GpuInfo`.