| Name | luks-tray JSON |
| Version |
1.5
JSON |
| download |
| home_page | None |
| Summary | A Qt-based tray app for managing LUKS encrypted volumes |
| upload_time | 2025-07-10 14:45:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
luks
qt6
applet
tray
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# LUKS Tray
**luks-tray** is a GTK-based tray utility for managing ad hoc LUKS-encrypted files: mount and unmount with ease from your Linux desktop environment.
## Features
- **System tray integration** - Simple click-to-mount/unmount interface for LUKS devices and files
- **Visual status indicators** - Clear icons showing mounted (✅), unmounted (🔳), and open-but-unmounted (‼️) states
- **File container support** - Add, create, and manage LUKS file containers from the tray.
- **Mount point history** - Remembers previous mount locations for convenience and clarity
- **Background monitoring** - Automatically detects newly inserted devices with LUKS containers
- **Password management** - Optional master password to encrypt stored credentials
## Quick Start
1. Install and run `luks-tray`. Use `pipx` to install, update and remove; e.g. `pipx install luks-tray`. See [pipx docs](https://pypa.github.io/pipx/) for more details.
2. Click the tray icon to see available containers. You may:
- Insert a disk with LUKS devices to detect them automatically.
- Add an existing or create a new encrypted file to manage it.
4. Click a container to mount (🔳) or unmount (✅ or ‼️)
5. When mounting a container, enter its password and choose mount point in the dialog
- if the app has a mount point in its history, it will fill in that mount point
- otherwise, the app will generate a mount point in `~/Vaults`
For best results, the Noto Color Emoji fonts should be installed if not already:
sudo pacman -S noto-fonts-emoji # EndeavourOS/Arch
sudo dnf install google-noto-emoji-fonts # Fedora
sudo zypper install noto-emoji-fonts # openSUSE Tumbleweed
sudo apt install fonts-noto-color-emoji # Ubuntu
## Visual Interface
The tray icon is shaped like a shield changes based on container states:
- <img src="https://github.com/joedefen/luks-tray/raw/main/luks_tray/resources/white-shield-v04.svg" alt="White Shield Icon" width="24" height="24"> - All containers are locked and unmounted (i.e., all data is secure).
- <img src="https://github.com/joedefen/luks-tray/raw/main/luks_tray/resources/alert-shield-v04.svg" alt="Alert Shield Icon" width="24" height="24"> - Some containers are unlocked but unmounted (i.e., one or more anomalies).
- <img src="https://github.com/joedefen/luks-tray/raw/main/luks_tray/resources/green-shield-v04.svg" alt="Green Shield Icon" width="24" height="24"> - Some containers are mounted w/o any anomalies (i.e., some of the encrypted data is available)
Here is an sample menu as seen when you right-click the tray shield icon:
<img src="https://github.com/joedefen/luks-tray/raw/main/images/sample-menu.png" alt="Sample Menu"></center>
Notes:
- the first section shows LUKS devices, and the second shows LUKS files.
- click a ✅ entry to dismount and lock a mounted, unlocked LUKS container
- if busy, you are shown the PIDs and names of processes preventing dismount
- click a 🔳 entry to unlock and mount a locked LUKS container
- click a ‼️ entry to lock an unmounted, unlocked container (considered an anomaly)
- or click of the action lines to perform the described action
- LUKS files are only automatically detected in its history; when you add or create new LUKS files, they are added to the history.
- LUKS devices must be created with other tools such as Gnome Disks.
## Configuration
Settings and data files are stored in `~/.config/luks-tray/`:
- **History file** - Stored of passwords and mount preferences; it is encrypted when the master password enabled.
- **INI file** - the default .ini file looks like:
[ui]
show_passwords_by_default = True
show_anomaly_alerts = True
auto_mount_folder = ~/Vaults
You can thus change
- whether passwords are shown by default when being first entered.
- whether ‼️ entries (i.e., anomalies) cause the tray icon to change to the alert shield.
- where the automatically generated mount points live
## Security Notes
- Passwords are only stored when master password feature is enabled
- History file is encrypted using the master password
- System mount points are excluded by default to prevent interference with disk encryption
- When creating LUKS file containers, password strength is not enforced; use due care.
---
## Limitations
- **Not for whole disk encryption** - Excludes system mount points like `/`, `/home`, `/var` to avoid interfering with boot-time encrypted volumes
- **No udisks2 integration** - May not always play nicely with desktop auto-mounting tools; so mount and unmount containers with the same tool for the best results.
- **Loop device requirement** - File containers require `lsblk` to show them as loop devices (standard on most distros)
- **Single filesystem focus** - Containers with multiple filesystems are out of scope of this tool and get very limited support (i.e., mostly handling only the first filesystem).
---
## Requirements
#### Additional System Utilities may be Needed
This program requires `cryptsetup`, `fuser`, and other system utilities. After install, run `luks-tray --check-deps` to get a report on what dependencies are found and missing. If any are missing, install those using your distro package manager.
#### Passwordless `sudo` Setup (Required)
To allow the tray app to manage LUKS containers without prompting for your password each time, configure passwordless `sudo` for specific commands. For example, in a terminal, run `sudo visudo`, and then add this line at the end of the file (replacing {yourusername} with your actual username):
{yourusername} ALL=(ALL) NOPASSWD: ALL
💡 This grants your user passwordless access to all commands. You may be able to limit it to just the `luks-tray` app or subset of commands. See `man sudoers` for details.
#### A Working System Tray
It works best with DEs/WMs that offer **first-class tray support**, such as:
- **KDE Plasma**
- **Sway** with **waybar**
- **i3wm** with **polybar**
> ⚠️ **GNOME**: Requires a third-party extension (such as AppIndicator support) to show tray icons. Results may vary across GNOME versions.
> ⚠️ **Xfce** and similar lightweight DEs: Tray menus may open off-screen or be partially cut off, depending on panel layout and screen resolution.
---
Test Notes:
- for no filesystems:
- sudo dd if=/dev/zero of=/tmp/test_luks_container bs=1M count=100
- sudo cryptsetup luksFormat /tmp/test_luks_container
- sudo cryptsetup open /tmp/test_luks_container test_luks
- for two file systems:
- sudo pvcreate /dev/mapper/test_luks
- sudo vgcreate test_vg /dev/mapper/test_luks
- sudo lvcreate -L 20M -n lv1 test_vg
- sudo lvcreate -L 20M -n lv2 test_vg
- sudo mkfs.ext4 /dev/test_vg/lv1
- sudo mkfs.ext4 /dev/test_vg/lv2
Raw data
{
"_id": null,
"home_page": null,
"name": "luks-tray",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "LUKS, Qt6, applet, tray",
"author": null,
"author_email": "Joe Defen <joedef@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c9/6e/8603c4ea1ff9db647e443fa2dfc4b3ba7de8845da3cc0a6603b2d6638bb6/luks_tray-1.5.tar.gz",
"platform": null,
"description": "# LUKS Tray\n\n**luks-tray** is a GTK-based tray utility for managing ad hoc LUKS-encrypted files: mount and unmount with ease from your Linux desktop environment.\n\n\n## Features\n\n- **System tray integration** - Simple click-to-mount/unmount interface for LUKS devices and files\n- **Visual status indicators** - Clear icons showing mounted (\u2705), unmounted (\ud83d\udd33), and open-but-unmounted (\u203c\ufe0f) states\n- **File container support** - Add, create, and manage LUKS file containers from the tray.\n- **Mount point history** - Remembers previous mount locations for convenience and clarity\n- **Background monitoring** - Automatically detects newly inserted devices with LUKS containers\n- **Password management** - Optional master password to encrypt stored credentials\n\n## Quick Start\n\n1. Install and run `luks-tray`. Use `pipx` to install, update and remove; e.g. `pipx install luks-tray`. See [pipx docs](https://pypa.github.io/pipx/) for more details.\n2. Click the tray icon to see available containers. You may:\n - Insert a disk with LUKS devices to detect them automatically.\n - Add an existing or create a new encrypted file to manage it.\n4. Click a container to mount (\ud83d\udd33) or unmount (\u2705 or \u203c\ufe0f)\n5. When mounting a container, enter its password and choose mount point in the dialog\n - if the app has a mount point in its history, it will fill in that mount point\n - otherwise, the app will generate a mount point in `~/Vaults`\n\nFor best results, the Noto Color Emoji fonts should be installed if not already:\n\n sudo pacman -S noto-fonts-emoji # EndeavourOS/Arch\n sudo dnf install google-noto-emoji-fonts # Fedora\n sudo zypper install noto-emoji-fonts # openSUSE Tumbleweed\n sudo apt install fonts-noto-color-emoji # Ubuntu\n\n\n## Visual Interface\n\nThe tray icon is shaped like a shield changes based on container states:\n- <img src=\"https://github.com/joedefen/luks-tray/raw/main/luks_tray/resources/white-shield-v04.svg\" alt=\"White Shield Icon\" width=\"24\" height=\"24\"> - All containers are locked and unmounted (i.e., all data is secure).\n- <img src=\"https://github.com/joedefen/luks-tray/raw/main/luks_tray/resources/alert-shield-v04.svg\" alt=\"Alert Shield Icon\" width=\"24\" height=\"24\"> - Some containers are unlocked but unmounted (i.e., one or more anomalies).\n- <img src=\"https://github.com/joedefen/luks-tray/raw/main/luks_tray/resources/green-shield-v04.svg\" alt=\"Green Shield Icon\" width=\"24\" height=\"24\"> - Some containers are mounted w/o any anomalies (i.e., some of the encrypted data is available)\n\nHere is an sample menu as seen when you right-click the tray shield icon:\n\n<img src=\"https://github.com/joedefen/luks-tray/raw/main/images/sample-menu.png\" alt=\"Sample Menu\"></center>\n\nNotes:\n\n- the first section shows LUKS devices, and the second shows LUKS files.\n- click a \u2705 entry to dismount and lock a mounted, unlocked LUKS container\n\n - if busy, you are shown the PIDs and names of processes preventing dismount\n\n- click a \ud83d\udd33 entry to unlock and mount a locked LUKS container\n- click a \u203c\ufe0f entry to lock an unmounted, unlocked container (considered an anomaly)\n- or click of the action lines to perform the described action\n- LUKS files are only automatically detected in its history; when you add or create new LUKS files, they are added to the history.\n- LUKS devices must be created with other tools such as Gnome Disks.\n\n\n\n## Configuration\n\nSettings and data files are stored in `~/.config/luks-tray/`:\n- **History file** - Stored of passwords and mount preferences; it is encrypted when the master password enabled.\n- **INI file** - the default .ini file looks like:\n\n [ui]\n show_passwords_by_default = True\n show_anomaly_alerts = True\n auto_mount_folder = ~/Vaults\n\n You can thus change\n - whether passwords are shown by default when being first entered.\n - whether \u203c\ufe0f entries (i.e., anomalies) cause the tray icon to change to the alert shield.\n - where the automatically generated mount points live\n\n## Security Notes\n\n- Passwords are only stored when master password feature is enabled\n- History file is encrypted using the master password\n- System mount points are excluded by default to prevent interference with disk encryption\n- When creating LUKS file containers, password strength is not enforced; use due care.\n\n---\n## Limitations\n\n- **Not for whole disk encryption** - Excludes system mount points like `/`, `/home`, `/var` to avoid interfering with boot-time encrypted volumes\n- **No udisks2 integration** - May not always play nicely with desktop auto-mounting tools; so mount and unmount containers with the same tool for the best results.\n- **Loop device requirement** - File containers require `lsblk` to show them as loop devices (standard on most distros)\n- **Single filesystem focus** - Containers with multiple filesystems are out of scope of this tool and get very limited support (i.e., mostly handling only the first filesystem).\n---\n## Requirements\n#### Additional System Utilities may be Needed\nThis program requires `cryptsetup`, `fuser`, and other system utilities. After install, run `luks-tray --check-deps` to get a report on what dependencies are found and missing. If any are missing, install those using your distro package manager.\n\n \n#### Passwordless `sudo` Setup (Required)\n\nTo allow the tray app to manage LUKS containers without prompting for your password each time, configure passwordless `sudo` for specific commands. For example, in a terminal, run `sudo visudo`, and then add this line at the end of the file (replacing {yourusername} with your actual username):\n\n {yourusername} ALL=(ALL) NOPASSWD: ALL\n\n\ud83d\udca1 This grants your user passwordless access to all commands. You may be able to limit it to just the `luks-tray` app or subset of commands. See `man sudoers` for details.\n\n#### A Working System Tray\nIt works best with DEs/WMs that offer **first-class tray support**, such as:\n\n - **KDE Plasma**\n - **Sway** with **waybar**\n - **i3wm** with **polybar**\n\n> \u26a0\ufe0f **GNOME**: Requires a third-party extension (such as AppIndicator support) to show tray icons. Results may vary across GNOME versions.\n> \u26a0\ufe0f **Xfce** and similar lightweight DEs: Tray menus may open off-screen or be partially cut off, depending on panel layout and screen resolution.\n\n\n---\n\nTest Notes:\n - for no filesystems:\n - sudo dd if=/dev/zero of=/tmp/test_luks_container bs=1M count=100\n - sudo cryptsetup luksFormat /tmp/test_luks_container\n - sudo cryptsetup open /tmp/test_luks_container test_luks\n - for two file systems:\n - sudo pvcreate /dev/mapper/test_luks\n - sudo vgcreate test_vg /dev/mapper/test_luks\n - sudo lvcreate -L 20M -n lv1 test_vg\n - sudo lvcreate -L 20M -n lv2 test_vg\n - sudo mkfs.ext4 /dev/test_vg/lv1\n - sudo mkfs.ext4 /dev/test_vg/lv2",
"bugtrack_url": null,
"license": null,
"summary": "A Qt-based tray app for managing LUKS encrypted volumes",
"version": "1.5",
"project_urls": {
"Bug Tracker": "https://github.com/joedefen/luks-tray/issues",
"Homepage": "https://github.com/joedefen/luks-tray"
},
"split_keywords": [
"luks",
" qt6",
" applet",
" tray"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "54904d96695e5981d246bd0b8bb673536e61d38f51a600af17a662c766486275",
"md5": "dcf6a2a22f58e477f1e61e8edc6f0777",
"sha256": "f67832269656f61f13da34b5f4db009b1ee29866b5b9394072cc5881aa7a9f88"
},
"downloads": -1,
"filename": "luks_tray-1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dcf6a2a22f58e477f1e61e8edc6f0777",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 79980,
"upload_time": "2025-07-10T14:45:08",
"upload_time_iso_8601": "2025-07-10T14:45:08.124153Z",
"url": "https://files.pythonhosted.org/packages/54/90/4d96695e5981d246bd0b8bb673536e61d38f51a600af17a662c766486275/luks_tray-1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c96e8603c4ea1ff9db647e443fa2dfc4b3ba7de8845da3cc0a6603b2d6638bb6",
"md5": "887218fbd57b293b9d39e50142387e8a",
"sha256": "0ac402134bed5788441e3be0785b7f64b04b9135fa54eed2be10a25791cc5f12"
},
"downloads": -1,
"filename": "luks_tray-1.5.tar.gz",
"has_sig": false,
"md5_digest": "887218fbd57b293b9d39e50142387e8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 80867,
"upload_time": "2025-07-10T14:45:10",
"upload_time_iso_8601": "2025-07-10T14:45:10.325852Z",
"url": "https://files.pythonhosted.org/packages/c9/6e/8603c4ea1ff9db647e443fa2dfc4b3ba7de8845da3cc0a6603b2d6638bb6/luks_tray-1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 14:45:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "joedefen",
"github_project": "luks-tray",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "luks-tray"
}
