Open Web Desktop

A modular framework for building web-based desktop experiences.

Overview

Open Web Desktop (OWD) is an open-source framework built on top of Nuxt.js, used to create web-based operating systems and interactive, window-driven desktop experiences directly inside a web browser.

Demo · Documentation · Support

Scope and security model

Open Web Desktop is a shell, not a security boundary. It composes the code you ship: apps, modules, kits, and themes are installed at build time and bundled with your desktop. Nothing executable is fetched or evaluated at runtime in the page's origin.

• Installation is developer-side and on-disk. pnpm desktop add places a package in apps/ (or themes/) and registers it in desktop.config.ts. The browser receives a pre-generated bundle — auditable and reproducible, with no on-the-fly code.
• Extensions are bundled code, not sandboxed code. Any JavaScript in your desktop runs with the full privileges of the page. Never run code you do not trust inside an OWD build.
• Untrusted code is your responsibility. If you need it, isolate it yourself — <iframe sandbox> or a Worker — and expose only declared capabilities. OWD does not offer OS-grade permissions, and does not pretend to.
• Not a daily-driver OS. OWD is for demos, prototypes, theme compatibility, and desktop experiences that stay maintainable. It connects to APIs; it does not isolate your machine.

Open in two ways: open to every framework, and open about what it does not do.

Features

• Desktop extendable through apps, modules, and themes
• Bundled with popular libraries like Pinia and VueUse
• Designed to make the most of the Nuxt.js ecosystem
• Supports any UI kit, such as PrimeVue, Nuxt UI, and Vuetify
• Fully localizable with nuxt-i18n support
• Easy to learn and extend via pnpm desktop

Repository layout

• desktop/ — dev desktop (workspace apps, modules, themes)
• template/ — scaffold copied by npm create owd@latest / pnpm desktop init.
  
  Do not edit "template" by hand; regenerate with pnpm desktop template after changing the starter desktop or publishing @owdproject/* packages. Blueprint sources live in template-blueprint/.

Getting Started

To create a new Open Web Desktop project:

1. Create a project

Run the initializer command to scaffold your project:

npm create owd@latest

2. Install dependencies

Install the project dependencies using pnpm:

pnpm install

3. Run the environment

Run the dev server directly:

pnpm run dev

Or start the control panel (TUI) to manage packages and logs:

pnpm run desktop

(Press d in the control panel to start the dev server, x to stop).

Ecosystem & Extensibility

Open Web Desktop is designed to scale via modular extension packages.
You can customize your workspace using three dedicated package types:

Package Categories

Type	Package convention	Description	Directory	Discovery Tag
Apps	@owdproject/nuxt-app-*	User-facing desktop application programs	apps/	owd-apps
Modules	@owdproject/nuxt-module-*	Nuxt/Vue plugins and backend integrations	packages/	owd-modules
Kits	@owdproject/nuxt-kit-*	UI kits installed by themes	packages/	owd-modules
Themes	@owdproject/nuxt-theme-*	Window manager styles and workspace skins	themes/	owd-themes

Nuxt extensions are framework-first: <framework>-<kind>-<name>. React extensions follow the same shape (@owdproject/react-app-*, @owdproject/react-kit-*, @owdproject/react-theme-*). The engine (@owdproject/core), the framework bindings (@owdproject/nuxt, @owdproject/react, …) and the desktop distribution (@owdproject/nuxt-desktop) are not extensions.

---

Managing Packages

The CLI makes it easy to install, import, and configure packages automatically.

Note

For security reasons, the Control Panel (CP) only displays packages from a whitelist of approved GitHub usernames like owdproject and atproto-os. Modules from other users will not appear automatically, although this discovery mechanism is planned to be improved in the future.

This is a curation measure, not a sandbox: OWD does not isolate the code you install. See Scope and security model.

Installing an Application

To add a new application (e.g., a Todo app):

pnpm desktop add nuxt-app-todo

This command clones or copies the package into apps/nuxt-app-todo and automatically registers it in the local desktop/desktop.config.ts config.

Installing a Module

To add a module (e.g., Pinia state persistence):

pnpm desktop add nuxt-module-pinia-persistence

Installing a Theme

To add a theme (e.g., a GNOME look-and-feel package):

pnpm desktop add nuxt-theme-gnome

Advanced CLI Commands

You can install packages from various sources, specifying different branches or protocols. Run the CLI with --help (e.g. pnpm desktop add --help) to discover all available flags and options:

# Show help and all available options for the add command
pnpm desktop add --help

# Install directly from the npm registry
pnpm desktop add nuxt-app-todo --npm

# Clone from a specific GitHub user fork
pnpm desktop add nuxt-module-pinia-persistence --from github-username

# Clone an official repository in development mode
pnpm desktop add nuxt-app-todo --dev

# Install a specific branch from a user fork using SSH protocol
pnpm desktop add nuxt-theme-gnome --from github-username --branch feature-branch --protocol ssh

Isolated Package Development

For developers building reusable packages (e.g., publishable apps or themes in isolation), OWD supports playground builds using nuxt-module-build.

• Learn more about the playground setup in docs/agents/OWD_APP_MODULE_PLAYGROUND.md.
• Reference examples: app-about and app-wasmboy.

CLI Reference

To view all available commands and options for the OWD CLI, run:

pnpm desktop --help

View complete CLI Help Menu

desktop — add apps, modules, and themes to your Open Web Desktop

USAGE
  desktop                 Open the control panel (interactive TUI)
  desktop dev [--playground]  Start dev server (auto-detects module playground)

CONTROL PANEL (Bubble Tea)
  d / x                   Start / stop the dev server
  s                       Apply queued package and theme changes
  1 / 2 / 3               Apps / Modules / Themes catalog tabs
  ↑ / ↓ / Space           Navigate and select packages
  f                       Find the optional Nuxt file service
  c / u                   Manage / update the selected package
  g / r                   Settings / refresh catalog
  n                       Create a new app or module
  q                       Quit
  desktop init [dir] [--framework nuxt|react]  Create a desktop project
  desktop add <package> [options]
  desktop add <kind> <name> [options]
  desktop validate [path...]  Check Nuxt module + playground layout
  desktop template [--dry-run] [--check]  Regenerate client/template/ (maintainers)

TEMPLATE (monorepo maintainers)
  desktop template              Write template/ from blueprint + desktop/ + latest npm versions
  desktop template --dry-run    Show planned @owdproject/* and starter versions
  desktop template --check      Fail if committed template/ differs (CI)

VALIDATE
  desktop validate            Validate cwd package, or all apps/themes/modules at repo root
  desktop validate .          Validate explicit package directory
  desktop validate apps       Validate every @owdproject/* module under apps/
  --json                      Machine-readable output
  --strict                    Treat warnings as failures
  --smoke                     Run dev:prepare + nuxt build playground (slow, CI)

INSTALL SOURCES (control panel or CLI)
  npm                   registry (default for desktop add)
  --dev                 clone github.com/owdproject/<package>
  --from <user>         clone from GitHub user or full git URL (SSH supported)

EXAMPLES
  pnpm desktop            # control panel
  pnpm desktop dev        # monorepo desktop (from repo root)
  cd apps/owd-nuxt-app-about && pnpm desktop dev   # about app playground
  pnpm desktop dev --playground           # force playground when cwd is in a module
  desktop init my-desktop # scaffold + pnpm install + control panel
  desktop add nuxt-app-todo --npm
  desktop add nuxt-app-todo --dev
  desktop add nuxt-module-pinia-persistence --from dxlliv

KINDS (optional — inferred from the package name)
  app       nuxt-app-*    → apps/     (react-app-* for React desktops)
  module    nuxt-module-* → packages/ (nuxt-kit-*, react-kit-* and *-template are not listed in the control panel)
  theme     nuxt-theme-*  → themes/   (react-theme-* for React desktops)

OPTIONS
  --playground      Start the module playground dev server (when cwd is inside an @owdproject/* package with playground/)
  --from <source>   Git source (user, user/repo, or URL)
  --branch <name>   Git branch to clone
  --npm             Install from npm (default when --from is omitted)
  --dev, --workspace  Clone from github.com/owdproject/<package>
  --protocol https|ssh  With --from <user>, use HTTPS (default) or SSH clone URL
  --dry-run         Print the plan without changing anything
  -h, --help        Show this help

--from <source>
  (omit)          npm registry (default)
  npm             npm registry
  owdproject      Clone official repo (monorepo only)
  <github-user>   Clone github.com/<user>/<package> (your fork)
  <user>/<repo>   Explicit GitHub repo
  <git-url>       Full clone URL

LEGACY (still supported)
  desktop install-app @owdproject/nuxt-app-todo
  → prefer: desktop add nuxt-app-todo

License

Open Web Desktop is released under the MIT License.