ffwebapps Documentation

Design and technical reference for ffwebapps — native, chromeless web apps for Linux, built on Firefox's first-party Web Apps. Last updated 2026-06-29.

ffwebapps runs any website as a standalone desktop app: its own window with no tabs or address bar, its own dock identity, and a system-tray icon with an unread badge. Rather than patching Firefox's chrome, it drives Firefox's first-party Web Apps (Taskbar Tabs) feature and configures it through supported extension points — a privileged _autoconfig.cfg, a profile user.js, and userChrome.css. There is no ffwebapps daemon: the running app is a Firefox process that serves one Unix socket, and everything else — the CLI, the tray, the GTK GUI — is a short-lived client of it. These pages document each part from its real implementation.

Architecture & Design

• Architecture Overview CORE
  The binaries, the shared library, the runtime they drive, and the one socket that ties an app to its tray and launcher.
• The Firefox Runtime & Autoconfig CORE
  Driving Web Apps / Taskbar Tabs, the privileged _autoconfig.cfg, the taskbartabs registry, profile prefs, and the chromeless titlebar.
• IPC & the Runtime-Owned Window CORE
  The newline socket protocol, the singleton launcher, close-to-tray, and the hard-won KWin hide/show mechanism.
• Data Model & Storage CORE
  Storage, Config, Site, Profile, and Runtime; the ULID vs UUID identifiers; and the on-disk layout that makes an app fully file-described.

Components

• CLI & Command Model COMPONENT
  The clap command tree, the Run trait, and the three-state update semantics behind site update.
• System Tray COMPONENT
  The ksni StatusNotifierItem, the flock singleton, the menu, and the “tray spawns nothing” invariant.
• GTK Management GUI COMPONENT
  The ffwebapps-gtk app: same-crate in-process calls, off-thread workers, the carousel UI, and live socket control.

Subsystems

• Link Routing & Scope SUBSYSTEM
  Two-layer out-of-scope interception, the in-app allow-list, and the auth/SSO carve-outs that keep logins working.
• Desktop Integration SUBSYSTEM
  The .desktop launcher, icons, autostart, the app_id identity chain, and the KWin position rule.
• Performance Tuning SUBSYSTEM
  Hardware WebRTC, software rendering, real-time scheduling, and the per-app memory caps — and the precedence rule between them.

Build & Operations

• Build, Install & Packaging OPS
  Cargo features and binaries, the runtime link step, the installed footprint, and the Arch package.

ffwebapps by Jordan Johnston — github.com/nine7nine/ffwebapps
A fork of PWAsForFirefox by Filip Š. — native chromeless web apps for Linux | 2026-06-29