v1.0.0 — Stable

The kernel
for WebOS creators.

Stop spending hours building a bootloader and kernel from scratch. Drop in one file, call one function, and get straight to building your OS.

index.html
<!-- 1. link the kernel -->
<script src="https://webnux.pages.dev/kernel.js"></script>

<!-- 2. your OS starts here -->
<script>
  WebOSKernel.onReady(kernel => {
    // build your OS here
  });
</script>
⎘  View kernel source code
Zero dependencies
Black screen bootloader included
Universal app store
Firebase cloud subsystem
What is it

A kernel that does
the boring parts.

Webnux handles everything a real kernel does — booting, error handling, service management, routing, and a shared app ecosystem — so you can skip straight to building your OS's UI and features.

⬛
Clean Boot Screen
Pure black screen with a spinner while the kernel initialises. No clutter. No branding you didn't ask for.
⚠️
Web-Error Menu
If the kernel fails to load for any reason, a built-in error screen shows the error code, what went wrong, and exactly how to fix it.
⚡
One File
Drop in a single <script> tag. No build tools, no npm, no configuration. Works in any HTML page.
🌐
Universal App Store
Apps built for any WebOS using Webnux can be shared globally with other WebOSes via the built-in app store layer.
How to use

Up and running
in three steps.

The kernel manages its own boot sequence. You only write code for your OS — nothing else.

1
Add kernel.js to your page
Add a single script tag to your WebOS HTML pointing to the kernel on Cloudflare. No downloading, no drag and drop — just the link. The kernel boots automatically when your page loads.
<script src="https://webnux.pages.dev/kernel.js"></script>
2
Call onReady() to start your OS
Everything inside the callback runs after the kernel has fully booted. The black loading screen disappears automatically.
WebOSKernel.onReady(kernel => {
  // mount your UI, start your desktop, etc.
  document.body.innerHTML = `<div id="desktop">...</div>`;
});
3
Use the kernel API in your OS
Register services, add routes, listen to events, load plugins, and publish apps — all through the kernel object.
WebOSKernel.onReady(kernel => {

  // register a service
  kernel.register('storage', myStorageService);

  // add a route
  kernel.router.get('/api/files', handler);

  // emit an OS event
  kernel.events.emit('os:ready');

});
How services load

The kernel starts first.
Then everything else.

Services are loaded in a strict order to make sure the kernel is always stable before any OS code runs.

Kernel
1. Core Subsystems Boot
The kernel initialises its internal subsystems in order: EventBus → Router → Middleware Pipeline → Service Container. If any of these fail, the Web-Error Menu appears with the exact failure code.
Kernel
2. Built-in Routes Register
The kernel registers its own internal routes like /kernel/info and /kernel/services. These are always available and cannot be overridden by OS code.
Auto
3. App Store Layer Initialises
The kernel connects to the global app registry. Any WebOS using the kernel with correct app metadata will be able to see and install apps from other WebOSes automatically.
Creator
4. onReady() Fires
Once everything above is stable, the kernel calls your onReady() callback. This is when your OS code runs. Services you register here are available immediately to your OS and optionally to the app store layer.
Creator
5. Plugins Load
Any plugins your OS installs via kernel.plugin() are installed after onReady runs. Each plugin can register additional services, routes, and middleware without touching the kernel core.
Auto
6. OS Is Live
The kernel is now fully running. The boot screen is gone. Your OS has full control of the page and access to the kernel API for the rest of the session.
Global app store

Build once.
Run on every WebOS.

Apps built for any WebOS powered by Webnux are automatically compatible with every other WebOS using the same kernel — as long as the app metadata is correct.

How the universal app layer works
Each app declares a metadata object that the kernel reads. If the metadata is valid and the WebOS has the app store layer enabled, the app becomes globally discoverable and installable from any other WebOS running the same kernel version.
id *required
com.yourname.appname
name *required
"My App"
version *required
"1.0.0"
kernelVersion *required
"1.0.0"
entry
"https://cdn.com/app.js"
store
true
category
"productivity"
permissions
["storage", "network"]
🛠️
Creator builds app
App declares valid kernel metadata with store: true
🌐
Kernel registers it
App becomes visible in the global app registry shared across all WebOSes
📲
Any WebOS installs it
Any WebOS with the same kernel version can discover and install the app
Add to your WebOS
<script src="https://webnux.pages.dev/kernel.js"></script>
Cloud Subsystem

Firebase. Built into
the kernel.

The kernel ships with a built-in Firebase cloud layer. Fetch data, load cloud apps, and listen to cloud events — all without touching a line of Firebase setup code.

☁️
Lazy Connection
Firebase is only initialised the first time you use it. No cold-start overhead if your OS never needs the cloud.
📦
Cloud App Loading
Call kernel.cloud.loadApps() to fetch apps from Firestore and register them into the AppStore automatically.
🔌
Named Service
The cloud subsystem is available as a named service via kernel.resolve('cloud') — composable with any plugin or middleware.
📡
Cloud Events
The kernel emits cloud:connected, cloud:app:fetched, and cloud:apps:loaded so any part of your OS can react in real time.
Using the cloud subsystem
my-os.js
WebOSKernel.onReady(async kernel => {
  // load all cloud apps into the AppStore
  await kernel.cloud.loadApps();

  // or fetch any Firestore collection yourself
  const news = await kernel.cloud.fetch('news');

  // listen to cloud events
  kernel.events.on('cloud:apps:loaded', ({ count }) => {
    console.log(`Loaded ${count} cloud apps`);
  });
});
API Reference

Everything the kernel
exposes to you.

All kernel APIs are available on the kernel object passed into your onReady() callback, and also on the global window.WebOSKernel.

kernel.onReady(cb)
Register a callback to run once the kernel has fully booted. If the kernel is already booted, the callback fires immediately on the next microtask.
kernel.register(name, service)
Register a named service on the kernel. Services are accessible from anywhere via kernel.resolve(name). Emits service:registered.
kernel.resolve(name)
Retrieve a registered service by name. Throws WK_E005 if the service has not been registered. Built-in: 'cloud'.
kernel.router.get / .post / .put / .delete(path, handler)
Register a route handler on the kernel's internal request router. Supports :param segments. Dispatch with kernel.handle(method, url).
kernel.events.on(event, fn) / .emit(event, data) / .once(event, fn)
Subscribe to or broadcast kernel events. Built-in events include kernel:booting, kernel:ready, cloud:connected, appstore:registered, and more.
kernel.use(fn)
Add a middleware function to the kernel's request pipeline. Signature: async (req, res, next) => void. Runs before every route handler.
kernel.plugin({ name, install(kernel) })
Install a plugin into the kernel. The plugin's install(kernel) method is called immediately. Plugins can register services, routes, and middleware.
kernel.cloud.loadApps() / .fetch(collection)
Cloud subsystem methods. loadApps() fetches the apps Firestore collection and auto-registers valid entries. fetch(name) returns raw documents from any collection.
kernel.handle(method, url, body?, headers?)
Dispatch a request through the kernel's middleware pipeline and router. Returns a response object with status and body. Built-in routes: /kernel/info, /kernel/apps.
Error Codes

When things go wrong,
you'll know exactly why.

Every kernel failure produces a structured error code. The boot error screen shows the code, a plain-English description, and a specific fix — no guessing.

WK_E001
Kernel Initialisation Failed
A required internal subsystem failed to start during boot. Check the console for the specific subsystem that threw.
WK_E002
Event Bus Failure
The kernel EventBus could not be created. Usually caused by a heavily sandboxed iframe or environment that restricts object construction.
WK_E003
Router Subsystem Error
The internal router failed to initialise. Routing and request handling will be unavailable. Check for script conflicts and reload.
WK_E004
Middleware Pipeline Error
The middleware pipeline could not be constructed. Ensure no middleware is registered before the kernel finishes booting — always use onReady().
WK_E005
Service Container Error
The service container failed to initialise, or you called resolve() for a service that was never registered.
WK_E006
Plugin Load Error
A plugin threw during installation. Check the plugin's install() method for uncaught errors or async operations missing await.
WK_E007
App Registration Error
An app's metadata is invalid or incomplete. All four required fields must be present: id, name, version, kernelVersion.
WK_UNKNOWN
Unknown Kernel Error
An unexpected error the kernel doesn't recognise. Open DevTools (F12) and look for red errors in the console.
Modes

One kernel family.
Five configurations.

Each mode ships as its own kernel file, purpose-built for a specific type of WebOS. Drop in the one that matches what you're building — nothing else changes.

1
OS
Standard
A full WebOS kernel with booting, routing, services, app store, and the Firebase cloud subsystem. The default choice for building a browser-based operating system with a desktop UI.
Features: Boot screen · EventBus · Router · AppStore · Cloud · Plugins
<script src="https://webnux.pages.dev/kernel-os.js"></script>
kernel-os.js
2
SMS
Messaging
A kernel trimmed for messaging-style WebOSes. Keeps the core subsystems and cloud layer, but is configured for conversation-driven interfaces rather than a full desktop environment.
Features: Boot screen · EventBus · Router · Cloud · Plugins
<script src="https://webnux.pages.dev/kernel-sms.js"></script>
kernel-sms.js
3
Tools
Headless
A headless kernel with no UI layer. Includes both developer tools (console, inspector) and utility tools (calculator, notes) as kernel services. Designed to run logic and expose APIs — not to render a desktop.
Features: EventBus · Router · Services · Dev tools · Utility tools · Cloud
<script src="https://webnux.pages.dev/kernel-tools.js"></script>
kernel-tools.js
4
OS with Login
Standard
Auth
Everything in Mode 1, plus a built-in login gate. The kernel holds the boot sequence until the user authenticates via Firebase Auth. Your OS code only runs after a successful login.
Features: All of Mode 1 · Firebase Auth · Login gate · User session
<script src="https://webnux.pages.dev/kernel-os-login.js"></script>
kernel-os-login.js
5
SMS with Login
Messaging
Auth
Everything in Mode 2, plus a Firebase Auth login gate. Conversations and cloud data are scoped to the authenticated user. Ideal for multi-user messaging WebOSes.
Features: All of Mode 2 · Firebase Auth · Login gate · User session
<script src="https://webnux.pages.dev/kernel-sms-login.js"></script>
kernel-sms-login.js