Story / scenario opener
You install a media player or a disk imaging tool via Flatpak. You point it at a folder on your external drive. The app freezes or throws a generic permission denied error. You check the terminal and see a sandbox violation. You know the app should work, but the container is locking it out.
What is actually happening
Flatpak ships applications in isolated containers. The default policy grants access to your home directory, the network, and basic display servers. Everything else requires explicit approval. This design prevents a compromised app from reading your SSH keys or writing to system partitions. The tradeoff is friction. When an app needs access to /run/media, a USB sound card, or a specific D-Bus service, the sandbox blocks it until you grant the right. Flatseal is a graphical frontend that reads and writes the underlying flatpak override configuration files. It translates the JSON permission matrix into checkboxes and dropdowns. The container boundary stays intact. You are just adjusting the gates.
Install and launch Flatseal
Here is how to pull Flatseal from Flathub and start it. Flatseal itself runs as a Flatpak, so it can safely modify the override files for other containers without needing root privileges.
flatpak install flathub com.github.tchx84.Flatseal # Pull the latest stable build from the official repository
flatpak run com.github.tchx84.Flatseal # Launch the GUI without adding it to your desktop menu permanently
The application opens with a list of installed Flatpak packages on the left. Select the app causing trouble. The right pane breaks permissions into categories. Filesystem access is the most common culprit. The default ~ checkbox grants read-write access to your home directory. If you need to reach an external drive, you must toggle Other files and select Ask or All. Ask prompts you through a portal dialog when the app tries to open a file outside its sandbox. All grants unrestricted read-write access to the entire host filesystem. Use Ask whenever possible. It preserves the sandbox boundary while still letting you browse.
Device permissions control hardware access. A virtual machine manager needs D-Bus and System Bus access to talk to libvirt. A recording app needs Audio and Video device access. Network is usually enabled by default. If you are running a local-only tool like a password manager, toggle Network off to reduce the attack surface. Environment variables let you pass host settings into the container. You rarely need to touch these unless you are debugging a graphics driver or forcing a specific locale. Apply the change and launch the app. The container reads the new policy on startup.
Adjust permissions from the terminal
Flatseal writes to JSON files in ~/.local/share/flatpak/overrides/. You can achieve the exact same result from the command line. Here is how to grant filesystem access to a specific application using the override command.
flatpak override --filesystem=host com.github.tchx84.Flatseal # Grant full host filesystem access to the target app
flatpak override --device=all com.github.tchx84.Flatseal # Allow access to all host devices including USB and serial ports
flatpak override --talk-name=org.freedesktop.secrets com.github.tchx84.Flatseal # Permit D-Bus communication with the system keyring
The --filesystem flag accepts paths, wildcards, and special keywords. host means everything. ~ means your home directory. /run/media targets mounted drives. You can combine multiple flags in a single command. The override command appends to the existing configuration. It never deletes unrelated settings. Run the override command before launching the app. The sandbox enforces the new rules immediately.
Verify the configuration
Run the application again and watch the terminal output. If you granted filesystem access, the app should now list the directories it previously skipped. You can also verify the override took effect by inspecting the generated configuration file.
cat ~/.local/share/flatpak/overrides/<app-id> # Replace <app-id> with the actual application identifier
The output will show the exact keys you modified. If the file is missing, the override was not applied or you are looking at the wrong user directory. Reboot before you debug. Half the time the symptom is gone after a session restart.
Common pitfalls and error patterns
The most frequent mistake is granting All filesystem access when Ask or a specific path would work. Wide-open permissions defeat the purpose of sandboxing. Another common trap is confusing user overrides with system-wide overrides. Commands run with sudo or targeting /var/lib/flatpak/overrides/ affect every user on the machine. Stick to user-level overrides unless you are managing a shared workstation. Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. The same principle applies to Flatpak overrides. Keep user changes in ~/.local/share/. Keep system policies in /var/lib/.
When the sandbox blocks an action, the terminal usually prints a clear denial message. You will see something like Error: Permission denied (os error 13) or a Flatpak-specific trace: flatpak-spawn: Failed to execvp: Permission denied. If you are using a graphical app, it might just fail silently or show a generic cannot open file dialog. Check journalctl -xe for the exact denial. The x flag adds explanatory context and the e flag jumps to the end. Most sysadmins type journalctl -xeu flatpak muscle-memory style. Read the actual error before guessing.
SELinux also plays a role here. Flatpak relies on SELinux policies to enforce the container boundary. If you see avc: denied messages in the audit log, do not disable SELinux. The denial usually means the app is trying to access a file type or mount point that lacks the correct label. Run restorecon -Rv /path/to/directory to fix label mismatches. Trust the package manager. Manual file edits drift, snapshots stay.
Reset and clean up
Overrides accumulate over time. You might grant temporary access to debug a crash and forget to remove it later. Here is how to inspect and clear permissions for a specific application.
flatpak info --show-permissions com.github.tchx84.Flatseal # Print the current permission matrix for the target app
flatpak override --reset com.github.tchx84.Flatseal # Remove all custom overrides and restore the developer defaults
The --reset flag deletes the override file for that application. The app falls back to the permissions defined in its manifest. This is safer than manually editing the JSON file. Manual edits introduce syntax errors that break the entire override chain. Run the reset command before reinstalling an app. Clean overrides prevent silent permission drift.
When to use this vs alternatives
Use Flatseal when you need a visual interface to toggle permissions for desktop applications without memorizing command flags. Use flatpak override when you are scripting deployments or managing permissions over SSH. Use native RPM packages when the application requires deep system integration and sandboxing causes more friction than it prevents. Use the Flatpak portal system when you only need occasional file access and want the system to prompt you each time. Stay on the default Flatpak permissions if the app works out of the box.