Vula OS

A web-first operating system built on Alpine Linux.
"Vula" is Zulu for "open".

Install · Features · Development · Contributing · License

Alpha Software — Under active development. Not recommended for production use yet.

---

Install

Bare metal

Download, flash, boot — like Ubuntu.

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
postmarketOS	See alpine/ build scripts	PinePhone, Librem 5, OnePlus 6

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.

Docker

Try without installing:

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

Open http://localhost:8080.

---

Features

• Desktop Shell — Window manager, dock, launchpad, multi-desktop, screensaver
• Terminal — Persistent PTY sessions with detach/reattach
• Chromium Browser — Remote browser streamed via WebRTC
• File Manager — Browse, upload, download, manage files
• AI Assistant — Pluggable backend (Ollama, OpenAI, Anthropic) with sandboxed code execution
• App Hub — Install apps from the registry
• Auth & Security — Multi-user, OAuth, sessions, rate limiting
• Remote Access — Built-in tunneling
• Mobile Ready — Alpine Linux and postmarketOS builds

Tech Stack

Layer	Technology
Frontend	React 19, Tailwind CSS 4, Vite 8, xterm.js
Backend	Go (24 services, 110+ API endpoints)
Apps	Python/HTML apps with JSON manifests
Infrastructure	Alpine Linux, Docker, Chromium, GStreamer

---

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

Configuration

All config lives in .env at the repo root:

PORT=8080
APP_URL=http://localhost:8080
LANDING_PORT=3000
LANDING_URL=http://localhost:3000

Project Structure

vulos/
├── src/                  # React frontend
│   ├── auth/             #   Login, setup, lock screen
│   ├── builtin/          #   Terminal, files, browser, activity monitor, etc.
│   ├── core/             #   Settings, app registry, telemetry
│   ├── layouts/          #   Desktop and mobile layouts
│   └── shell/            #   Window manager, dock, launchpad
├── backend/              # Go backend (24 services)
├── apps/                 # Plugin apps with JSON manifests
├── landing/              # Landing page & docs (separate server)
├── alpine/               # postmarketOS build scripts
└── dev.sh                # Dev, build, deploy script

---

Releases

Each release produces:

• System images — vulos-vX.X.X-x86_64.img.gz and vulos-vX.X.X-arm64.img.gz for bare metal
• 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

1. Fork and clone
2. ./dev.sh to run locally
3. Create a branch (feat/, fix/, docs/, refactor/)
4. Open a PR

See DEVELOPMENT.md for detailed setup.

---

License

MIT

Built with purpose. Open by design.