438 lines
17 KiB
Markdown
438 lines
17 KiB
Markdown
<div align="center">
|
|
|
|
# :evergreen_tree: Driftwood
|
|
|
|
**Your apps. Your computer. No middleman.**
|
|
|
|
A friendly, modern AppImage manager for Linux desktops -
|
|
built by the community, owned by no one.
|
|
|
|
<br />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<br />
|
|
|
|
*No accounts. No tracking. No data harvested. No profit motive.*
|
|
*Just a tool that helps you manage your apps, and gets out of the way.*
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## :sparkles: What is Driftwood?
|
|
|
|
**Driftwood is a graphical app manager for AppImages.** AppImages are portable
|
|
Linux applications that come as a single file - no installation needed, no
|
|
package manager required, no root access, no corporate app store standing between
|
|
you and the software you want to run.
|
|
|
|
But managing AppImages by hand can be confusing. Making them show up in your app
|
|
menu, checking for updates, knowing if they're safe - that's a lot of work,
|
|
especially if you're new to Linux.
|
|
|
|
Driftwood handles all of that for you with a clean, easy-to-use interface. It
|
|
runs entirely on your machine - nothing is sent anywhere, nothing is collected,
|
|
nothing is monetized.
|
|
|
|
---
|
|
|
|
## :raising_hand: Who is this for?
|
|
|
|
- **People new to Linux** who want a simple, welcoming way to manage their apps
|
|
- **Anyone who downloads AppImages** and wants them organized, updated, and
|
|
integrated into their desktop without friction
|
|
- **People who care about privacy** and want to know exactly what their apps
|
|
contain and whether any bundled libraries have known security issues
|
|
- **People who believe software should be accessible to everyone** - Driftwood
|
|
meets WCAG 2.2 AAA accessibility standards
|
|
- **Power users** who want a full command-line interface alongside the GUI
|
|
|
|
---
|
|
|
|
## :framed_picture: What does it look like?
|
|
|
|
Driftwood uses GTK4 and libadwaita, so it looks and feels like a native GNOME
|
|
app. It has three main views:
|
|
|
|
| View | What it does |
|
|
|------|-------------|
|
|
| **Installed** | Shows all your AppImages in a grid or list with status badges |
|
|
| **Catalog** | Browse and discover new AppImage apps from the community |
|
|
| **Updates** | See which apps have newer versions and update them |
|
|
|
|
Click any app to see its full details - version info, security status, disk
|
|
usage, screenshots, and more.
|
|
|
|
---
|
|
|
|
## :star2: Features
|
|
|
|
### :package: App Library
|
|
|
|
- **Automatic scanning** - Driftwood finds all AppImage files in your chosen
|
|
folders (like `~/Applications` or `~/Downloads`)
|
|
- **Grid and list views** - See your apps as cards with icons, or as a detailed
|
|
list - whichever you prefer
|
|
- **Search and sort** - Find apps by name, sort by name, size, or when you added
|
|
them
|
|
- **Tags** - Label your apps with custom tags and filter by them
|
|
- **Selection mode** - Select multiple apps at once for batch actions
|
|
- **Drag and drop** - Drop an AppImage file onto the window to add it
|
|
|
|
### :globe_with_meridians: App Catalog
|
|
|
|
- **Browse community apps** - Discover AppImage apps shared by developers and
|
|
communities - no walled garden, no curation fees, no gatekeeping
|
|
- **Category filters** - Browse by Audio, Games, Graphics, Development, and more
|
|
- **Featured apps** - A rotating carousel of highlighted apps
|
|
- **Search** - Find apps by name across the entire catalog
|
|
- **App details** - See descriptions, screenshots, star counts, and download
|
|
numbers
|
|
- **One-click install** - Download and add apps directly from the catalog
|
|
|
|
### :arrow_up: Updates
|
|
|
|
- **Check for updates** - Scan all your apps for newer versions with one click
|
|
- **Update all at once** - Or update apps individually, your choice
|
|
- **Release notes** - See what changed in each new version before you decide
|
|
- **Automatic backups** - Optionally save old versions before updating, so you
|
|
can roll back if something breaks
|
|
- **Multiple update sources** - Works with GitHub Releases, GitLab Releases,
|
|
zsync delta updates, and OCS feeds
|
|
|
|
### :rocket: Desktop Integration
|
|
|
|
- **Add to app menu** - Make any AppImage show up in your desktop's application
|
|
menu with one click
|
|
- **Icon installation** - Automatically extracts and installs the app's icon
|
|
- **Autostart** - Set apps to launch automatically when you log in
|
|
- **Custom launch options** - Add command-line arguments or environment variables
|
|
per app
|
|
- **Fully reversible** - Remove any app from your menu just as easily as you
|
|
added it. Every change Driftwood makes to your system is tracked and can be
|
|
undone
|
|
|
|
### :shield: Security
|
|
|
|
Your apps shouldn't be a black box. Driftwood helps you see what's inside.
|
|
|
|
- **Vulnerability scanning** - Extracts the shared libraries bundled inside each
|
|
AppImage and checks them against the OSV.dev vulnerability database
|
|
- **CVE details** - Shows the severity (Critical, High, Medium, Low), CVSS
|
|
scores, and which library versions are affected
|
|
- **Security report** - Generate a full report of all your apps and export it as
|
|
HTML, JSON, or CSV
|
|
- **Desktop notifications** - Get notified when a new vulnerability is found in
|
|
one of your apps
|
|
- **Signature verification** - Check GPG signatures and SHA256 checksums
|
|
- **Configurable thresholds** - Choose whether to be notified about only critical
|
|
issues or everything
|
|
|
|
### :jigsaw: FUSE and Wayland Compatibility
|
|
|
|
- **FUSE detection** - Checks whether your system can mount AppImages and tells
|
|
you exactly what to install if it can't
|
|
- **Guided FUSE setup** - A step-by-step wizard that shows you the right install
|
|
command for your distribution - no searching forums, no guesswork
|
|
- **Wayland compatibility** - Detects whether you're running Wayland or X11 and
|
|
flags any compatibility concerns
|
|
- **Fallback launching** - If FUSE isn't available, Driftwood can extract and run
|
|
AppImages directly - you're never locked out of your own software
|
|
|
|
### :broom: Cleanup and Disk Management
|
|
|
|
- **Duplicate finder** - Detects when you have multiple copies of the same app
|
|
or different versions taking up space, and shows how much you'd save
|
|
- **Disk footprint** - Shows config, cache, and data folders each app has created
|
|
on your system - no hidden clutter
|
|
- **Cleanup wizard** - A guided walkthrough that finds orphaned desktop entries,
|
|
leftover caches, and duplicates, then lets you choose what to remove
|
|
- **Orphan cleanup** - Finds and removes menu entries for AppImages that no
|
|
longer exist on disk
|
|
|
|
### :bar_chart: Dashboard
|
|
|
|
- **System overview** - A quick health check showing FUSE status, Wayland status,
|
|
total apps, storage used, and apps needing updates
|
|
- **At-a-glance stats** - Everything about your AppImage setup in one place
|
|
|
|
### :gear: Preferences
|
|
|
|
- **Appearance** - Follow your system's light/dark theme, or pick one
|
|
- **Scan directories** - Choose which folders Driftwood watches for AppImages
|
|
- **Update settings** - Configure automatic update checking, backup behavior,
|
|
and how long to keep old versions
|
|
- **Security settings** - Enable automatic scanning, notifications, and set a
|
|
GitHub token for higher API rate limits
|
|
- **Catalog settings** - Toggle automatic metadata enrichment and removable media
|
|
watching
|
|
|
|
### :lock: Sandboxing
|
|
|
|
- **Firejail support** - Launch apps inside a Firejail sandbox for extra
|
|
isolation
|
|
- **Per-app profiles** - Each app can have its own sandbox configuration
|
|
- **Profile management** - Use local, community, or default Firejail profiles
|
|
|
|
### :wheelchair: Accessibility
|
|
|
|
Software that only works for some people doesn't really work. Driftwood is built
|
|
to meet WCAG 2.2 AAA accessibility standards:
|
|
|
|
- **Full keyboard navigation** - Every single feature is reachable without a
|
|
mouse
|
|
- **Screen reader support** - All buttons, images, and status changes are
|
|
announced to screen readers like Orca
|
|
- **Focus management** - Clear, visible focus indicators (3px outlines) on all
|
|
interactive elements
|
|
- **44px minimum target sizes** - All buttons meet the AAA touch/click target
|
|
standard
|
|
- **High contrast support** - Enhanced borders and colors when your system uses
|
|
high contrast mode
|
|
- **No timing requirements** - Nothing in the app requires fast reactions or
|
|
races against a clock
|
|
- **Semantic roles** - Headings, alerts, status regions, and live announcements
|
|
are all properly marked up for assistive technology
|
|
- **Automated testing** - Ships with an AT-SPI audit tool that walks the live
|
|
accessibility tree and checks for violations
|
|
|
|
### :keyboard: Keyboard Shortcuts
|
|
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Ctrl+1` | Switch to Installed view |
|
|
| `Ctrl+2` | Switch to Catalog view |
|
|
| `Ctrl+3` | Switch to Updates view |
|
|
| `Ctrl+F` | Search |
|
|
| `Ctrl+R` or `F5` | Scan for AppImages |
|
|
| `Ctrl+U` | Check for updates |
|
|
| `Ctrl+K` | Open command palette |
|
|
| `Ctrl+D` | Open dashboard |
|
|
| `Ctrl+,` | Open preferences |
|
|
| `Ctrl+?` | Show keyboard shortcuts |
|
|
| `Ctrl+Q` | Quit |
|
|
|
|
### :desktop_computer: Command Line Interface
|
|
|
|
Every feature is also available from the terminal. The GUI and CLI share the same
|
|
database, so they always stay in sync.
|
|
|
|
```sh
|
|
driftwood scan # Find AppImages in your configured folders
|
|
driftwood list # Show all known AppImages
|
|
driftwood list --format json # Output as JSON
|
|
|
|
driftwood inspect ~/Apps/MyApp.AppImage # Show app metadata
|
|
driftwood integrate ~/Apps/MyApp.AppImage # Add to desktop menu
|
|
driftwood remove ~/Apps/MyApp.AppImage # Remove from desktop menu
|
|
driftwood launch ~/Apps/MyApp.AppImage # Run the app
|
|
driftwood launch --sandbox ~/Apps/MyApp.AppImage # Run in sandbox
|
|
|
|
driftwood check-updates # Check all apps for updates
|
|
driftwood update-all # Update everything
|
|
driftwood verify ~/Apps/MyApp.AppImage # Check integrity
|
|
driftwood verify ~/Apps/MyApp.AppImage --sha256 abc123... # Verify hash
|
|
|
|
driftwood security # Scan all apps for vulnerabilities
|
|
driftwood duplicates # Find duplicate AppImages
|
|
driftwood footprint ~/Apps/MyApp.AppImage # Show disk usage
|
|
driftwood status # System compatibility check
|
|
driftwood clean-orphans # Remove stale menu entries
|
|
|
|
driftwood export # Export app list to JSON
|
|
driftwood export --output ~/backup.json
|
|
driftwood import ~/backup.json # Import app list
|
|
|
|
driftwood autostart ~/Apps/MyApp.AppImage --enable # Autostart on login
|
|
driftwood autostart ~/Apps/MyApp.AppImage --disable
|
|
|
|
driftwood purge # Remove ALL Driftwood system modifications
|
|
```
|
|
|
|
---
|
|
|
|
## :penguin: Which Linux distributions does it work on?
|
|
|
|
Driftwood works on any Linux distribution that has GTK 4.16+ and libadwaita 1.6+.
|
|
In practice, that means most modern distributions released from 2024 onward.
|
|
|
|
| Distribution | Status | Notes |
|
|
|-------------|--------|-------|
|
|
| **Ubuntu 24.04+** | :white_check_mark: Works | GTK4 and libadwaita in default repos |
|
|
| **Fedora 40+** | :white_check_mark: Works | Excellent GTK4 support out of the box |
|
|
| **Arch Linux** | :white_check_mark: Works | Rolling release, always has the latest |
|
|
| **Manjaro** | :white_check_mark: Works | Same packages as Arch |
|
|
| **openSUSE Tumbleweed** | :white_check_mark: Works | Rolling release with current GTK4 |
|
|
| **Debian Testing/Sid** | :white_check_mark: Works | Stable may have older GTK versions |
|
|
| **Linux Mint 22+** | :white_check_mark: Works | Based on Ubuntu 24.04 |
|
|
| **Pop!_OS 24.04+** | :white_check_mark: Works | Based on Ubuntu |
|
|
| **elementary OS 8+** | :white_check_mark: Works | GTK4-based Pantheon desktop |
|
|
| **Gentoo** | :white_check_mark: Works | Build from source |
|
|
| **Alpine** | :white_check_mark: Works | GTK4 in community repos |
|
|
| **NixOS** | :white_check_mark: Works | Package GTK4 + libadwaita via Nix |
|
|
|
|
**Desktop environment**: Driftwood is designed for GNOME but works on any desktop
|
|
that supports GTK4 applications (KDE Plasma, Cinnamon, XFCE, Budgie, Sway, etc.).
|
|
It looks best on GNOME and GNOME-based desktops because it uses libadwaita for
|
|
styling.
|
|
|
|
---
|
|
|
|
## :wrench: System Requirements
|
|
|
|
### What you need
|
|
|
|
| Requirement | Version | What it is |
|
|
|------------|---------|-----------|
|
|
| **GTK** | 4.16 or newer | The toolkit that draws the interface |
|
|
| **libadwaita** | 1.6 or newer | GNOME's design library for modern-looking apps |
|
|
| **SQLite** | 3 | A small, local database engine (stores your app library) |
|
|
| **gettext** | any | Handles translations for different languages |
|
|
|
|
### Optional (but recommended)
|
|
|
|
| Package | What it does |
|
|
|---------|-------------|
|
|
| **libfuse2** or **libfuse3** | Lets AppImages mount themselves (most AppImages need this to run) |
|
|
| **firejail** | Runs apps in a security sandbox for extra isolation |
|
|
| **appimageupdate** | Enables fast delta updates (downloads only what changed, not the whole file) |
|
|
|
|
### For building from source
|
|
|
|
| Package | What it is |
|
|
|---------|-----------|
|
|
| **Rust 1.75+** and **Cargo** | The programming language and build tool |
|
|
| **Meson** | Build system (only for system-wide installation) |
|
|
| **libgtk-4-dev** | GTK4 development headers |
|
|
| **libadwaita-1-dev** | libadwaita development headers |
|
|
| **libsqlite3-dev** | SQLite development headers |
|
|
| **libglib2.0-dev-bin** | Provides `glib-compile-resources` and `glib-compile-schemas` |
|
|
|
|
> Package names vary between distributions. On Fedora, use `-devel` instead
|
|
> of `-dev` (for example, `gtk4-devel` instead of `libgtk-4-dev`). On Arch,
|
|
> the packages are `gtk4`, `libadwaita`, and `sqlite`.
|
|
|
|
---
|
|
|
|
## :building_construction: Building from Source
|
|
|
|
### Quick development build
|
|
|
|
```sh
|
|
git clone https://git.lashman.live/lashman/driftwood.git
|
|
cd driftwood
|
|
cargo build
|
|
cargo run
|
|
```
|
|
|
|
### System-wide installation
|
|
|
|
```sh
|
|
meson setup build --prefix=/usr
|
|
meson compile -C build
|
|
sudo meson install -C build
|
|
```
|
|
|
|
After installing, Driftwood will appear in your application menu.
|
|
|
|
---
|
|
|
|
## :package: Packaging
|
|
|
|
Packaging files are included so anyone can build packages for their distribution:
|
|
|
|
| Format | Location | Notes |
|
|
|--------|----------|-------|
|
|
| **Flatpak** | `build-aux/app.driftwood.Driftwood.json` | Flatpak manifest |
|
|
| **Arch Linux (AUR)** | `packaging/PKGBUILD` | For makepkg |
|
|
| **AppImage** | `packaging/build-appimage.sh` | Build script |
|
|
|
|
If you package Driftwood for a distribution not listed here, let us know - we'd
|
|
love to include it.
|
|
|
|
---
|
|
|
|
## :open_file_folder: Where Driftwood Stores Things
|
|
|
|
Driftwood keeps everything local. Nothing leaves your machine.
|
|
|
|
| What | Location |
|
|
|------|----------|
|
|
| App database | `~/.local/share/driftwood/driftwood.db` |
|
|
| Cached icons | `~/.local/share/driftwood/icons/` |
|
|
| Desktop entries | `~/.local/share/applications/driftwood-*.desktop` |
|
|
| Installed icons | `~/.local/share/icons/hicolor/` |
|
|
| Autostart entries | `~/.config/autostart/` |
|
|
| Settings | GSettings (`app.driftwood.Driftwood`) |
|
|
| Backups | `~/.local/share/driftwood/backups/` |
|
|
|
|
Every modification Driftwood makes to your system is recorded in its database.
|
|
You can undo all of it at any time with `driftwood purge` or through the UI.
|
|
Your system, your rules.
|
|
|
|
---
|
|
|
|
## :test_tube: Accessibility Testing
|
|
|
|
Driftwood ships with an automated accessibility audit tool that uses AT-SPI (the
|
|
Linux accessibility bus) to walk the live widget tree and check for WCAG 2.2
|
|
violations:
|
|
|
|
```sh
|
|
# Full AAA-level audit (builds and launches automatically)
|
|
python3 tools/a11y-audit.py --level aaa
|
|
|
|
# Attach to an already-running instance
|
|
python3 tools/a11y-audit.py --no-launch --level aaa
|
|
|
|
# AA level only
|
|
python3 tools/a11y-audit.py --level aa
|
|
|
|
# Verbose output with live region inventory
|
|
python3 tools/a11y-audit.py --level aaa --verbose
|
|
```
|
|
|
|
The tool checks for:
|
|
|
|
- Interactive widgets without accessible names (SC 4.1.2)
|
|
- Images without alt text or decorative marking (SC 1.1.1)
|
|
- Headings without level attributes (SC 1.3.1)
|
|
- Widgets that aren't keyboard-focusable (SC 2.1.1)
|
|
- Target sizes below 24px (AA) and 44px (AAA)
|
|
- Windows without titles (SC 2.4.8)
|
|
- Vague link text (SC 2.4.9)
|
|
- Content regions without headings (SC 2.4.10)
|
|
- Keyboard traps (SC 2.1.3)
|
|
|
|
Results are printed to the terminal and saved as `a11y-report.json` for CI
|
|
integration.
|
|
|
|
---
|
|
|
|
## :raised_hands: Contributing
|
|
|
|
Driftwood is a community project. There's no company behind it, no investors,
|
|
no roadmap driven by profit - just people building something useful together.
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute code,
|
|
translations, bug reports, or ideas. Every contribution matters, and everyone
|
|
who helps is a co-owner of this project.
|
|
|
|
---
|
|
|
|
## :page_facing_up: License
|
|
|
|
**CC0-1.0 - Public Domain**
|
|
|
|
Driftwood belongs to everyone. It is released into the public domain under the
|
|
[CC0 1.0 Universal](LICENSE) license. You can copy, modify, distribute, and use
|
|
it for any purpose - personal, educational, commercial, anything - without
|
|
asking permission, without paying anyone, without restrictions.
|
|
|
|
Knowledge and tools should be shared freely. This is ours, and it's yours.
|