Abstract

Portable is a sandbox framework targeted for Desktop usage and offers ease of use for distro packagers, which should work on most recent systems:

• enables unprivileged user namespaces
• uses systemd >=258
• has landlock version 6 and above (optional)
• has kernel.yama.ptrace_scope <= 1

• Follows the FHS (Filesystem Hierarchy Standard)

  • Note that /lib /lib64 /bin /sbin should be symlinks to their respective locations under /usr

• Does not have mount points under /usr/bin, and use a supported fs of OverlayFS (NOT BcacheFS)

This is the rewrite of the original Portable. For the legacy version, see legacy branch.

Portable has companion projects for packaging and sandboxing: | Project | Descripton | | ------------- | ------------- | | StashPak | Build a Portable package for Arch Linux | | Packer | Packaging utility for Portable on Arch Linux | | Netsock | Network firewall | | bawn | CLI for transient sandbox |

Why Portable?

See Docs

Available for

• Minecraft
• Arch Linux
  • Arch Linux CN Repository
    • Only selected free/OSS apps
    • Updates faster
  • Portable for Arch
    • Configure paru to use portable-arch: https://github.com/Kraftland/portable-arch
    • Current support status (as of 30 Nov 2025): 29 packages in repo.

Limitations:

1. Running untrusted code is never safe, sandboxing does not change this.
2. On KDE Plasma window grouping may not work properly unless your desktop file name exactly matches certain arguments.
   • This is an KWin issue
3. Due to some desktop portal implementations being insecure (without requiring user consent), feature(s) may only be available on GNOME:
   • Location Portal
4. Portable acts like Flatpak, to trick XDG Desktop Portal.
   • The correct way for this situation is to specify another sandboxing engine in XDP, which I have a PoC here
     • I barely understand C at all! Please help if you will.
   • The other possibly "correct way" is to wait until busd#34, and XDP's implementation.
     • Is it dead? idk.

Discuss Development at #portable-dev:matrix.org

Demo

---

Transient sandbox

See bawn for the successor of Portable Pools.

---

How to package?

See Docs

FAQ / Troubleshooting

1. Portable fails with something like invalid argument
   • BcacheFS is not supported, or you have mountpoints under /usr/bin and /usr/lib

Starting portable

Start portable with environment variable PORTABLE_CONF, which can be 1) the appID of the sandbox, 2) an absolute path (if exists), 3) a file name interpreted as $(pwd)/${PORTABLE_CONF}. It searches for each of them respectively.

• Debugging output can be enabled using a environment variable PORTABLE_LOGGING=debug

Debugging

Entering sandbox

To manually execute programs instead of following the launchTarget config, start portable with argument --actions debug-shell. This will open a bash prompt and gives you full control of the sandbox environment.

Code of Conduct

Portable and any of its social environment follows the Kraftland Code of Conduct. Please be sure not to violate such rule set.

Version Scheme

Portable follows a major.minor.patch version scheme. We thrives to provide a stable experiences with no breaking changes, however, if said change is necessary, will land in a major release.

The patch release is exclusive for bug fixes. Whereas minor releases contain new features. If a feature or a set of features needs time to test or is important enough, we conduct a major release.

Portable has and always will be only supporting the latest release. Generally users can upgrade without manual intervention, but between major releases it's advised to run systemctl --user stop portable.slice to stop the portable framework.