The sandbox wall
You install a Flatpak media player or a local document editor. You point it at your project directory or your music library. The app shows an empty folder or throws a generic "Unable to access path" dialog. You know the files are there. You know your user account has read permissions. The application simply refuses to look. This happens because Flatpak isolates every application from the rest of your system by default. The isolation is intentional. It prevents a compromised app from reading your SSH keys or modifying system binaries. It also means the app cannot see your home directory unless you explicitly grant it access.
How the sandbox actually works
Flatpak uses Linux namespaces, mount propagation, and seccomp filters to create a restricted environment for each application. Inside that environment, the filesystem is empty except for a few whitelisted directories. The app runs in a container that shares your kernel but gets its own view of the disk. When you install a Flatpak, the developer defines which paths the app needs. Most apps only request access to their own data directory and the standard XDG user directories through the Filechooser Portal.
The portal is a secure bridge. It lets the app ask the desktop environment to open a file picker, and the portal hands the app a temporary file descriptor. The app never gets direct path access. This keeps your home directory safe. It also breaks workflows where you want the app to scan a specific folder automatically, like a music library or a project directory. The portal works for one-off file operations. It does not work for background indexing or direct path resolution.
Flatpak stores override rules in plain text configuration files. User overrides live in ~/.local/share/flatpak/overrides/. System overrides live in /var/lib/flatpak/overrides/. The command-line tool writes to these files and updates the runtime mount namespace before the next launch. You do not need to edit the files manually. The CLI handles syntax validation and path resolution.
Restart the application after changing permissions. Flatpak does not inject new mount points into a running process.
Granting filesystem access
You bypass the portal by adding a filesystem override. The flatpak override command modifies the runtime configuration for a specific application ID. You run it once, and the change persists across reboots. The command targets either the current user or the entire system. Always prefer user overrides unless you are managing a shared workstation.
Here is how to grant access to your home directory for a specific app.
flatpak override --user --filesystem=xdg-home org.gnome.Lollypop
# --user scopes the change to your account only
# --filesystem=xdg-home maps the standard XDG home directory into the sandbox
# org.gnome.Lollypop is the application ID you are modifying
Replace the application ID with the one you are using. You can find the exact ID by running flatpak list or by checking the Flathub website. The xdg-home token expands to your actual home path. You can also target specific subdirectories.
flatpak override --user --filesystem=~/Music org.gnome.Lollypop
# ~/Music grants read-write access to that exact folder
# Flatpak resolves the tilde before applying the sandbox rules
# The app will see the folder at the same absolute path inside the container
If you need the app to see everything on your system, you can use the host token. This removes the filesystem restriction entirely for that application. Use it sparingly. It defeats the primary security benefit of Flatpak.
flatpak override --user --filesystem=host org.gnome.Lollypop
# host grants full read-write access to the entire host filesystem
# The app can now read /etc, /var, and every user home directory
# Only use this for trusted system utilities or local development tools
To remove an override, pass the same path with a minus sign prefix. The sandbox returns to its default state immediately.
flatpak override --user --filesystem=~/Music:ro org.gnome.Lollypop
# :ro appends read-only mode to the path
# The app can read files but cannot create or delete them
# Adding :ro is a safer default for media players and document viewers
Run the override command before launching the app. The mount namespace only updates at process start.
Verify the change
Check the active overrides before you start guessing. The --show flag prints the current configuration for an app.
flatpak override --user --show org.gnome.Lollypop
# Displays all active filesystem, device, and environment overrides
# Empty output means the app is running with default sandbox permissions
# Compare the output against your intended access rules
You can also inspect the runtime permissions directly from the app metadata. This shows what the developer requested at build time versus what you have overridden.
flatpak info --show-permissions org.gnome.Lollypop
# Lists the base permissions defined in the Flatpak manifest
# Look for the [Context] section to see default filesystem access
# Your override commands sit on top of these base rules
If the override appears correct but the app still cannot see the files, check the actual mount points inside the running container. Flatpak exposes a debug interface that shows the current namespace layout.
flatpak run --command=ls org.gnome.Lollypop /run/host/user-home
# --command=ls runs a shell command inside the sandbox instead of the app
# /run/host/user-home is the standard bind mount for the host home directory
# Verify that your target path actually appears in the output
Run flatpak override --show first. Read the actual configuration before adding more rules.
Common pitfalls and error patterns
The most frequent mistake is using relative paths or unexpanded variables. Flatpak expects absolute paths or recognized tokens like xdg-desktop or host. If you pass a path that does not exist on the host, the override silently fails or creates an empty mount point inside the sandbox. The app will report "No files found" instead of a permission error.
Another trap is mixing user and system overrides. If you run a command without --user, it writes to the system directory. Your user override might conflict with a system override, or vice versa. The last applied rule wins, but debugging the conflict requires checking both ~/.local/share/flatpak/overrides/ and /var/lib/flatpak/overrides/. Stick to --user for personal desktop apps.
You might also encounter portal conflicts. Some apps hardcode the file picker to use the portal even when direct access is available. The app will still show the desktop file chooser dialog instead of scanning the folder automatically. This is an application bug, not a Flatpak configuration issue. Check the app settings for a "Use native file picker" or "Disable portal" toggle.
If you see the following error, you are targeting the wrong ID or the app is not installed for your user.
FlatpakError: Cannot override permissions for a non-installed runtime
Run flatpak list --app to verify the exact string. Flatpak distinguishes between application IDs and runtime IDs. A typo in the ID creates a new empty override file that never applies to anything.
Check the application ID before overriding. A single missing character breaks the entire rule.
When to use overrides versus alternatives
Use flatpak override --filesystem when you need a specific app to scan or monitor a directory automatically. Use the built-in Filechooser Portal when you only need to open or save individual files on demand. Use --filesystem=host when you are running a local development environment or a system diagnostic tool that requires broad access. Stick to the default sandbox when you are installing media players, games, or productivity apps that do not need background file access. Trust the portal for one-off file operations. It keeps your home directory isolated without breaking functionality.