Description of Changes

TL;DR

• Flatpak apps installed in the Flatpak VM now automatically appear in the GUI VM's app library and can be launched like any other app
• Clicking a Flatpak app in the app library routes the launch through givc to the Flatpak VM, where the app is started via flatpak run
• A single persistent Waypipe server replaces the previous per-app Waypipe instances, simplifying app VM configuration and fixing some display and environment config issues

1. Flatpak Desktop Entry Export

Flatpak app desktop entries installed in the Flatpak VM are automatically exported to the GUI VM, where they appear in the app library and can be launched like any other app.

How the export works:

• Systemd service (flatpak-share-installer) watches for installed Flatpak apps and copies the flatpak exports/share dir (which includes the desktop entries and icons) to the Unsafe share (/home/appuser/Unsafe share/.flatpak-share)
  • Size impact - tested with 3 apps (Spotify, Discord, Solitaire), 216K of space is used.
    These are mostly icons (svg or png), .desktop entries, and some metainfo files.
• The Unsafe share is configured as an XDG profile in the GUI VM via environment.profiles, making the entries visible to the DE
• Each entry's Exec= field is rewritten to route the launch through givc's flatpak-run command, which (basically) triggers flatpak run <app-id> in the Flatpak VM
  • The flatpak-run givc app actually reads the real desktop entry for the given app-id and executes that in Flatpak VM.

Desktop Entries' Export Visualized

flowchart LR
    subgraph FLATPAK_VM["Flatpak VM"]
        INSTALLED["installed flatpak apps"]
        EXPORTER["flatpak-share-installer"]
        EDITED["desktop entries with rewritten Exec="]
        SHARE["Unsafe flatpak-vm share"]
        INSTALLED --> EXPORTER --> EDITED --> SHARE
    end

    subgraph GUI_VM["GUI VM"]
        PROFILES["environment.profiles adds share as XDG profile"]
        APPLIBRARY["app appears in app library"]
        SHARE --> PROFILES --> APPLIBRARY
    end

Flatpak App Launch Flowchart

flowchart LR
    USER["user clicks desktop entry"]
    EXEC["Exec= runs ghaf-open flatpak-run with http://app.id"]
    GIVC_GUI["givc in GUI VM"]
    GIVC_FLATPAK["givc in Flatpak VM"]
    RUN["run-flatpak-app"]
    APP["app starts in Flatpak VM"]

    USER --> EXEC
    EXEC --> GIVC_GUI
    GIVC_GUI -- "flatpak-run url=http://app.id" --> GIVC_FLATPAK
    GIVC_FLATPAK --> RUN --> APP

2. Persistent Waypipe Server

Previously, a new Waypipe server instance was spawned for every app launch, requiring run-waypipe to be explicitly prefixed to each givc app definition. This made launching apps across VMs unintuitive, as it was unclear which environment variables (WAYLAND_DISPLAY, DISPLAY, XDG_SESSION_TYPE, etc.) needed to be set for which app. Running multiple apps simultaneously also meant multiple Waypipe server instances running at the same time unnecessarily.

What changed:

• A single persistent Waypipe server now runs as a systemd user service in the App VM, listening for Wayland connections at $XDG_RUNTIME_DIR/wayland-ghaf
• Apps are launched directly via their binaries with no Waypipe arguments or wrapper scripts. They automatically attach to the persistent server via WAYLAND_DISPLAY=wayland-ghaf
• All required environment variables are set once at the session level, so any app launched in the VM gets the correct display configuration automatically
• Optionally, an XWayland Satellite instance is also managed as a user service through the same Waypipe server, enabling X11 apps to run in the App VM via DISPLAY=:99

The following environment variables are set in the AppUser session:

WAYLAND_DISPLAY=wayland-ghaf
DISPLAY=:99
XDG_SESSION_TYPE=wayland
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus

Side-by-side Comparison

Old Approach Flowchart

flowchart TB
    subgraph BEFORE["BEFORE"]
        direction TB
        subgraph GUIVM_OLD["GUI VM"]
            CLIENT_OLD["waypipe client <- compositor"]
        end
        subgraph APPVM_OLD["App VM (flatpak)"]
            SP["Spotify"]
            DI["Discord (X11)"]
            WP1["waypipe server #1"]
            WP2["waypipe server #2"]
            VSOCK["vsock"]
            SP --> WP1 --> VSOCK
            DI --> WP2 --> VSOCK
        end
        VSOCK --> CLIENT_OLD
    end

New Approach Flowchart

flowchart TB
    subgraph AFTER["AFTER"]
        direction TB
        subgraph GUIVM_NEW["GUI VM"]
            CLIENT_NEW["waypipe client <- compositor"]
        end
        subgraph APPVM_NEW["App VM (flatpak)"]
            SERVER["waypipe server (systemd) (+ optional xwayland-satellite)"]
            VSOCK["vsock"]
            SP["Spotify"]
            DI["Discord (X11)"]
            SP -- "WAYLAND_DISPLAY=wayland-ghaf" --> SERVER
            DI -- "DISPLAY=:99" --> SERVER
        end
        SERVER --> VSOCK --> CLIENT_NEW
    end

Type of Change

• New Feature
• Bug Fix
• Improvement / Refactor

Related Issues / Tickets

• Closes https://jira.tii.ae/browse/SSRCSP-8118

Checklist

• Clear summary in PR description
• Detailed and meaningful commit message(s)
• Commits are logically organized and squashed if appropriate
• Contribution guidelines followed
• Ghaf documentation updated with the commit - https://tiiuae.github.io/ghaf/
• Author has run make-checks and it passes
• All automatic GitHub Action checks pass - see actions
• Author has added reviewers and removed PR draft status

Testing Instructions

Applicable Targets

• Orin AGX aarch64
• Orin NX aarch64
• Lenovo X1 x86_64
• Dell Latitude x86_64
• System 76 x86_64

Installation Method

• Requires full re-installation
• Can be updated with nixos-rebuild ... switch
• Other:

Test Steps To Verify:

Flatpak app desktop entries:

1. Boot into Ghaf
2. Launch the App Store and install some apps (good options include - Spotify (picky), Discord (X11), GNOME Weather (known to cause issues previously)
3. After installation, verify apps appear in the app library (Note: some apps are automatically sorted/categorized, so they may appear in specific app library pages)

Flatpak app launching:

1. Try launching any Flatpak app via their desktop entry from the app library, verify the app opens
2. Try launching any flatpak app through the App Store, verify the app opens
3. (Optional) verify flatpak file browser dialogs open as before, if this was present and tested before

Regression:

1. Test crucial (or all) virtual apps - they should launch properly, have their appropriate border colors, names, icons.