Stargate

A Kotlin library that provides JVM applications with access to XDG Desktop Portals on Linux.

XDG Desktop Portals originated from the Flatpak project but have since become a widely adopted Linux desktop standard, including Snaps. They can be used by any application, sandboxed or not, to provide a standardized API to common desktop features, such as taking screenshots, recording, and accessing files, that work consistently across desktop environments, like GNOME and KDE, and across display servers including X11 and Wayland.

In addition to XDG Desktop Portals, Stargate also includes support for the Freedesktop Status Notifier Item Specification, which enables system tray icon integration.

Getting Started

Add the dependency to your project (requires JDK 25+):

Gradle (Kotlin DSL)

dependencies {
    implementation("com.github.zugaldia:stargate:0.6.0")
}

Check out the reference app for working examples, or browse the API reference (KDocs).

Supported Portals

Portal definitions are based on XDG Desktop Portal version 1.21.0.

Every portal includes a low-level interface auto-generated from the official XML specification. High-level interfaces with convenience methods and reference app examples are being added iteratively across all portals:

Portal	Low Level	High Level	Example
Registry (host)	docs	docs	app
Account	docs	❌	❌
Background	docs	❌	❌
Camera	docs	❌	❌
Clipboard	docs	docs	❌
Documents	docs	❌	❌
Dynamic Launcher	docs	❌	❌
Email	docs	❌	❌
File Chooser	docs	❌	❌
File Transfer	docs	❌	❌
Game Mode	docs	❌	❌
Global Shortcuts	docs	docs	app
Inhibit	docs	❌	❌
Input Capture	docs	❌	❌
Location	docs	❌	❌
Memory Monitor	docs	❌	❌
Network Monitor	docs	❌	❌
Notification	docs	docs	app
OpenURI	docs	docs	app
Power Profile Monitor	docs	❌	❌
Print	docs	❌	❌
Proxy Resolver	docs	❌	❌
Realtime	docs	❌	❌
Remote Desktop	docs	docs	app
Request	docs	❌	❌
ScreenCast	docs	docs	❌
Screenshot	docs	❌	❌
Secret	docs	❌	❌
Session	docs	❌	❌
Settings	docs	docs	app
Trash	docs	❌	❌
Usb	docs	❌	❌
Wallpaper	docs	❌	❌

Portal Availability and Sandboxing

Both sandboxed (Flatpak and Snap) and unsandboxed applications can use portal interfaces. However, unsandboxed applications running directly on the host may need additional setup for some portals to work.

XDG Desktop Portals rely on an Application ID for permission checks and to show the requesting app's name in dialogs. Sandboxed applications get their identity automatically from the sandbox. Unsandboxed applications must register their Application ID explicitly using the Registry portal before making any portal calls. Without registration some portals like Global Shortcuts will not work and others may have degraded functionality.

This library provides access to the Registry portal through DesktopPortal.registry and includes a isSandboxed() utility function to detect if the application is running inside a sandbox. See the demo application for a working example. This demo application can run both as an unsandboxed app (make run) and as a sandboxed Flatpak (make flatpak-run).

Support for Status Notifier Item Specification

While technically not part of the XDG Desktop Portals specification, this library also supports the related Freedesktop Status Notifier Item Specification. This is essentially the D-Bus interface that allows applications to provide a system tray icon to report their status, and an optional menu.

A word of caution: system tray icons are not well standardized on Linux today and APIs might change if and when desktop environments settle on a common framework. Under the hood, the Status Notifier Item Specification relies on a KDE specification for items (org.kde.StatusNotifierItem) and an Ubuntu specification for menus (com.canonical.dbusmenu). Support across distributions and desktop environments varies, and some distributions require a dedicated GNOME extension to be installed.

This mechanism described above is, in turn, different from the indicator icons provided by GNOME Shell Extensions.

This library abstracts away this fragmentation for the application developer, and the bundled demo application provides a reference example on the "Status Notifier" screen.

Projects Using Stargate

• Speed of Sound — Voice typing for the Linux desktop.

If your application, project, or CLI depends on Stargate, feel free to open a PR to add it to this list.

Contributing

To build the project from source and learn how to contribute, see CONTRIBUTING.md. If you find any issues or limitations, please open a GitHub issue with your use case, it helps us prioritize what to build next.

If you find Stargate useful, consider sponsoring this work.

Built With

Stargate stands on the shoulders of these excellent open source projects:

• dbus-java — A native Java implementation of the D-Bus protocol, enabling JVM applications to communicate over the Linux desktop bus.
• Java-GI — GTK/GNOME bindings for Java, enabling access to native libraries via the modern Panama framework, aka the Foreign Function & Memory API.