Vula OS

A web-native operating system built on Debian Linux.
"Vula" is isiZulu for "open".

Install · Features · Development · Contributing · License

Alpha Software — Under active development.

---

What is Vula OS?

Vula OS is a web-native window manager and operating system built on Debian Linux. Instead of streaming an entire remote desktop, Vula streams individual application windows on demand — web apps run as first-class citizens in the browser, and native Linux GUI apps (GIMP, LibreOffice, Blender, games via Wine/Lutris) stream via WebRTC only when you open them.

The four ideas

1. Web-native OS. The shell is a real OS shell — windows, dock, file manager, terminal, settings — but it lives in a browser tab. Open it from your laptop, phone, or a TV at someone else's house and you get the same desktop.
2. Web-app sovereignty. Self-host the apps you'd normally rent from a SaaS company. The bundled app store installs things like Memos, Navidrome, Uptime Kuma, and Vaultwarden as proper OS apps with their own subdomain and isolated network namespace — not embedded iframes, not browser bookmarks.
3. Peering, not federation. Every Vula instance is a server with a stable identity (Ed25519 keypair, vula:<id> URI). Instances message, share files, and place WebRTC calls directly. No middleman, no account on someone else's server. See roadmap/PEERING.md.
4. Real baremetal. Flash the same image to a USB stick and it boots into cage running a fullscreen browser — and that browser is the Vulos shell. The OS is the React app. Native Linux apps (GIMP, Blender, Wine games) stream into windows of that desktop on demand via the same WebRTC pipeline used for remote access. See roadmap/BAREMETAL-INIT.md.

How the pieces fit

• Web apps are first-class — install from apt or Flatpak, they run in isolated network namespaces and load in their own subdomain. No streaming overhead, just proxied HTTP.
• Desktop apps stream on demand — open Audacity and it launches in its own virtual display, streams via WebRTC. Close the window, the stream stops. No always-on VNC session.
• Cloud gaming built in — Wine/Lutris games stream with GPU-accelerated encoding (NVENC, VA-API, AV1). Gamepad, keyboard, and mouse input injected via uinput at kernel level.
• Full OS underneath — real Debian Linux with terminal, file manager, package management. Multi-user with per-user isolation.
• Runs anywhere — flash to bare metal (boots into a WebKit kiosk), deploy to a cloud server, or run in Docker for development.

How to read this project

The repo carries its own project-management docs. If you want to follow along or contribute:

You want to…	Read
Understand the design of a specific area (peering, gaming, init, network, …)	roadmap/ — start at roadmap/README.md
See what's done, what's open, and pick something to work on	tasks.md — start at the "At-a-glance" table
Understand why the project was built a certain way	decisions.md — the running design-decision log
Submit a change	CONTRIBUTING.md
Build / run / deploy	DEVELOPMENT.md

---

Install

Bare Metal (flash to USB)

Download, flash, boot — like Ubuntu. On bare metal, Vulos boots a fullscreen browser via cage; the React shell is the desktop. Native Linux apps stream into windows of that desktop on demand — the same WebRTC pipeline used for remote access, so everything works out of the box on any hardware.

Platform	File	Devices
x86_64	vulos-vX.X.X-x86_64.img.gz	PC, laptop, server
ARM64	vulos-vX.X.X-arm64.img.gz	Raspberry Pi, Pine64, Rock64

# Flash to USB drive
gunzip -c vulos-vX.X.X-x86_64.img.gz | sudo dd of=/dev/sdX bs=4M status=progress

Or use Balena Etcher — drag and drop the .img.gz file.

Cloud Server

Deploy to any Debian server with one command:

./build.sh --deploy YOUR_SERVER_IP --domain os.yourdomain.com

Web apps available at https://{app}.os.yourdomain.com. Wildcard TLS via Caddy + Namecheap/Cloudflare DNS.

Docker (development)

docker run -p 8080:8080 --shm-size=1g --privileged -v vulos-data:/root/.vulos ghcr.io/vul-os/vulos:latest

Open https://lvh.me:8080 (requires mkcert for local TLS).

---

GPU-Accelerated Streaming

Vula OS auto-detects GPU hardware and selects the best encoder for streaming desktop apps and games.

Tier	GPU	Encoder	FPS	Latency	Setup
0	None	VP8 (CPU)	30	~15ms	Default
1	Intel/AMD	H.264/AV1 (VA-API)	60	<2ms	--device /dev/dri
2	NVIDIA	H.264/AV1 (NVENC)	120	<1ms	--gpus all + NVIDIA Container Toolkit

---

Features

Window Manager

• Multiple windows with drag, resize, snap (half/quarter screen like Ubuntu)
• Mission Control (F3) — overview of all windows and desktops
• Multiple desktops with drag-to-move between them
• Dock with running app indicators

Applications

• Terminal — persistent PTY sessions with bash, accessible from anywhere
• Browser — Chromium instances streamed via WebRTC, multiple independent windows
• File Manager — browse, upload, download, manage files
• App Store — install web apps and desktop apps from apt/Flatpak
• Activity Monitor — processes, CPU, memory, network connections
• Settings — theme, display, WiFi, Bluetooth, audio, energy, backups

App Platform

• Web apps run in isolated network namespaces with auth-gated subdomain routing
• Desktop apps (apt/Flatpak) stream via WebRTC with GPU encoding
• Games via Wine/Lutris with gamepad support and low-latency input
• AI Assistant with pluggable backend (Ollama, OpenAI, Anthropic) and sandboxed code execution

Infrastructure

• Multi-user with per-user Linux accounts, sudo, and profile isolation
• Built-in tunnel for remote access from any device
• S3/Restic backup and restore
• 110+ API endpoints across 24 Go backend services

Tech Stack

Layer	Technology
Shell	React 19, Tailwind CSS 4, Vite
Backend	Go (single binary, 24 services)
Streaming	GStreamer, WebRTC (pion), Xvfb
Apps	apt, Flatpak, isolated network namespaces
Base	Debian 13 (Trixie), Caddy

---

Development

git clone https://github.com/vul-os/vulos.git
cd vulos

./dev.sh                # Local dev — Go + Vite HMR (localhost:5173)
./dev.sh deploy         # Full Docker build (localhost:8080)
./dev.sh deploy quick   # Quick rebuild into running container
./dev.sh deploy layer   # Docker rebuild, reuses cached apt layer

Deploy to production

./build.sh --deploy SERVER_IP --domain os.yourdomain.com --dns-namecheap USER APIKEY

See DEVELOPMENT.md for detailed setup, GPU configuration, and environment variables.

Project Structure

vulos/
├── src/                  # React frontend (shell, apps, auth)
├── backend/              # Go backend (24 services, 110+ endpoints)
├── apps/                 # Bundled app manifests
├── registry.json         # App store registry (apt + web apps)
├── landing/              # Landing page
├── build.sh              # Bare-metal image builder + deployer
└── dev.sh                # Dev and Docker deploy script

---

Releases

Each release produces:

• System images — .img.gz for bare metal (flash to USB)
• Docker images — ghcr.io/vul-os/vulos:latest for linux/amd64 and linux/arm64

git tag v0.1.0 && git push origin v0.1.0

Download from the Releases page.

---

Contributing

The short version:

1. Skim tasks.md → "At-a-glance" → pick a todo task whose dependencies are done.
2. ./dev.sh to run locally.
3. Branch as task/<ID> (e.g. task/AUTH-10) or feat/, fix/, docs/, refactor/ for off-roadmap work.
4. Tick the task's acceptance criteria, run go build ./... + npm run build, open a PR.

See CONTRIBUTING.md for the full flow, including how tasks are formatted, where decisions live, and how to report a security issue.

---

License

MIT

Built with purpose. Open by design.