Hara OS

Browser-native isolated Hara OS (32-bit) environment. Open hara.html, boot a real Linux userspace, and work in a terminal. The guest cannot see the host filesystem, processes, or credentials.

Product: Hara OS
Guest distro: Hara OS
Source: github.com/cumakurt/hara
Maintainer: Cuma KURT <cumakurt@gmail.com>
Developer: linkedin.com/in/cuma-kurt-34414917
License: GNU GPL v3 or later

What it is

Hara OS embeds copy/v86 (x86 → WebAssembly JIT) and boots a custom i686 kernel plus a Debian i386 userspace branded as Hara OS. This is a real process/ABI environment (bash, apt, dpkg, python3, …), not a JavaScript command fake.

v86 does not implement x86_64 long mode, so the guest is 32-bit by design.

How it works

1. A Web Worker runs v86 and a Pentium 4–class CPU.
2. Hara OS boots from assets/bzImage with assets/hara-rootfs.img as /dev/sda.
3. Serial console output is batched out of the worker and rendered by xterm.js (root@hara:~#).
4. Guest state (CPU, RAM, dirty sectors) is persisted through v86 save_state into OPFS or IndexedDB, and can be exported as a .wlnx snapshot.
5. Built-in WISP on the UI server gives the guest TCP/IP when Internet access is on.

How to run

Install Node.js 22+ (LTS). Keep assets/bzImage and assets/hara-rootfs.img in this folder (~1.5 GiB). Then use the launcher for your OS — it installs dependencies, builds the UI, starts the server, and opens the browser.

OS	Double-click or terminal
Linux	./run-linux.sh
macOS	./run-macos.sh or double-click run.command
Windows	double-click run-windows.bat or powershell -File .\run-windows.ps1

Unix shortcut: ./run.sh (detects Linux vs macOS).

Then use http://127.0.0.1:8787/hara.html (the script opens it for you).

Do not double-click hara.html. file:// is degraded (KL-008).

You need make image (Docker) once if the guest disk is missing. Rebuilding the guest image on Windows is easier in WSL2 Ubuntu or Docker Desktop.

Manual commands (any OS with Node 22+):

npm install
npm run build
npm run serve

Sudo password (after a local make image / Docker build): MustafaKemalAtaturk for both cuma and root. Host copy:

Get-Content .\build\sudo-password

Optional internet for apt/curl: make serve includes a WISP gateway at /wisp. Leave the relay URL empty and keep Internet access checked. Private network and host access are off until you enable them and click Apply and restart.

How to build

make build          # JS/CSS bundle
make image          # Hara OS rootfs + current i686 kernel (Docker)
make test           # unit + security tests
make release        # dist artifacts + checksums
make single-html    # portable HTML (warns on large disk embed)

Details: BUILD.md.

Single HTML

make single-html

Produces dist/hara.single.html. WASM/BIOS can be embedded; the Hara OS disk is large — the build prints a size warning and will not silently embed a multi-hundred-megabyte image.

Hara OS image

make image

Debian bookworm i386 debootstrap + Hara OS /etc/os-release + upstream i686 kernel (Linux 7.1.x, fallback 6.18 LTS). Packages still come from Debian mirrors. The distro identity is Hara OS.

sudo password

Default password for root and cuma is MustafaKemalAtaturk. It is hashed with yescrypt into guest /etc/shadow at image build time. It is never written to HTML, JavaScript, console.log, or localStorage.

HARA_PASSWORD='...' ./tools/set-password.sh

set-password.sh updates assets/hara-rootfs.img in place when that file exists. A host-only copy is stored in gitignored build/sudo-password. Change the default before any public release.

Storage, snapshots, and files

• Session persistence: guest state is automatically saved after every command (Enter key), on tab hide/close, and via periodic checkpoints (every 10 s). On the next page load the session is restored from the last checkpoint instead of cold-booting.
• Snapshot: Snapshots panel → Export writes a .wlnx file containing the live guest state; Import restores it and reloads.
• Factory reset: Snapshots panel → Factory reset drops the saved state and reloads.
• Malformed snapshots are rejected (bad magic/version, path traversal, oversized headers, truncated payloads).
• Files: the Files panel stages a picked file in browser storage only. Delivery into the guest filesystem needs the 9p bridge, which is not in this build yet.

Networking

Default: Internet ON through the built-in WISP gateway (/wisp on the same server as the UI). Private network OFF. Host access OFF.

The three Network checkboxes are enforced by the gateway after DNS resolution:

• Internet access — public IPv4 (apt, curl, HTTPS)
• Private network — RFC1918 and link-local, including 169.254.169.254
• Host access — loopback and this machine, reachable from the guest as 192.168.86.1

Leave the relay URL empty to use the built-in gateway. A custom wisp:// URL still receives the same query flags. Settings apply after Apply and restart. See SECURITY.md.

Security model

Guest is confined to emulator memory and a virtual disk. Host /, C:\, cookies, SSH keys, and localhost services are not mapped. Clipboard and file import/export are explicit. See SECURITY.md.

Browser limits

No KVM, no raw NIC, no USB passthrough, no 64-bit guest. Documented in KNOWN_LIMITATIONS.md.

License

Copyright (C) 2026 Cuma KURT.

Hara OS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE.

Upstream components keep their own licenses (v86 BSD-2-Clause, Linux GPL-2.0, Debian packages, xterm.js MIT). Details: THIRD_PARTY_NOTICES.md.

Documentation

Doc	Contents
ARCHITECTURE.md	UI, worker, disk, WISP
BUILD.md	make build / make image
DEVELOPMENT.md	checks, overlay sync, disk cleanup
SECURITY.md	threat model, CSP, SSRF
TESTING.md	unit, security, Playwright
KNOWN_LIMITATIONS.md	emulator and browser limits
CHANGELOG.md	user-facing changes
LICENSE	GNU GPL v3 or later
THIRD_PARTY_NOTICES.md	upstream licenses