Repository navigation
Flatpak and Permissions
Mimick is designed to work with selected-folder access rather than full home-directory access.
Flatpak builds do not need --filesystem=home.
Instead, folders are granted one at a time through the file chooser portal. Inside the sandbox those folders may appear as document-portal paths such as:
/run/user/1000/doc/...
The Mimick UI and logs convert those into friendlier folder names where possible.
Mimick uses the oo7 crate for secure API key storage. The backend is selected automatically:
-
Inside Flatpak: Credentials are stored in an encrypted file within the sandbox (
~/.var/app/dev.nicx.mimick/data/keyrings/). The encryption key is retrieved from theorg.freedesktop.portal.Secretportal. This avoids exposing secrets to other sandboxed applications. -
Outside Flatpak (native): Credentials are stored in the desktop's Secret Service (GNOME Keyring, KWallet) via the
org.freedesktop.secretsD-Bus interface.
Note: On desktops other than GNOME and KDE (Hyprland, Sway, XFCE, i3, etc.), the Secret portal may not be configured out of the box. If saving your API key fails, see the Keyring Setup guide.
Immich API Key Permissions vs Desktop Permissions: This page documents local Linux sandbox and D-Bus portal permissions. For Immich server API key permissions (scopes needed for syncing, albums, sharing, and library browsing), see API Key Security & Required Permissions.
The Flatpak manifest grants the following D-Bus talk permissions:
| Permission | Purpose |
|---|---|
org.kde.StatusNotifierWatcher |
System tray icon integration |
Mimick uses StatusNotifier support for its tray icon.
The Flatpak manifest keeps this narrowed to the minimum needed integration and no longer requests broad org.kde.* bus-name ownership.
The Run on Startup option uses:
- the desktop background portal in Flatpak
- a regular autostart desktop entry outside Flatpak
The local Flatpak manifest follows the same selected-folder model as the deployed build so behavior stays consistent during testing.
This is expected. The file chooser portal returns a document-portal path (/run/user/<uid>/doc/<id>/<folder-name>) instead of the real filesystem path. Mimick converts this to the folder name for display in the UI and logs.
The path stored in config.json may look like /run/user/1000/doc/abcd1234/Pictures. This is correct and survives reboots.
Portal grants are tied to the sandbox identity. Reinstalling or rebuilding the Flatpak can invalidate existing grants.
Fix: Remove the affected watch folders from Settings and re-add them through the folder picker. The picker re-grants portal access.
External drives and mounts are accessible as long as they appear in the file chooser portal's picker. If the drive does not appear, confirm it is mounted and visible to the desktop session before opening the Mimick folder picker.
Portal grants persist as long as the app ID (dev.nicx.mimick) stays the same and the grant has not been revoked via your desktop's permission settings. If a watch folder stops syncing with a permissions error after a desktop upgrade, remove and re-add the folder to renew the grant.