---
title: Boot Sequence
description: How the WebGPU OS comes up — from the HTML page to a mounted desktop — via boot.js and the bootWebGpuOS() entry point.
updated: 2026-06-05
---

# Boot Sequence

How the WebGPU OS comes up, from the HTML page to a mounted desktop. This reflects `webgpu-os/boot.js` and the `bootWebGpuOS()` function in `webgpu-os/index.js`.

## Entry points

- **`webgpu-os/index.js`** — a side-effect-free barrel exporting `bootWebGpuOS(options)`. Importing it does **not** auto-boot, which makes it the clean entry point for the static bundler (`bundle_engine.py --target webgpu-os`).
- **`webgpu-os/boot.js`** — a thin wrapper that calls `bootWebGpuOS()` on `DOMContentLoaded` for plain ES-module/dev usage.

```javascript
// boot.js (essence)
import { bootWebGpuOS } from './index.js';
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', () => bootWebGpuOS(), { once: true });
} else {
  bootWebGpuOS();
}
```

## The boot phases

`bootWebGpuOS()` runs these phases, updating the on-screen boot status as it goes:

```mermaid
sequenceDiagram
  participant HTML as index.html
  participant Boot as bootWebGpuOS()
  participant Kernel as KernelBootstrap
  participant Apps as appRegistry
  participant Mods as modRegistry
  participant Desktop as Desktop (shell)

  HTML->>Boot: DOMContentLoaded
  Boot->>Kernel: KernelBootstrap.init({ canvasSelector, logger })
  Kernel-->>Boot: kernel services
  Boot->>Apps: appRegistry.discover()
  Apps-->>Boot: discovered apps
  Boot->>Kernel: packageManager.syncBuiltins(appRegistry)
  Boot->>Mods: modRegistry.discover()
  Mods-->>Boot: loaded mods
  Boot->>Desktop: new Desktop(root, taskbar, kernel).mount()
  Desktop-->>Boot: desktop mounted
  Boot->>HTML: hide boot loader, set window.OS
```

1. **Initializing kernel** — `KernelBootstrap.init({ canvasSelector, logger })` brings up kernel services against the WebGPU canvas.
2. **Discovering apps** — `appRegistry.discover()` finds apps from `apps/` (errors are logged as warnings, not fatal). Discovered built-ins are synced into the package registry via `kernel.packageManager.syncBuiltins(appRegistry)` (idempotent).
3. **Loading mods** — `modRegistry.discover()` loads runtime mods from `mods/`.
4. **Mounting desktop shell** — `new Desktop(desktopRoot, taskbarRoot, kernel)` then `await desktop.mount()`. Missing shell root elements throw.
5. **Optional security self-tests** — when `window.__DEV__` is true or the URL contains `?securityAudit`: `auditSyscallGuards(kernel)`, `auditCapabilityMap()`, and `runSecurityDoctor(kernel)` run and log findings. `kernel.securityDoctor()` is also exposed for on-demand use.
6. **Ready** — the boot loader is hidden and `window.OS = { version, ready: true }` (frozen). `bootWebGpuOS()` resolves to `{ kernel, desktop, version }`.

## Kernel init order

Inside `KernelBootstrap`, the package/trust subsystem initializes in this order (Source: `webgpu-os/docs/ARCHITECTURE.md`):

```text
TrustStore.init()
  → PackageManager.init()   (re-registers installed packages/mods)
  → PatchManager
  → UpdateManager
```

Because installed packages are re-registered on init, **installed apps survive a reload.**

## Boot options

`bootWebGpuOS(options)` accepts selector overrides (defaults shown):

| Option | Default |
| --- | --- |
| `canvasSelector` | `#os-gpu-canvas` |
| `desktopSelector` | `#os-desktop` |
| `taskbarSelector` | `#os-taskbar` |
| `statusSelector` | `#os-boot-status` |
| `loaderSelector` | `#os-boot-loader` |
| `logger` | `console` |

## Failure handling

If any phase throws, the boot status is set to `Boot failed: <message>`, the error is logged via `logger.error`, and the promise rejects. App/mod discovery errors are non-fatal and surface as console warnings.

## See also

- [GPU Device Sharing](gpu-device-sharing.md) — what the kernel sets up on the canvas.
- [Security & Trust Model](security-model.md) — what the boot-time audits check.
- WebGPU OS **API Reference** — `KernelBootstrap`, `AppRegistry`, `Desktop`.