Kandelo

Kandelo is an operating system kernel for WebAssembly (Wasm). It runs Unix-style software — shells, editors, web servers, databases, and games — in a browser or Node.js. Programs use POSIX, the standard interfaces for files, processes, pipes, signals, and sockets, to work together.

Try Kandelo in your browser — open the Library to create a computer. Nothing to install.

Kandelo is experimental. POSIX conformance is the goal; some interfaces are incomplete or limited by WebAssembly and browser security rules.

What runs on it

Examples	What you can do
WordPress, nginx, PHP, MariaDB, SQLite	Run web apps and databases
Python, Ruby, Perl	Run scripts and language interpreters
SpiderMonkey-based Node.js runtime	Run JavaScript with a Node.js-compatible API
Clang/LLVM, C/C++ SDK	Compile and run C and C++ inside Kandelo
Git, Vim, nano	Work with source code in a terminal
bash, dash, GNU coreutils	Use shells, pipes, and familiar command-line tools
Freeciv	Play single-player or multiplayer strategy games
DOOM, Quake	Play single-player or multiplayer games with graphics and audio
LÖVE	Run Lua games

See software examples and versions for more. These are upstream projects compiled through Kandelo's SDK; package recipes include portability patches where needed.

Quick start

To build locally, you need macOS or Linux, Git, and Nix with flakes enabled. Nix supplies the compilers, Node.js, and other build tools.

git clone https://github.com/Automattic/kandelo.git
cd kandelo
git submodule update --init libc/musl sdk/rust/libc-upstream
./run.sh setup
./run.sh browser

Open the URL printed by the server, normally http://127.0.0.1:5401. The first setup downloads tools and builds the software needed by the browser. Later runs reuse cached builds. Run ./run.sh setup again after pulling changes. For full test preparation, use ./run.sh setup --all; see Contributing.

To try a package without building everything, compose a small shell that carries only it: ./run.sh partial shell <package>, then ./run.sh browser --partial. See Partial images.

The development server supplies the browser isolation settings Kandelo needs. For custom hosting, see Browser Support.

To change Kandelo, run tests, or compile a C program, start with Contributing.

Using the browser

The Library creates and reopens computers from Base Shell, Web Stack, or WordPress images. Activities starts installed apps on the running computer without rebooting it. Apps share that computer's files and processes.

DOOM, Quake, and Freeciv support multiplayer through browser network sessions. Use the dock's network panel to invite friends; see multiplayer setup.

Computers use browser disk storage by default. Temporary computers may be cleaned up after 24 hours without opening them; keep one through Library to retain it. Browser storage is not a backup.

Persistence is experimental: saved computers from this release will not work in the next release. Export important files before updating Kandelo. See computer storage and retention.

Build C and C++ inside Kandelo

Create a Base Shell computer and open its terminal. The cc and c++ commands download the compiler tools on first use. Try this example:

cat > /tmp/hello.c <<'C'
#include <stdio.h>
int main(void) { puts("Hello, Kandelo!"); return 0; }
C
cc /tmp/hello.c -o /tmp/hello
/tmp/hello

# Build and run the same example as C++
cp /tmp/hello.c /tmp/hello.cpp
c++ /tmp/hello.cpp -o /tmp/hello-cpp
/tmp/hello-cpp

See the in-Kandelo compiler guide for details and current limits.

How it works

Programs (C, C++, Rust → Wasm)
    │ system calls through shared memory
    ▼
Kernel (Rust → Wasm, in a dedicated worker)
    │
    ▼
Host runtime (TypeScript → browser or Node.js APIs)

Each process runs in its own worker. One kernel manages the machine's processes, files, and communication between programs. Programs link against musl, a C library, and a small adapter that sends system calls to the kernel. The host runtime starts workers and connects the kernel to network, display, and other host APIs.

See the architecture reference for the layers and system-call flow, and fork instrumentation for how Kandelo copies a running process.

Capabilities and limits

Kandelo supports files and directories, processes and threads, pipes and signals, sockets, terminals, and graphics/audio devices. Programs can share one machine or communicate over virtual networks and browser WebRTC sessions.

Some system calls and flags are incomplete. WebAssembly also limits memory protection, shared memory between processes, and asynchronous thread cancellation. Browser internet traffic uses fetch/TLS bridges rather than arbitrary raw TCP/UDP sockets.

See POSIX status for supported behavior and WebAssembly limitations for platform boundaries. Browser APIs and file image formats can change: pin your Kandelo revision and rebuild programs and images when their application binary interface (ABI) changes. See API stability.

Learn more

I want to…	Start here
Use the browser app	User guide
Build, change, or test Kandelo	Contributing
Compile a program	C/C++ SDK · Rust SDK
Port software	Porting Guide
Host Kandelo	Static hosting · Optional Spacefast hosting
Understand the internals	Architecture · Repository layout

License

• GPL-2.0-or-later for the platform: kernel, host runtime, SDK, build scripts, and examples.
• MIT for the runtime glue and musl overlay linked into user programs.

Ported packages keep their upstream licenses. See LICENSE for the full licensing model, including running your own proprietary programs.