swadhin / linuxy public
/ linuxy / docs / USAGE.md
Swadhin Biswas feat: production-ready Linuxy v1.0.0 with comprehensive CI/CD · 3/30/2026
d7d7a56
441 lines · 10.4 KB
Raw Download

Usage Guide

A comprehensive guide to using Linuxy for managing your AppImages.

Table of Contents

Getting Started

First Launch

When you first launch Linuxy, you'll see an empty library. This is normal - you haven't installed any AppImages yet!

# Launch from terminal
linuxy

# Or find it in your application menu under "Utilities"

Quick Tour

  1. Library - Your installed AppImages (default view)
  2. Discover - Browse and find new AppImages
  3. Settings - Configure Linuxy preferences

User Interface

Library View

The Library is where you manage your installed AppImages.

┌─────────────────────────────────────────────────┐
│  Library                                        │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌─────────────┐  ┌─────────────┐              │
│  │   📝 Icon   │  │   🎨 Icon   │              │
│  │   App Name  │  │   App Name  │              │
│  │  120 MB     │  │  85 MB      │              │
│  │ [▶][🔄][🗑] │  │ [▶][🔄][🗑] │              │
│  └─────────────┘  └─────────────┘              │
│                                                 │
└─────────────────────────────────────────────────┘

Each app card shows:

  • Icon - Application icon (auto-extracted)
  • Name - Application name
  • Size & Date - File size and installation date
  • Actions - Launch, Update, Remove buttons
  • Shield Icon - Sandbox status (top-right corner)

Sidebar Navigation

┌──────────────────┐
│  🐧 Linuxy       │
├──────────────────┤
│  📚 Library      │  ← Your apps
│  🏪 Discover     │  ← Find new apps
│  ⚙️  Settings     │  ← Configuration
├──────────────────┤
│  🔄 Refresh      │  ← Reload library
│  ❓ Help         │  ← Documentation
└──────────────────┘

Installing AppImages

Method 1: Drag and Drop

  1. Open Linuxy
  2. Drag an .AppImage file from your file manager
  3. Drop it onto the Linuxy window
  4. Installation begins automatically

Method 2: Browse Button

  1. Click the "Browse" or "+" button in the Library view
  2. Navigate to your .AppImage file
  3. Select and click "Open"
  4. Wait for installation to complete

Method 3: From Discover

  1. Navigate to the "Discover" tab
  2. Browse available AppImages
  3. Click "Install" on your chosen app
  4. Linuxy downloads and installs automatically

Installation Process

During installation, you'll see:

┌─────────────────────────────────┐
│  Installing Application...      │
│  ████████░░░░░░░░  65%          │
│  Extracting icon...             │
└─────────────────────────────────┘

Steps performed:

  1. Copy AppImage to ~/.local/appimages/
  2. Extract application icon
  3. Create desktop entry
  4. Update system menus

Post-Installation

After installation:

  • App appears in your Library
  • Desktop entry created in application menu
  • Icon available in system icon cache

Managing Apps

Launching Apps

From Linuxy:

  1. Find the app in your Library
  2. Click the ▶️ Launch button

From System Menu:

  1. Open your application menu
  2. Find the app (usually under the app's category)
  3. Click to launch

Removing Apps

  1. Click the 🗑️ Remove button on the app card
  2. Confirm the removal dialog
  3. AppImage, desktop entry, and icons are deleted

Note: This permanently deletes the AppImage file.

Viewing App Details

Hover over or click an app card to see:

  • File size
  • Installation date
  • Sandbox status
  • Version (if available)

Sandboxing with Firejail

What is Firejail?

Firejail is a Linux sandbox program that restricts the running environment of untrusted applications. When enabled for an AppImage, it limits access to:

  • Your home directory files
  • System configuration
  • Network (optional)
  • Other running processes

Checking Firejail Status

# Check if Firejail is installed
which firejail

# If not installed
sudo apt install firejail  # Debian/Ubuntu
sudo dnf install firejail  # Fedora
sudo pacman -S firejail    # Arch

Enabling Sandboxing

Per-App Basis:

  1. Find the app in your Library
  2. Click the 🛡️ Shield icon (top-right of app card)
  3. The shield turns green when sandboxing is enabled

Visual Indicators:

  • 🛡️ Gray = Not sandboxed
  • ✅ Green = Sandboxed

How Sandboxing Works

When you enable sandboxing for an app:

  1. Linuxy modifies the app's .desktop file
  2. Adds firejail --appimage to the Exec command
  3. Next launch runs the app in a sandbox

Example:

# Without sandboxing
Exec=/home/user/.local/appimages/Firefox.AppImage

# With sandboxing
Exec=firejail --appimage /home/user/.local/appimages/Firefox.AppImage

Disabling Sandboxing

  1. Click the shield icon again
  2. Confirm you want to disable
  3. App will run without restrictions next launch

Sandboxing Limitations

Some AppImages may not work correctly with Firejail due to:

  • Required system access
  • Hardware acceleration needs
  • Specific kernel features

If an app fails to launch with sandboxing, disable it and try again.

Updating Apps

Manual Update Check

  1. Click the 🔄 Update button on an app card
  2. Linuxy checks for newer versions when appimageupdatetool is installed
  3. If available, confirms download
  4. Downloads and replaces the AppImage

Update Indicators

  • Up to date: "Your AppImage is already up to date"
  • Update available: "An update is available! Download now?"
  • Check failed: Error message with details

Auto-Update Support

Not all AppImages support automatic updates. Support depends on:

  • AppImage having update metadata (zsync2)
  • Developer providing update information
  • Accessible update server
  • appimageupdatetool being installed on your system

Best Practices

  • Check for updates regularly
  • Review changelogs before updating
  • Keep backups of important AppImages

Settings & Configuration

Appearance

Theme Options:

  • 🌙 Dark - Default dark theme
  • ☀️ Light - Light theme for bright environments
  • 💻 System - Follows system preference

To change theme:

  1. Go to Settings
  2. Click your preferred theme
  3. Changes apply immediately

Storage

View Storage Usage:

  • Total disk space used by AppImages
  • Number of installed apps

Open AppImage Folder:

Settings → Library Storage → Open Folder

Opens ~/.local/appimages/ in your file manager

Security

Firejail Status:

  • Shows if Firejail is installed
  • Provides installation instructions
  • Explains sandboxing benefits

Keyboard Shortcuts

Shortcut Action
Ctrl + O Open/Browse for AppImage
Ctrl + R Refresh library
Ctrl + , Open settings
Ctrl + Q Quit application
Delete Remove selected app
F5 Refresh library
F1 Open help/documentation

Tips & Tricks

Organizing Your Library

While Linuxy doesn't support folders, you can:

  • Use descriptive app names
  • Keep related AppImages together
  • Remove unused apps regularly

Performance Tips

  1. Keep library small: Remove unused AppImages
  2. Use SSD: Faster app launches
  3. Limit sandboxing: Only sandbox untrusted apps

Backup Your Apps

# Backup all AppImages
tar -czf appimages-backup.tar.gz ~/.local/appimages/

# Restore
tar -xzf appimages-backup.tar.gz -C ~/

Custom Icons

If an app has a missing or wrong icon:

  1. Find or create a PNG/SVG icon
  2. Name it {app-name}_icon.png
  3. Place in ~/.local/share/icons/
  4. Refresh Linuxy

Command Line Usage

While Linuxy is GUI-focused, you can:

# Launch Linuxy
linuxy

# Check version
linuxy --version

# Show help
linuxy --help

Troubleshooting Common Issues

App won't launch:

# Make AppImage executable
chmod +x ~/.local/appimages/app-name.AppImage

# Try launching directly
~/.local/appimages/app-name.AppImage

Missing from system menu:

# Refresh desktop database
update-desktop-database ~/.local/share/applications/

Icon not showing:

# Refresh icon cache
gtk-update-icon-cache -f ~/.local/share/icons/

Advanced Usage

Manual Desktop File Editing

Location: ~/.local/share/applications/

Example .desktop file:

[Desktop Entry]
Type=Application
Name=My App
Exec=firejail --appimage /home/user/.local/appimages/myapp.AppImage
Icon=myapp_icon
Categories=Utility;

Custom Firejail Profiles

Create custom profiles in ~/.config/firejail/:

# Custom profile for specific app
mkdir -p ~/.config/firejail
nano ~/.config/firejail/myapp.profile

Environment Variables

# Enable debug logging
export RUST_LOG=debug
linuxy

# Custom config directory
export XDG_CONFIG_HOME=/custom/path

Getting Help

Enjoy managing your AppImages with Linuxy!

🐧 Built with love for the Linux community