Distrobox desktop discovery and background-service integration

The command interfaces in this article were checked against the official Distrobox 1.8.2.5 scripts. Image tags and distribution package names are examples; before use, confirm that the image is still supported, its repositories are available, and the versions match your machine. The examples have not been tested by running them.

distrobox-export has only two export modes: app and bin. Applications still run in their source container; the host receives a launch entry point. For the full parameter list, Exec rewriting, icon copying, the wrapper’s cross-container branches, PATH conflicts, and removal procedures, see What Does Distrobox Actually Export?. This article covers desktop discovery, validation workflows, and separate background service management.

1. Verify the guest application before verifying the export#

# 在宿主进入 Arch 环境
distrobox enter arch-box
# 在 guest 中全量同步后安装应用；先测试程序能否显示
sudo pacman -Syu --needed firefox
firefox
# 在 guest 中生成宿主入口
distrobox-export --app firefox

Exporting requires an existing desktop entry. You can use an application name or the entry’s absolute path; the mere existence of a program is no substitute for a desktop file. Generated names are based on the source container and source desktop file, so do not guess <app>-<container>.desktop. Locate the actual file, then inspect Exec and Name.

# 在宿主检查已生成的入口（根据实际文件选择，不盲目覆盖）
find "${XDG_DATA_HOME:-$HOME/.local/share}/applications" -name '*firefox*.desktop' -print
# 在来源 guest 查看与撤销导出
distrobox-export --list-apps
distrobox-export --list-binaries --export-path "$HOME/.local/bin"

The value of --extra-flags should include all required arguments in one string. In 1.8.2.5, repeated occurrences overwrite the value rather than accumulate. Electron applications do not universally require --foreground; consult the specific program’s help. --sudo elevates privileges inside the guest; it does not create a root service on the host. For disk utilities in particular, confirm which devices are visible and what real data they contain first.

2. Desktop files, icons, and XDG discovery#

Launchers discover entries through the XDG data directories: the applications subdirectory under the user’s $XDG_DATA_HOME (defaulting to ~/.local/share when unset), and those under $XDG_DATA_DIRS (defaulting to /usr/local/share:/usr/share when unset). Desktops usually monitor directory changes or maintain their own caches; there is no guarantee that every launcher uses the same inotify or immediate-refresh strategy.

update-desktop-database updates the MIME type association cache; it is not a universal switch for rescanning launchers. gio info displays file information, but does not establish that a desktop entry has been parsed and launched correctly. Check each layer:

# 在宿主，用 find 找到的实际文件替换此路径
entry="$HOME/.local/share/applications/arch-box-firefox.desktop"
desktop-file-validate "$entry"
gio launch "$entry"
# 需要 MIME 缓存时才刷新相应目录
update-desktop-database "${XDG_DATA_HOME:-$HOME/.local/share}/applications"
printf '%s\n' "$XDG_DATA_HOME" "$XDG_DATA_DIRS"

If the entry is valid but does not appear in the launcher, check NoDisplay, Hidden, OnlyShowIn/NotShowIn, its directory location, and the desktop’s own cache. If launching produces an error, run the entry’s actual command directly in a terminal and check the guest program, graphics libraries, fonts, display sockets, application single-instance behavior, and logs. Do not use logging out or restarting the entire desktop to mask errors in earlier stages.

2.1 Lightweight graphical validation

# guest 内，二选一，包名以仓库为准
# Arch 的可执行名称不一定就是包名
sudo pacman -Syu --needed xorg-xeyes mesa-utils gedit
# Debian/Ubuntu
# sudo apt update && sudo apt install -y x11-apps mesa-utils gedit
xeyes
glxgears
gedit

First confirm that the program itself works, then check whether its package provides an exportable desktop entry. xeyes/glxgears can diagnose X11/XWayland and OpenGL, but some packages do not include desktop files, so do not assume --app xeyes will succeed. To test the native Wayland path, use a Wayland-capable application and check the backend it actually uses; a visible window does not establish that hardware acceleration is working.

2.2 Labels across containers and identically named CLI tools

# 在 Arch 来源容器中执行
distrobox-export --app firefox --export-label '(Arch)'
# 在 Ubuntu 来源容器中执行
distrobox-export --app firefox --export-label '(Ubuntu)'

Container names themselves must be unique; the usual problem is that several different containers have applications with the same name. GUI labels can distinguish their sources, but identically named CLI wrappers conflict in the same export-path. Choose a separate directory for each container, such as ~/bin/arch-tools and ~/bin/ubuntu-tools, then use full paths or explicit aliases on the host. Display labels cannot solve CLI overwrites.

3. How this differs from Flatpak and Snap desktop integration#

Distrobox generates desktop entries directly in the host user’s data directory, with Exec returning to the source environment through distrobox-enter. Flatpak’s system/user export directories are usually added to XDG_DATA_DIRS, and Exec launches applications through flatpak run; permissions are determined by the sandbox and application grants. Snap also has its own export and launch wrappers. Do not conflate these directory layouts or isolation models.

Distrobox shares HOME, networking, and session sockets by default, making it suitable for integrating trusted development tools; GUI export does not add a security sandbox. Flatpak’s actual isolation also depends on application permissions and portal use; a menu icon alone tells you nothing about it.

4. Background services: managing the container and guest units#

In 1.8.2.5, distrobox-export has no --service, and assemble has no exported_services. For long-running services, create an --init guest, then manage the guest system unit and host user unit separately. The two layers cannot substitute for each other.

4.1 Create, initialize, and test the service

# 宿主创建；镜像与包名需确认仍可用
distrobox create --name myserver --image ubuntu:24.04 --init \
  --additional-packages 'systemd nginx'
# 第一次 enter 完成用户/包初始化
distrobox enter myserver
# 以下在 guest 中：guest sudo 不等于宿主 rootful 后端
sudo systemctl enable --now nginx
sudo systemctl status nginx
sudo journalctl -u nginx

--init uses a separate process namespace so that the guest’s init becomes PID 1. Ordinary development containers do not need init. If an existing container needs different init/namespace settings, record its manifest and data, then recreate it; a nonexistent export flag cannot add them afterward.

Networking is shared with the host by default, so services such as nginx occupy host ports. Development services should use restricted listen addresses, with checks for port conflicts. Databases need authentication, persistent data directories, and consistent backups; placing one in a rootless guest does not establish that it is unexposed.

4.2 The host user unit only controls container startup and shutdown

Complete guest initialization and service validation before preparing the user unit. This example uses a conventional Podman path; on NixOS, replace it with the actual declaratively generated path, such as ${pkgs.podman}/bin/podman.

# ~/.config/systemd/user/distrobox-myserver.service
[Unit]
Description=Distrobox init container myserver
After=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/podman start myserver
ExecStop=/usr/bin/podman stop myserver

[Install]
WantedBy=default.target

# 在宿主操作宿主 user unit
systemctl --user daemon-reload
systemctl --user enable --now distrobox-myserver.service
systemctl --user status distrobox-myserver.service
journalctl --user -u distrobox-myserver.service
# guest nginx 的状态和日志仍在 guest 中查询
distrobox enter myserver -- sudo systemctl status nginx
distrobox enter myserver -- sudo journalctl -u nginx

oneshot + RemainAfterExit only records that the startup operation succeeded; it does not continuously monitor whether the container later crashes. For reliable service supervision, consider Podman Quadlet or a dedicated OCI service suited to the actual workload. systemctl --user enable primarily follows the user manager’s lifecycle; startup without anyone logging in requires explicitly evaluating linger and execution permissions.

4.3 Stopping, removing, and retaining data

# guest 中禁用某个应用服务
distrobox enter myserver -- sudo systemctl disable --now nginx
# 宿主停止并禁用容器启动 unit
systemctl --user disable --now distrobox-myserver.service
# 审核 unit 来源后移除你自己创建的 unit，再 reload
# rm "$HOME/.config/systemd/user/distrobox-myserver.service"
systemctl --user daemon-reload

Removing a unit, uninstalling an application, deleting a container, removing app/bin exports, and cleaning up data are separate operations. If Home Manager manages the unit, change the declaration rather than deleting generated files directly. Do not blindly delete all user services using filename globs.

4.4 Use cases

This layered approach can support nginx/apache/caddy development sites, PostgreSQL/MySQL/Redis, file synchronization, and CI runners. Whether a specific application suits Distrobox depends on its background lifecycle, ports, authentication, and data requirements; conventional OCI services are more straightforward when least privilege or reliable supervision is needed. Docker-in-Docker and libvirt involve additional permissions and host control, and should not be treated as one-click examples of ordinary service export.

5. Removing exports and checking for leftovers#

# 来源 guest 中分别列出并撤销已知 app/bin
distrobox-export --list-apps
distrobox-export --list-binaries --export-path "$HOME/.local/bin"
distrobox-export --app firefox --delete
distrobox-export --bin /usr/bin/vim --export-path "$HOME/.local/bin" --delete

Remove the entry points from the source guest first, then decide whether to uninstall the application or delete the container. Deleting the container makes the entry points unusable, but may not automatically remove host desktop files/wrappers. Check leftover items individually using their source markers and contents rather than bulk-deleting based on unverified filename conventions. Other entries may reuse the icons, so check references before removing them.