MarsOS

MarsOS is an in-progress experiment in building a Linux desktop from the distribution image up through its native interface components. It uses Debian Trixie and KDE Plasma as a working base while replacing parts of the desktop experience with custom Rust applications built directly on Wayland.

Important

MarsOS is a research prototype. The image pipeline, bootable development environment, and several desktop components work, but substantial integration, packaging, reliability, and UX work remains. It is not ready to be installed as a general-purpose or daily-use operating system.

What is implemented

• Reproducible Debian Trixie image construction for ARM64 and x86_64 targets
• KDE Plasma desktop running on Wayland with system-wide configuration overlays
• UTM/QEMU development loop with SSH access from a macOS host
• A custom Rust dock with Wayland window tracking
• A custom Rust header surface
• A Spotlight-style application launcher with fuzzy search and global shortcut integration
• A reusable Rust UI framework for layout, drawing, input, scrolling, animation, icons, and common control state

Why build this

MarsOS is a way to study the systems work hidden beneath a desktop environment: producing bootable images, configuring a Linux userspace, talking to a compositor, drawing pixels, dispatching input, tracking windows, and integrating programs into an existing session.

The Debian/KDE layer provides enough of a usable system to iterate. The custom components make it possible to replace the visible desktop piece by piece instead of beginning with a kernel or an empty framebuffer.

Architecture

┌─────────────────────────────────────────────────────────┐
│ Custom desktop components                               │
│ dock · header · spotlight · reusable Rust UI framework  │
├─────────────────────────────────────────────────────────┤
│ KDE Plasma services and KWin Wayland compositor         │
├─────────────────────────────────────────────────────────┤
│ MarsOS packages, configuration, overlays, and scripts   │
├─────────────────────────────────────────────────────────┤
│ Debian Trixie userspace and Linux kernel                │
└─────────────────────────────────────────────────────────┘

The native components use smithay-client-toolkit and Wayland client protocols for surfaces and events. Rendering is software-based through Skia or tiny-skia, while Taffy provides flexbox/grid layout in the shared UI crate.

Repository map

os/
├── ui/                 # Shared Rust UI framework
├── dock/               # Dock and Wayland window tracking
├── header/             # Desktop header surface and controls
├── spotlight/          # Fuzzy application launcher
├── config/
│   ├── packages/       # Base and desktop package manifests
│   ├── kde/            # System-wide Plasma, KWin, input, and SDDM config
│   └── kernel/         # Kernel configuration experiments
├── overlays/           # Files installed directly into the target image
├── scripts/            # Build, VM, image, and deployment automation
├── Dockerfile.build    # ARM64 image-build environment
└── Cargo.toml          # Rust workspace

Technical highlights

• Wayland layer-shell surfaces and event loops
• Window discovery through KDE/Wayland protocols
• Skia display lists and Taffy-powered layout
• Hit testing, event propagation, reactive state, scrolling, text input, and spring animation
• Freedesktop application and icon discovery
• Global shortcut integration through KDE's kglobalaccel D-Bus interface
• Cross-architecture disk image construction with Docker, debootstrap, GRUB, and QEMU/UTM
• 147 Rust unit tests across the desktop components and UI framework

Run the development image on Apple Silicon

Prerequisites

• macOS on Apple Silicon
• UTM for the GPU-accelerated development VM
• Docker Desktop when rebuilding an image
• sshpass for the overlay deployment script

brew install --cask utm
brew install sshpass

With build/mars-os-arm64.qcow2 present, create or boot the development VM:

bash scripts/test-qemu-arm64.sh

The VM exposes SSH on port 2222:

ssh -p 2222 mars@localhost
# development password: mars

Apply changes from overlays/ and config/kde/ to the running VM:

bash scripts/apply-overlays.sh
ssh -p 2222 root@localhost 'reboot'

Build an image

The image scripts require privileged Linux filesystem operations. On macOS, those operations run inside the supplied Docker build environment:

bash scripts/build-local.sh --desktop

The x86_64 path is intended to run on a Debian or Ubuntu build machine:

sudo bash scripts/setup-ec2.sh
sudo bash scripts/build.sh --desktop
sudo bash scripts/make-iso.sh

Build and test the Rust workspace

The desktop crates depend on Linux and Wayland libraries and should be built inside a Linux environment, not directly on a macOS host.

cargo build --workspace
cargo test --workspace

See spotlight/README.md for a component-level build and installation example.

Next milestones

• Integrate and package all custom Rust components as part of the image build
• Replace remaining stock desktop surfaces with a coherent MarsOS shell
• Stabilize input, multi-display, scaling, and session lifecycle behavior
• Automate end-to-end VM tests for image creation and overlay deployment
• Complete installation and recovery flows
• Establish release images, upgrade strategy, and hardware-support boundaries

License

Original MarsOS code and assets are available under the PolyForm Noncommercial License 1.0.0. Debian, KDE, the Linux kernel, and other bundled upstream projects retain their own licenses.