Hey party people, it’s 2026! Time for a new blog.

Last time, I talked about Experimenting with a mutable /usr within a Flatpak, and we’re going to continue the trend of doing cool things with Flatpak.

The reason I tried to make Flatpak have a mutable /usr was so I could experiment with adding things to the runtime that I could use during my development in VSCode, but what if I instead made the VSCode Flatpak escape the sandbox?

That was the question I set out to solve yesterday, and spoiler alert: I figured it out.

As always, I had to show off on Mastodon :)

How do we escape the sandbox and develop on the host? It actually ended up being pretty simple, so I won’t waste much of your time. (It did take me about 8 hours of fiddling though, so please love and appreciate me thx)

VSCode has the concept of “Remote Development”, where the VSCode GUI can communicate with a VSCode Server on a remote system. This works over SSH, WSL, and in Dev Containers by default. Because VSCode Server exists, I knew it should be possible to use that on the host system and have the flatpak connect to it.

The problem was that VSCode only supports those transports, and not something like TCP by default. Luckily, VSCode has a private API for something called Resolvers, which are responsible for marshalling a remote connection from the VSCode Server to the GUI. This is used internally for the Remote - SSH, WSL and Dev Containers extensions, but it has never been exposed for public extensions to use. See https://code.visualstudio.com/api/advanced-topics/using-proposed-api and a relevant issue from 2022! https://github.com/microsoft/vscode/issues/148316.

Just because the API is private doesn’t mean we can’t experiment with it. You can use proposed APIs in extensions, they just can’t be published to the extension marketplace as the API is not considered stable.

The VSCode repo actually has an amazing example for how to use the resolvers API. The example basically just runs a server on the base system and connects to itself. This is actually very close to what we need for the flatpak host escape. Because flatpak vscode shares the network with the host (via --share=network) and we have the proper sandbox escape mechanism to set up the server via flatpak spawn --host, all we need to do is rewire the example to spawn the downloaded vscode server on the host instead of within the sandbox.

From there, all it took was renaming a bunch of things, removing functionality from the example that doesn’t make sense to have in an actual extension, and write instructions on how to install it. Because we are using proposed APIs, VSCode requires you to explicitly enable the extensions by adding it to the VSCode command line arguments. You can set it automatically by editing the $HOME/.vscode/argv.json:

{
    // ...
    "enable-proposed-api": [
        "ryanabx.flatpak-host-remote"
    ]
}

It’s unfortunate that this API has been a proposed (read: private) API for years. This is something that a lot of people could make use of, AND it would allow for open source alternatives to the closed-source Remote Development extensions VSCode offers, but I digress.

Anyway, it all works! Go check it out at https://github.com/ryanabx/vscode-flatpak-host-remote if you use Flatpak vscode like me.

It seems like some folks on the vscode team are interested in making the Flatpak vscode official (or potentially homebrew). I was pointed to this post on the bluefin repository from a vscode team member expressing interest in working on that. I went ahead and posted my extension there, if it could be useful.

While it may not seem useful immediately to immutables, you can use Homebrew for dependencies on the host system, OR you can connect to containers by first connecting to the host system, and then to containers. This gets rid of the requirement to have the podman runtime extension installed in the VSCode flatpak.

Anyways, that’s all for now! I really enjoyed making this and I hope people find it useful.