Quickstart

There are three ways to meet JouleOS. The fastest is to open the live OS — but here is how to build each surface yourself.

1. The browser shell (PWA)

The full shell compiles to ~2 MB of WebAssembly and runs in a tab.

# from the joule-os repo root
wasm-pack build crates/joule-os-pwa --target web \
    --out-dir ../../static/pkg --release --features webgpu

cd static && python3 -m http.server 8889
# open http://localhost:8889/

You get the workspace, draggable surfaces, the intent bar, and live per-surface energy attribution. Type an intent and watch it route down the cascade.

2. Native

cargo run --release -p joule-os-native
# winit + wgpu window; workspace persists under ~/.jouleos/
# also starts the energy bridge on localhost:9911

3. The bare-metal kernel

cargo +nightly build --target x86_64-unknown-none \
    -p joule-os-baremetal-kernel --release

# run it under the emulator (QEMU + ramfb framebuffer)
cargo run -p joule-os-emulator
# or grab a single frame headless:
cargo run -p joule-os-emulator -- --shot frame.png

The same x86_64-unknown-none image boots inside an in-browser virtual machine — that’s the VM you can drive on the live page.

Verify the invariants

cargo test -p joule-os-conformance
# enforces THEOREM v0.2 invariants I1–I20 and AOT ≡ JIT equivalence