https://github.com/kraftland/portable
Fast, private, efficient sandbox for Linux desktop.
https://github.com/kraftland/portable
accessibility dbus linux packaging privacy sandbox security systemd
Last synced: about 1 month ago
JSON representation
Fast, private, efficient sandbox for Linux desktop.
- Host: GitHub
- URL: https://github.com/kraftland/portable
- Owner: Kraftland
- License: gpl-3.0
- Created: 2024-11-11T03:36:51.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2026-01-27T15:43:55.000Z (5 months ago)
- Last Synced: 2026-01-27T21:07:16.922Z (5 months ago)
- Topics: accessibility, dbus, linux, packaging, privacy, sandbox, security, systemd
- Language: Shell
- Homepage:
- Size: 1.08 MB
- Stars: 70
- Watchers: 1
- Forks: 8
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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)
- Follows the [FHS (Filesystem Hierarchy Standard)](https://specifications.freedesktop.org/fhs/latest/)
- 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](https://github.com/Kimiblock/stashpak) | Build a Portable package for Arch Linux |
| [Packer](https://github.com/Kimiblock/portable-packer) | Packaging utility for Portable on Arch Linux |
| [Netsock](https://github.com/Kimiblock/netsock) | Network firewall |
# Why Portable?
See [Docs](https://github.com/Kraftland/portable/blob/master/doc/Why%20Portable.md)
## Available for
- [Minecraft](https://github.com/Kimiblock/moeOS.config/blob/master/usr/bin/mcLaunch)
- 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): 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](https://bugs.kde.org/show_bug.cgi?id=502309)
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](https://github.com/Kimiblock/xdg-desktop-portal/commit/199c0934035789986b98738b01b15edf0443d675)
- I barely understand C at all! Please help if you will.
- The other possibly "correct way" is to wait until [busd#34](https://github.com/dbus2/busd/issues/34), and XDP's implementation.
- Is it dead? idk.
Discuss Development at [#portable-dev:matrix.org](https://matrix.to/#/#portable-dev:matrix.org)
Demo
---
# Pools
Pools is a user friendly sandbox generator. To create and enter a user sandbox, simply execute portable-pools with your sandbox name.
Example: Create a test sandbox:
```bash
portable-pools test
╰─>Portable Sandbox·top.kimiblock.test·🧐⤔
```
Usage:
```
portable-pools [Options]
Options:
--quit: Terminates the sandbox
```
---
# How to package?
See [Docs](https://github.com/Kraftland/portable/tree/master/doc)
# 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](https://blog.kimiblock.top/notice/#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.