driftwood/docs/USER-GUIDE.md

Driftwood User Guide

Getting started

Installation

From source:

cargo build --release
sudo install -Dm755 target/release/driftwood /usr/local/bin/driftwood

Arch Linux (AUR):

yay -S driftwood

Flatpak:

flatpak install app.driftwood.Driftwood

First launch

When you first open Driftwood, you'll see an empty state with two options:

• Scan Now - Immediately scan the default directories (~/Applications and ~/Downloads) for AppImage files
• Preferences - Configure which directories to scan and other settings

Driftwood will discover all AppImage files (both Type 1 and Type 2) in your configured directories and add them to its library.

Library view

The main screen shows all your discovered AppImages in either grid or list mode. Toggle between views with the button in the header bar.

Status badges

Each AppImage card shows colored badges indicating:

• Wayland status - Green (native), yellow (XWayland), red (X11 only)
• FUSE status - Green (native FUSE), yellow (extract-and-run), red (cannot launch)
• Update available - Blue badge when a newer version is detected
• Security - Red badge if known vulnerabilities are found

Searching

Use the search bar to filter AppImages by name or file path. The search is debounced - it waits 150ms after you stop typing before filtering.

Keyboard shortcuts

• Ctrl+Q - Quit
• Ctrl+D - Open dashboard
• Ctrl+U - Check for updates

Detail view

Click any AppImage card to see its full detail page. The detail view has these sections:

Identity

App name, version, developer, description, and categories extracted from the AppImage's embedded .desktop file.

Desktop integration

Shows whether the AppImage is integrated into your desktop menu. You can integrate or remove integration from here.

Runtime compatibility

FUSE status (how the AppImage can be mounted) and Wayland compatibility (whether the app supports Wayland natively or needs XWayland).

Sandboxing

Toggle Firejail sandboxing for this AppImage. When enabled, the app launches inside a Firejail container with --appimage flag. Requires firejail to be installed.

Updates

Shows the update type (GitHub Releases, GitLab, zsync), current and latest versions, and lets you check for and apply updates.

Usage

Launch count and last launched date.

Security

Results of CVE scanning against bundled libraries. Shows counts by severity (critical, high, medium, low).

Disk footprint

Config, data, and cache directories associated with this AppImage. Shows estimated size and discovery confidence.

File details

File path, size, SHA256 hash, AppImage type, architecture, and timestamps.

Scanning

Automatic scanning

By default, Driftwood scans on startup. Disable this in Preferences under Behavior > "Scan on startup".

Manual scanning

Use the "Scan for AppImages" option in the hamburger menu or run:

driftwood scan

Scan optimization

On subsequent scans, Driftwood skips files that haven't changed (same size and modification time) and already have all analysis complete. This makes re-scans much faster.

Adding scan directories

Go to Preferences > General > Scan Locations to add or remove directories. Subdirectories are not scanned recursively.

Desktop integration

Driftwood creates standard .desktop files in ~/.local/share/applications/ with the prefix driftwood-. Icons are installed to ~/.local/share/icons/hicolor/.

To integrate an AppImage:

1. Open its detail view
2. Click "Integrate" in the Desktop Integration section
3. Confirm in the integration dialog

To remove integration:

1. Open its detail view
2. Click "Remove Integration"

Updates

Checking for updates

• Single app: Open detail view and click "Check for Updates"
• All apps: Use the hamburger menu "Check for Updates" or driftwood check-updates

Applying updates

When an update is available, click "Update Now" in the update dialog. Driftwood downloads the new version and replaces the old file.

Old version cleanup

After a successful update, Driftwood handles the old version based on your preference (Preferences > Behavior > "After updating an AppImage"):

• Ask each time (default) - Shows a dialog asking whether to remove the backup
• Remove old version - Automatically deletes the backup
• Keep backup - Saves the old version with a .old extension

Security scanning

Driftwood extracts the list of shared libraries (.so files) bundled inside each AppImage and queries the OSV.dev vulnerability database for known CVEs.

Running a scan

• Single app: Open detail view and click "Run Security Scan"
• All apps: driftwood security
• Single app CLI: driftwood security ~/path/to/app.AppImage

Interpreting results

Results show CVE IDs grouped by severity. Each CVE includes:

• CVE identifier and severity level
• CVSS score (if available)
• Summary of the vulnerability
• Affected library and version
• Fixed version (if known)

Limitations

• Not all bundled libraries can be identified
• Version detection uses heuristics and may be inaccurate
• Results should be treated as advisory, not definitive

Duplicate detection

Driftwood detects:

• Same app, different versions - Multiple version files of the same application
• Identical files - Same SHA256 hash in different locations

Access via the hamburger menu "Find Duplicates" or driftwood duplicates.

Disk cleanup

The cleanup wizard (hamburger menu > "Disk Cleanup") helps reclaim space by:

• Identifying orphaned desktop entries for deleted AppImages
• Finding associated config/data/cache directories
• Showing total reclaimable space

Orphaned entries

When an AppImage is deleted outside of Driftwood, its .desktop file and icon remain. Driftwood detects these orphans and offers to clean them up.

• Automatic detection on the dashboard
• Manual cleanup via hamburger menu or driftwood clean-orphans

Dashboard

The dashboard (Ctrl+D or hamburger menu) shows system health:

• FUSE availability (fuse2, fuse3, or none)
• Wayland session information
• Total disk usage by AppImages
• Orphaned entry count
• Security alert summary

CLI reference

driftwood                      # Launch the GUI
driftwood scan                 # Scan for AppImages
driftwood list                 # List all AppImages (table format)
driftwood list --format json   # List as JSON
driftwood inspect <path>       # Show AppImage metadata
driftwood integrate <path>     # Create .desktop file and icon
driftwood remove <path>        # Remove desktop integration
driftwood launch <path>        # Launch with tracking
driftwood launch --sandbox <path>  # Launch in Firejail
driftwood check-updates        # Check all for updates
driftwood duplicates           # Find duplicates
driftwood security             # Scan all for CVEs
driftwood security <path>      # Scan one for CVEs
driftwood footprint <path>     # Show disk footprint
driftwood status               # Show system status
driftwood clean-orphans        # Remove orphaned entries

Preferences

Access via hamburger menu > Preferences.

General

• Color Scheme - Follow system, light, or dark
• Default View - Grid or list
• Scan Locations - Directories to scan

Behavior

• Scan on startup - Auto-scan when the app opens
• Check for updates - Periodically check for newer versions
• Auto-integrate new AppImages - Automatically create .desktop files
• Confirm before delete - Show confirmation dialogs
• After updating - Old version cleanup policy (ask/always/never)

Security

• Auto-scan new AppImages - Run CVE scan on newly discovered AppImages