VulpesOS/README.md

🇬🇧 English · 🇫🇷 Français

Vulpes OS

The spirit of Firefox OS. A modern Gecko. One shared Gaia.
A community project bringing a web-based phone experience to desktop, Android and native hardware.

🌐 Website · 📦 Downloads · 📝 Changelog · 🐞 Report a bug

🦊 The Web as your interface

Home screen, settings, camera, gallery, messages: Gaia remains the interface, built from HTML, CSS and JavaScript. Vulpes adapts the APIs that these Firefox OS applications expect to a modern Gecko engine and platform-specific services.

This repository now contains the shared interface, desktop host, Android application, Tundra runtime and development tools. This is an early developer preview, not a finished phone operating system.

 

Desktop development screenshots. Capabilities depend on the platform and available hardware.

📥 Choose your platform

Platform	Available today	Engine
Linux desktop	Source checkout, phone-sized Gaia window, development and app tests	Gecko 156.0.1
Android APK	Installable Preview; keeps Android and its permissions underneath	GeckoView 156.0
Pixel 3a · Sargo	Tundra sources; native development build tested on our device	Gecko 156.0.1 ARM64

Android — Preview 17

Download the APK and SHA256SUMS.txt from the Preview 17 release. Installing over an earlier signed Vulpes Preview preserves its data.

• Minimum declared: Android 8 / API 26. Target: API 37.
• Universal APK: ARM64, ARMv7 and x86_64; approximately 600 MiB including GeckoView.
• Camera and Gallery use Gaia, with Android permissions and file import.
• Calls and SMS hand off to Android's applications; Vulpes is not the default SMS or phone app.
• Android 16 emulator workflows are tested. Minimum SDK support is not a claim that every Android device is validated.
• This is a signed development build with Gecko debugging available through authorized ADB, not a production-hardened app.

Linux — run from source

Linux x86_64, Python 3, Git and the system libraries needed by Firefox are required. On Debian/Ubuntu, install git python3 libgtk-3-0 libdbus-glib-1-2 libasound2 (package names may differ by distribution).

git clone https://nnsprod.com/git/oversu/VulpesOS.git
cd VulpesOS
./setup.sh
./run.sh

setup.sh downloads the pinned Mozilla engine and verifies its checksum. Normal startup opens the Gaia interface without a debugger. Profiles and downloaded engines stay outside Git.

Pixel 3a — native Tundra development

Tundra boots Gecko and Gaia directly, using Linux userspace and the Android hardware services selected for the device.

Our installed Sargo development image has passed startup and persistence checks. Real calls and two-way SMS have been observed; the latest checks cover conversation rendering, camera sensor switching, full-resolution JPEG capture, touch focus, digital zoom and bounded vibration.

A standalone installation has now been tested locally. The Fastboot package provides the system, fresh writable storage and the hardware components paired with the kernel. It replaces userdata, boot_a, dtbo_a and vbmeta_a: startup no longer uses files from an old Droidian installation and requires neither an Android session nor ADB. Two boots from internal storage passed eleven Gaia and ten native checks each and retained settings.

Installation requires an unlocked Pixel 3a (Sargo) and erases all existing userdata. The bootloader and device-specific calibration remain in place. This candidate currently reserves an 8 GiB volume, including 1 GiB of writable data; automatic expansion is not implemented yet. It has been tested on our Pixel, not every existing firmware combination.

The standalone package is not yet available as a download in this release. Build recipes and the installer are prepared; hardware component provenance and redistribution review are still pending. Development-phone backups and maintenance keys are excluded from the generic package.

🛠️ Latest source improvements · 8 October 2026

• Camera: serialized sensor switching, reliable release and binary photo transport. Front/rear capture, focus, zoom and Gallery opening tested on our Pixel 3a.
• Contacts: refreshed details after editing, restored SMS/number-picker/dialer flows, and Gallery photo selection. Desktop tests cover search, cropping, favourites and deletion; native tests cover creation, editing and cross-app navigation.
• Marketplace: integrated application installation with permission restrictions and controlled return to Gaia.
• Tundra: standalone build/recovery tools, pinned Bluetooth runtime packages and native trusted certificates. Bluetooth hardware discovery works; Gaia pairing and profiles remain unfinished.

These are source updates, newer than the published Preview 17 APK. Updated Android assets are prepared, but no new APK or native image containing all these fixes is published. The latest native candidate is tested in RAM; cellular registration remains under investigation and two-way call audio is not yet qualified. See changelog.json for the shared desktop/Android/Tundra history.

✨ What is shared

• One Gaia base: interface and common services serve desktop, Android and Tundra.
• Original applications: Camera, Gallery, Settings and Messages keep their Gaia UI, backed by platform adapters.
• Editable web code: change served assets in assets/webapps/, shared compatibility code in host/, and replacements in overrides/. Restart/reload to test; no Gecko rebuild is needed for these changes. Some historical gaia/ sources still need their bundled counterparts updated.
• A replaceable engine: pinned downloads, checksum verification, isolated compatibility checks and rollback tools. An engine update is tested and explicitly selected; compatibility is not guaranteed automatically.
• Separate version numbers: Vulpes release, Gaia, Gecko and hardware adaptation are reported independently. GeckoView 156.0 is not presented as desktop Gecko 156.0.1.

🧪 Current limits

This preview contains incomplete hardware adapters and legacy application behavior. On Sargo, camera preview is around 16 fps; flash/video, automatic sensor rotation and full suspend remain incomplete. Network registration can be unstable and two-way call audio still needs end-to-end qualification. A reported large dialog after SMS sending remains under investigation.

On Android, platform integration follows Android permissions and lifecycle restrictions. Gaia alarms are not guaranteed after Android stops Vulpes. Unsupported controls may remain visible but disabled. Development/test applications are included.

Keep a backup before testing. Include the platform, Vulpes/Gecko versions and reproduction steps when reporting a problem; remove phone numbers, contacts and other personal information from logs.

🛠️ Build the Android APK

cd android
./build-apk.sh

The script installs the pinned toolchain, packages the shared Gaia resources and builds a signed development APK in android/dist/. Android SDK licenses may need acceptance. A fresh checkout generates its own signing key; it cannot update an APK signed by the project's private release key.

📜 Credits and licenses

Vulpes OS is a community project by OverSu / NNS Production, inspired by Firefox OS. Thanks to Mozilla, Gaia contributors, Capyloon, Droidian, UBports, libhybris, Debian, AOSP and the communities keeping open mobile systems alive.

New Vulpes code uses MPL 2.0. Gaia retains Apache 2.0 and inherited components retain their own licenses and notices. See LICENSE, NOTICE and Gaia's license. Preserve the applicable attribution and license notices in forks.

Vulpes OS is independent of Mozilla and is not an official Firefox OS release.