---
title: WebGPU OS Getting Started
description: Boot the OS in a browser and build a minimal capability-gated app.
updated: 2026-06-05
---

# WebGPU OS Getting Started

Boot the OS and build a minimal app. Assumes [Install & Run](../getting-started/install.md) is done.

## Boot the OS

```bash
python start_server.py
# then browse to:
#   http://127.0.0.1:9001/webgpu-os/
```

Or embed it (see [Quickstart](../getting-started/quickstart.md)):

```javascript
import { bootWebGpuOS } from './webgpu-os/index.js';
const os = await bootWebGpuOS();
```

## Build a minimal app

1. **Create the folder** `webgpu-os/apps/hello/`.
2. **Add a manifest** `apps/hello/manifest.json`:

```json
{
  "id": "hello",
  "name": "Hello",
  "version": "0.1.0",
  "entry": "main.js",
  "surface": "window",
  "icon": "👋",
  "category": "utility",
  "permissions": ["ui.notify"]
}
```

3. **Add the entry module** `apps/hello/main.js` — default-export a class with `mount`:

```javascript
export default class HelloApp {
  async mount(root, syscalls) {
    root.innerHTML = '<h1 style="padding:16px">Hello, WebGPU OS</h1>';
    // syscalls are capability-gated; this requires "ui.notify"
    await syscalls.ui?.notify?.({ title: 'Hello', body: 'App mounted.' });
  }
  unmount() { /* clean up timers, GPU resources, listeners */ }
}
```

4. **Register it** — add `"hello"` to `webgpu-os/apps/index.json`.
5. **Reload** the OS. The app appears in the Start Menu and is discovered by `AppRegistry`.

## Key rules

- Declare **only** the permissions you use; they are checked by `guardSyscalls`. See [Security & Trust Model](../concepts/security-model.md).
- Treat GPU resources as reconstructable — handle the `device-lost` fan-out. See [GPU Device Sharing](../concepts/gpu-device-sharing.md).
- For distribution, package the app as a `.prpkg` v2 (`pkg-studio` / `PackageBuilder`).

## See also

- [Architecture](architecture.md) — the app entry contract and package pipeline.
- [App Catalog](app-catalog.md) — existing apps to learn from.
- `webgpu-os/templates/` — `template-app` / `template-mod` starters.