bubblejail.services(5)

📦 version 0.10.3, in alpine 3.24

💅 bubblejail.services — the manual page, bestie edition

okay so real quick: this is a File Formats Manual page, like, section 5 of the bubblejail.services docs. Sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

bubblejail.services — the service configuration for your bubblejail instance. that's it, that's the name, no cap 💅

🌸 SYNOPSIS 🌸

services.toml

🎀 DESCRIPTION 🎀

so like, a Bubblejail service's config lives in a file called services.toml, right? and that file hangs out at:

~/.local/share/bubblejail/instances/<instance_name>/services.toml

services.toml is a TOML-formatted file.¹ and the way it works is so cute: the moment you declare a table, that service is activated ✨ — and any key/values you put inside the table get passed straight through as settings for that service.

for example, bestie, look:

[home_share]
home_paths = ["Downloads"]

this activates the home_share service and shares the Downloads folder from your home directory with the sandbox. ate and left no crumbs 🫶

👑 AVAILABLE SERVICES 👑

🧚 common

Common Settings

settings that don't really fit in any particular category, y'know?

Options:

  • executable_name: str | list[str] — the default arguments to run when no arguments were provided.
  • share_local_time: bool = False — Deprecated. this option has, like, literally no effect since version 0.6.0 😭
  • filter_disk_sync: bool = False — do not allow flushing disk. highkey useful for the EA Origin client that tries to flush to disk way too often (it's giving main character energy but make it annoying 💀).
  • dbus_name: str — the D-Bus name that's allowed to acquire and own.

🦋 x11

X11 windowing system

gives access to the X11 socket. this is generally the default Linux windowing system, so like, if you're on it, you know 💅

🌈 wayland

Wayland windowing system

make sure you're running a Wayland session and that your application supports Wayland. both things, bestie, both 🌸

🌐 network

Network access

gives access to network. slay.

🎧 pulse_audio

Pulse Audio

the default audio system in most distros 🫶

🏠 home_share

Home Share

share directories or files relative to home.

Options:

  • home_paths: list[str] — path to share with the sandbox.

🖥️ direct_rendering

Direct Rendering

provides access to the GPU 🔥

Options:

  • enable_aco: bool = False — Deprecated. enables the high performance vulkan shader compiler for AMD GPUs. it's been enabled by default since mesa 20.02 anyway, so like… yeah 🙈

🎀 systray

System tray icons

provides access to the D-Bus API for creating tray icons. this is not the only way to create tray icons, but it's the most common one. iykyk ✨

🕹️ joystick

Joysticks and gamepads

windowing systems (x11 and wayland) do not support gamepads, which is honestly so rude. every game has to read from device files directly 😭 this service provides access to them.

📁 root_share

Root share

share directories or files relative to root /.

Options:

  • paths: list[str] — path to share with the sandbox.
  • read_only_paths: list[str] — path to share read-only with the sandbox.

☕ openjdk

Java

Deprecated: will be removed in the future 💀

enable for applications that require Java. example: Minecraft.

🔔 notify

Notifications

ability to send notifications to the desktop. cute 💖

🧚‍♀️ gnome_toolkit

GNOME toolkit

Experimental: maybe altered in the future.

access to GNOME APIs.

Options:

  • gnome_portal: bool = False — access to the GNOME Portal D-Bus API.
  • dconf_dbus: bool = False — access to the dconf D-Bus API.
  • gnome_vfs_dbus: bool = False — access to the GNOME Virtual File System D-Bus API.

🎵 pipewire

Pipewire

the Pipewire sound and screencapture system.

📹 v4l

Video4Linux

video capture (webcams and etc.) 🍓

⌨️ ibus

IBus input method

gives access to the IBus input method. this is generally the default input method for multilingual input.

⌨️ fcitx

Fcitx/Fcitx5 input method

gives access to the Fcitx/Fcitx5 input method. this is another popular input method framework. options, options 💅

🛰️ slirp4netns

Slirp4netns networking

an independent networking stack for the sandbox. requires the slirp4netns executable.

Options:

  • dns_servers: list[str] — DNS servers used. the internal DNS server is always used.
  • outbound_addr: str — address or device to bind to. if it's not set, the default address gets used.
  • disable_host_loopback: bool = True — prohibit connecting to the host's loopback interface.

🚧 namespaces_limits

Limit namespaces

limits the number of namespaces available inside the sandbox. and heads up: namespace limits are recursive — setting a limit to 0 blocks creating new namespaces, and setting -1 unlocks the limit. no cap 🫶

Options:

  • user: int = 0 — limiting user namespaces blocks acquiring new capabilities and privileges inside namespaces.
  • mount: int = 0 — limits the number of mount namespaces.
  • pid: int = 0 — limits the number of PID namespaces.
  • ipc: int = 0 — limits the number of IPC namespaces.
  • net: int = 0 — limits the number of net namespaces.
  • time: int = 0 — limits the number of time namespaces.
  • uts: int = 0 — limits the number of UTS namespaces.
  • cgroup: int = 0 — limits the number of cgroups namespaces.

🐛 debug

Debug options

various debug options, like adding arguments to bwrap or xdg-dbus-proxy.

Options:

  • raw_bwrap_args: list[str] — raw arguments to add to the bwrap invocation. see the bubblewrap documentation.
  • raw_dbus_session_args: list[str] — raw arguments to add to the xdg-dbus-proxy session invocation. see the xdg-dbus-proxy documentation.
  • raw_dbus_system_args: list[str] — raw arguments to add to the xdg-dbus-proxy system invocation. see the xdg-dbus-proxy documentation.

🎮 gamemode

GameMode

provides D-Bus access to Feral's GameMode daemon D-Bus API. use the gamemoderun command to run a specific game with optimizations 🔥 for example, add gamemoderun %command% to your Steam game launch options. iconic.

🍝 pasta_network

pasta networking

an independent networking stack for the sandbox. requires the pasta executable.

Options:

  • extra_args: list[str] — extra arguments to pass to pasta. for example, interface binding, port forwarding… see the passt man page.

🎶 mpris

MPRIS

Media Player Remote Interfacing Specification.

Options:

  • player_name: str — the D-Bus name suffix the player wants to acquire. accepts glob patterns (for example firefox.*).

🪟 xdg_desktop_portal

XDG Desktop Portal

Experimental: maybe altered in the future.

a D-Bus API that allows a sandboxed application access to resources outside of it.

Options:

  • add_flatpak_info: bool = False — adds the /.flatpak-info file to the sandbox, which some applications use as a trigger to use portals.
  • file_chooser: bool = False — enable the File Chooser portal, which allows spawning a file chooser outside the sandbox.
  • global_shortcuts: bool = False — enable the Global Shortcuts portal, which allows the application to create shortcuts that will work on Wayland.
  • inhibit: bool = False — enable the Inhibit portal, which allows the application to prevent the desktop from suspending or idling.
  • notification: bool = False — enable the Notification portal, which allows the application to send notifications.
  • open_uri: bool = False — enable the OpenUri portal, which allows opening files and links.
  • settings: bool = False — enable the Settings portal, which allows reading common GUI settings like dark mode 🌙
  • trash: bool = False — enable the Trash portal, which allows sending trashed files to a unified location outside the sandbox.
  • screen_cast: bool = False — enable the ScreenCast portal, which allows creating screen cast sessions.
  • override_xdg_open: bool = False — override xdg-open with a version that uses portals. currently depends on flatpak utils but will be replaced with a standalone version in the future.

🫶 SEE ALSO 🫶

📝 NOTES 📝

  1. TOML configuration file format. https://toml.io/

okay that's the whole thing bestie, you're officially a bubblejail services expert 👑✨ — this was bubblejail.services(5) from the File Formats Manual, dated 2026-06-07. go configure something iconic 💜

📦 where this page comes from