Portable is a desktop sandboxing framework that targets to be a) easy to use, b) efficient in disk space and other measurements, c) secure by default, convenient without compromise, d) automatically workaround issues.

This is a sandbox engine extracted from the original wechat-uos-qt, to lock up the proprietary WeChat in a cage. We started separating the internal sandbox to what would become portable in November 10, 2024. The very first commit containing LICENSE and README was pushed to the repository in Initial Commit, the core function was added in the following commit. And now, more than 240 days have been passed. Let’s take a peek in to what has changed and improved in portable.

The early days

I continued to separate WeChat specific code in portable. From Initial Commit to Merge pull request #3 from Kraftland/Kimiblock-patch-1. The very first release of portable was available. We also made the decision to use pull requests in order to draw a line between each addition or modification, that makes changes easier to follow. Portable 1 was released in November 21, 2024 with a usable core logic.

In the following time, more work is put in to fix our shitty X code, that allows only sharing the active X session authority to the sandbox. All of the fixes landed in version 1.1.3.

The unsafe mode, aka sandbox disabled mode also got improvements in version 1.1.4, that consists of Input Method fixes. Along with Wayland display binding and improved logging. Later in #19 comes the Input Method fixes for Wayland, marking the availability of portable for Wayland applications.

To allow more apps be sandboxed by portable, we added the documents portal in version 1.2.0. Which allows the XDG Desktop Portal FileChooser to pop up on request, and is the foundation of functions like secure DnD. That of the portal enhancements came with ability to retrieve a master secret via portals, and removal of org.freedesktop.portal.Flatpak.*=* calling rule, making way for a secure and fail-safe portal filtering, combined with #16 which switches to the whitelisting filter. Marking the deactivation of ScreenShots portal for the unsafe implementations.

Aiming to address the situation about hybrid GPUs, we introduced the nvidiaSwitchableGraphics() function in #18, that of the detection unbinds NVIDIA devices from the sandbox, allowing more efficient operation on laptops with more than one graphics card, which was refined in #100. systemd hardening was also added to install a syscall filter and restricts listening exotic sockets, as well as system level protection, capability dropping, private mounts & kernel keyring and more. Of which 5 commits containing 34 additions to the internal systemd-run call.

Our first outside contribution was received on Dec 4, 2024 by @guozesheng, improving HiDPI workarounds in unsafe mode. Input device binding was also added as an option in #22. Later comes with #25 for support of opening files through the /proc interface. GTK theming support was also added in #28.

A range of bug fixes landed in 1.3.5 and 1.3.6, paving way for the --inspect command landed in 2.1.0.

Another contributor came in version 2.2.0, who co-authored a fix for X11 & XIM socket passthrough with me. In response to the need of sharing files to applications that doesn’t use Portals (yuck, they sucks), portable gained the --actions share-files command switch, whose job is to copy files shared into sandbox home, under Shared.

Game mode was added to portable in #46 with environment variable settings added in #84, and yes, we use Portable for gaming. With more plumbing under the way, the Camera, ScreenCast and Account Information Portal was also added in version 2.7.0.

Opening files from the sandbox was refined in #65 too, using the same Shared directory as a bridge between sandbox world and host. There’s also initial work of automatic clean up of various directories in #66. Refactoring and bug fixes continued, Background Portals support was added #79, refined in #89.

Rising box

Portable is considered stable at version 2.18, of which added support for adaptive Wayland only mode, faster startup and an internal helper to manage sandbox processes. We continued the journey with hybrid GPU optimisation, multi-instances support and introduced a brand new tool: Pools. Of which is used to create transient sandboxed for trying out things and debugging, with simply one command to create a sandbox and enter:

1
portable-pools <sandbox name>

@someoneinjd also made their first contribution in #108, ensuring addEnv() works more consistently. And Network Monitor Portal was added in #116. Another fix for zink was added in version 2.25, which later proves important for WeMeet users on NVIDIA GPU. Global Shortcuts & USB portal was added to portable in version 3.1. The rest of version 3 includes general speedups, and the ability to directly start applications inside the sandbox using a startSignal file in #154.

Our new contributor @NKPmedia made their first contribution in #157 for an option to disable network access for a sandbox.

Things changed a bit in version 4.x. We changed the sandbox HOME directory to $XDG_DATA_HOME/$stateDirectory, which allows application themselves to call FileManager1, fixes issues with Obsidian, etc.

Leap

Portable released version 5.0, codename Leap on May 24, 2025, my birthday. Of which consists an exploding set of features, quoting the release page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
* Hardcode various XDG base directory to prevent user overriding
* BREAKING CHANGE: user-dirs is now in C locale!
* feat: Request user to terminate remaining processes
* Refactor bwBindPar & use tmpfs overlay
* Move startSignal to /run, avoid slow disks
* Fix: direct invocation should pass cmdline arg
* Drop support for bwBindPar open
* chore: set working directory and fix a bunch of issues #172
* Add support for pw-v4l2 #173
* feat: use zink #174
* feat: Stop application when portable is terminated #176
* Specify portal dependencies #177
* feat: stop relying on systemd to clean directories #178
* Implement Wayland Security Context V1 #179
* feat: make Qt5 compat optional #181
* Generate a .desktop file if not exists #184
* Fix opening files with file:// link #185
* Improve upon the Wayland security context #186
* fix: Reset should happen before cleaning #187
* Allow passing WAYLAND_DISPLAY to way-secure #188
* dbus: own appID.* #189

We spent the rest of the 5.0 series with bug fixes, quality of life improvements and more refinement. Paving way for the version 6.0 big release, co-authored by me and haakuya, bringing the most stable, clean and powerful version of portable ever…

What now?

I wrote this article to reflect what we have achieved in the past 98 releases. Moving closer to the one year anniversary of this project, I want to have a general idea of what it should be in the next year. Currently I don’t have plans for it to slow down, but a governance is preferred. Having stable support for more and more applications is always appreciated, though.

Portable for now has a reliable and performant enough nature. Our next step for it is currently unknown, but some ideas have sparked, like user overriding permissions, native flatpak-spawn support and more, a configuration generator and more. Stay tuned for future releases! Thanks to everyone who contributed to the Portable Project!