x11docker

Launch VLC in a container

$ x11docker [[-p|--pulseaudio]] --share [$HOME/Videos] [jess/vlc]

$ x11docker [[-d|--desktop]] [x11docker/xfce]

$ x11docker [[-d|--desktop]] [[-g|--gpu]] --init=[systemd] [x11docker/gnome]

$ x11docker [[-d|--desktop]] [[-g|--gpu]] --init=[systemd] [x11docker/kde-plasma]

$ x11docker --help

x11docker [OPTIONS] IMAGE [COMMAND] [ARG...]

--help
    Displays the help message and exits.

--clone
    Creates a non-root user in the container that matches the host user's UID/GID, improving file permissions and security.

--hostuser
    Runs the container as the host user, directly sharing the UID/GID. Less secure than --clone.

--gpu
    Enables GPU hardware acceleration within the container for improved graphics performance.

--sound
    Enables sound support, typically via PulseAudio or ALSA, for the containerized application.

--clipboard
    Allows bidirectional clipboard synchronization between the host and container.

--webcam
    Enables access to webcam devices inside the container.

--cap-drop=CAP
    Drops specified Linux capabilities from the container for enhanced security.

--cap-add=CAP
    Adds specified Linux capabilities to the container.

--desktop
    Runs a full desktop environment (e.g., XFCE, LXDE) inside the container.

--interactive or -i
    Keeps STDIN open even if not attached, useful for interactive shell sessions within the container.

--rm
    Automatically removes the container when it exits.

--docker-options "OPTIONS"
    Passes additional, raw options directly to the underlying docker or podman command.

--wayland
    Uses Wayland for the display server (requires a Wayland composite manager in the container).

--xorg
    Uses a nested Xorg server, providing strong isolation from the host X server. Often the recommended secure mode.

x11docker is a powerful wrapper script that simplifies running graphical user interface (GUI) applications in isolated Docker or Podman containers. It addresses the challenges of X11 forwarding and sound system integration, allowing users to run GUI apps securely without them directly accessing the host's display or system resources. x11docker automates the complex setup of X11 authorization, PulseAudio or ALSA sound, GPU acceleration, and webcam access, making it straightforward to sandbox untrusted applications or create portable development environments.

It supports various display backends like Xorg, Weston, or nested X servers, enhancing security by providing a separate X server for the container. It's an essential tool for privacy-conscious users and developers needing isolated graphical environments.

Running GUI applications in containers, even with x11docker, involves inherent security considerations. While x11docker significantly improves isolation compared to direct X11 forwarding, certain modes (e.g., --hostuser, --allow-host-xaccess, or not using a nested X server) can reduce the isolation level. Users should always be aware of the implications of the options they choose, especially when running untrusted applications. Network access and file system mounts (--share, --mount) can also bypass isolation if not carefully managed.

x11docker offers various display backends and user management options that directly impact security. Using --xorg or --weston provides a separate, nested X server, offering strong isolation from the host's X server, preventing the containerized application from snooping on host keyboard inputs or manipulating host windows. Options like --hostdisplay directly expose the host's X server, which is less secure but can be useful in trusted environments or for debugging. Choosing the appropriate mode based on trust in the application is crucial.

By default, x11docker often cleans up containers upon exit (via --rm). For development or persistent environments, options like --permanent or --container-name combined with omitting --rm allow containers to persist between sessions, enabling data and configuration to be saved.

x11docker was developed to provide a simpler and more secure way to run GUI applications in Docker containers. Traditional methods of X11 forwarding (e.g., `-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY`) expose the entire host X server to the container, posing a significant security risk. x11docker emerged as a solution to mitigate these risks by offering safer X server configurations (like nested X servers), managing user IDs, and integrating various host resources securely. It has evolved to support different container runtimes (like Podman) and advanced features such as GPU, sound, and webcam access, becoming a popular tool for sandboxing graphical applications.

docker(1), podman(1), X(7), xhost(1)