X11DOCKER(1)

📦 version 7.6.0, in fedora 43, fedora 44

💖 X11DOCKER(1) 💖

okay so bestie, this is the General Commands Manual page for x11docker, and honestly? it ate. grab a snack, we're going through every single line together. 🍓✨

🌸 NAME 🌸

x11docker — run GUI applications and desktop environments in containers 🦋

✨ SYNOPSIS ✨

so, if you wanna run a container on a fresh new X server, you do this:

x11docker [OPTIONS] IMAGE [COMMAND]

x11docker [OPTIONS] -- IMAGE [COMMAND [ARGS ...]]

x11docker [OPTIONS] -- [CUSTOM_RUN_OPTIONS] -- IMAGE [COMMAND [ARGS ...]]

and if you wanna run a host application on a new X server instead:

x11docker [OPTIONS] --backend=host -- COMMAND [ARGS ...]

that's the whole vibe check. 💅

🎀 DESCRIPTION 🎀

x11docker runs GUI apps and full desktop environments inside containers, no cap. It plays nice with docker, podman, and nerdctl (that last one is experimental, lowkey a work in progress 👀).

It can run X servers from your host, or X servers inside containers of the image x11docker/xserver. It can even hand X servers over to host applications. And the best part? x11docker always spins up a fresh container from the image and yeets it into the void afterwards. no leftover mess, periodt. 🧚

🌈 Optional features:

  • GPU hardware acceleration
  • Sound with pulseaudio or ALSA
  • Clipboard sharing
  • Printer access
  • Webcam access
  • Persistent home folder
  • Wayland support
  • Language locale creation
  • Several init systems and DBus in container
  • Support of several container runtimes and backends

🔒 Focus on security:

  • Avoids X security leaks using additional X servers.
  • Container user is same as host user to avoid root in container.
  • Restricts container capabilities to bare minimum.

so like, x11docker sets up an unprivileged container user whose password is x11docker, and it locks the container capabilities down to the bare minimum. because of these security restrictions, some applications might act different than they would under a regular docker|podman run command — not a bug bestie, it's the whole point. 💀 if you want a less restricted setup, go for --cap-default or --sudouser.

👑 OPTIONS 👑

real talk first: Short options do not accept arguments. like, none of them. that's the rule. 🙈
  • --help — print this whole message and dip.
  • --license — show the x11docker license (it's MIT) and exit.
  • --version — show the x11docker version and exit.

💫 Basic settings 💫

  • --backend=docker|podman|nerdctl|host — which container backend you're using, or host if you want no container at all.
  • -d, --desktop — tells x11docker there's a desktop environment living in the image.
  • -i, --interactive — run with an interactive tty so you can actually type shell commands. main character energy. ✨
  • --rootless [=yes|no] — use (or disallow) a rootless backend. and here's the default tea if you don't pass --rootless:
    • --backend=docker: rootful unless the environment variable DOCKER_HOST is set.
    • --backend=podman: rootless except started as root.
    • --backend=nerdctl: rootless except started as root
  • --xc [=yes|no|BACKEND] — run the X server inside a container of image x11docker/xserver. BACKEND can specify one of docker|podman|nerdctl.
  • --xonly — just start an empty X server. that's it. that's the whole job. 🫶

🔗 Host integration 🔗

  • --alsa [=ALSA_CARD] — sound via ALSA. you can pick the sound card you want with ALSA_CARD. wanna see your options? list of available sound cards: aplay -l
  • -c, --clipboard [=yes|no|oneway|superv|altv] — share the clipboard with the host. possible arguments:
    • yes — share clipboard in both directions. includes middle-mouse-click selection.
    • oneway — copy clipboard from container to host only. includes middle-mouse-click selection.
    • superv — keys [SUPER][v] copy clipboard from host to container. does not copy middle-mouse-click to container. otherwise same as oneway.
    • altv — same as superv but using keys [ALT][v].
    • no — do not share clipboard.
  • -g, --gpu [=yes|no|iglx|virgl] — GPU access for hardware accelerated OpenGL. works best with open source drivers on host and in image. for closed source nvidia drivers, regard the terminal output 👀. direct rendering is supported by few X server options only.
    • iglx enables indirect rendering (--xorg only).
    • virgl allows GPU access for all X servers, but with limited performance and with --xc only.
  • -I, --network [=NET] — allow internet access. (i.e. allow Docker default.) for the optional argument NET, see Docker documentation of docker run option --network. Docker default is bridge.
  • -l, --lang [=LOCALE] — set language variable LANG=LOCALE in the container. without an arg, the host variable --lang=$LANG is used. if LOCALE is missing in the image, x11docker generates it with localedef in the container (needs locales package). examples for LOCALE: ru, en, de, zh_CN, cz, fr, fr_BE.
  • -P, --printer [=MODE] — share host printers through the cups server. the optional MODE can be socket or tcp. default: socket
  • -p, --pulseaudio [=MODE] — sound with pulseaudio. needs pulseaudio on host and in image. optional arg MODE can be socket, tcp or host. tcp mode needs network access with --network.
  • --webcam — share host webcam device files. say cheese 📸

📁 Shared host folders or volumes 📁

  • -m, --home [=ARG] — create a persistent HOME folder for data storage. default: uses ~/.local/share/x11docker/IMAGENAME. ARG can be another host folder or a volume. (~/.local/share/x11docker has a softlink to ~/x11docker.) (use --homebasedir to change this base storage folder.)
  • --share=ARG — share host file or folder ARG. read-only with ARG:ro . device files in /dev can be shared, too. ARG can also be a volume instead of a host folder.

🖥️ X server options 🖥️

  • --auto — automatically choose the X server (this is the default). influenced notably by options --desktop, --gpu, --wayland, --wm.
  • -h, --hostdisplay — share host display :0. quite bad container isolation! 💀 least overhead of all X server options.
  • -a, --xpra — nested X server supporting seamless and --desktop mode.
  • --xpra2 — like --xpra --xc, but runs the xpra client on the host.
  • -A, --xpra-xwayland — like --xpra, but supports option --gpu.
  • --xpra2-xwayland — like --xpra2, but supports option --gpu.
  • -n, --nxagent — nested X server supporting seamless and --desktop mode. faster than --xpra, but can have compositing issues. 😭
  • -y, --xephyr — nested X server for --desktop mode. without --desktop, a host window manager will be provided (option --wm).
  • -Y, --weston-xwayland — desktop mode like --xephyr, but supports option --gpu. runs from console, within X and within Wayland.
  • -x, --xorg — core Xorg server. runs ootb from console. switch tty with <CTRL><ALT><F1>....<F12>.
⚠️ always switch to a black tty before switching to X to avoid possible crashes. fr fr, don't skip this step.

🦋 Special X server options 🦋

  • -t, --tty — terminal only mode. does not run an X or Wayland server.
  • --xvfb — invisible X server using Xvfb. can be used for custom access with xpra or VNC.
  • -X, --xwayland — blanc Xwayland, needs a running Wayland compositor.
  • --xwin — X server to run in Cygwin/X on MS Windows.
  • --runx — X server wrapper for VcXsrv and Xwin on MS Windows.

💜 Wayland instead of X 💜

  • -W, --wayland — automatically set up a Wayland environment. chooses one of the following options and regards --desktop.
  • -T, --weston — Weston without X for pure Wayland applications. runs in X, in Wayland or from console.
  • -K, --kwin — KWin without X for pure Wayland applications. runs in X, in Wayland or from console.
  • -H, --hostwayland — share host Wayland without X for pure Wayland apps.

🎨 X and Wayland appearance options 🎨

  • --border [=COLOR] — draw a colored border in windows of xpra. argument COLOR can be e.g. orange or #F00. thickness can be specified, too, e.g. red,3. default: blue,1
  • --dpi=N — dpi value (N dots per inch) to submit to X clients. influences font size of some applications.
  • -f, --fullscreen — run in fullscreen mode. give it the whole screen, it deserves it. 👑
  • --output-count=N — multiple virtual monitors for Weston or KWin.
  • --rotate=N — rotate display (--xorg, --weston and --weston-xwayland). allowed values: 0, 90, 180, 270, flipped, flipped-90, flipped-180, flipped-270. (flipped means mirrored)
  • --scale=N — scale/zoom factor N for xpra, Xorg or Weston. allowed for --xpra* and --xorg: 0.25...8.0. allowed for --weston and --weston-xwayland: 1...9.
  • --size=WxH — screen size of the new X server (e.g. 800x600).
  • -w, --wm [=ARG] — provide a host window manager to container applications. (in case of --xc, only openbox is provided.) possible ARG:
    • host — autodetection of a host window manager.
    • COMMAND — command for a desired host window manager.
    • none — run without a window manager. same as --desktop.
  • -F, --xfishtank — show fish tank on new X server. 🐠 iconic, no notes.

⚙️ X and Wayland special configuration ⚙️

  • --checkwindow [=ARG] — run container until all X windows are closed. if ARG is provided, run the container as long as grep can find ARG in output of xwininfo -root -children. this option helps to keep alive containers with self-forking applications like gnome-terminal or to stop endless running ones like chromium.
  • --clean-xhost — disable xhost access policies on host display.
  • --composite [=yes|no] — enable or disable X extension Composite. default is yes except for --nxagent. can cause or fix issues with some applications on nxagent.
  • --display=N — run new X server with display number N. must not be already in use.
  • --keymap=LAYOUT — set keyboard layout for the new X server, e.g. de, us, ru. for possible LAYOUT, look at /usr/share/X11/xkb/symbols.
  • --vt [=N] — use vt / tty N. without optional N, search an unused tty.
  • --westonini=FILE — custom weston.ini for --weston and --weston-xwayland.
  • --xhost [=STR] — set xhost STR on the new X server (see man xhost). without optional STR, will set: +SI:localuser:$USER . (use with care. --xhost=+ allows access for everyone).
  • --xoverip [=yes|no|listentcp|socat] — connect to X over TCP network. special setups only, usually only enabled by x11docker itself.
    • yes — use listentcp if possible, otherwise socat.
    • no — use shared unix socket (general default).
    • listentcp — use X option -listen tcp.
    • socat — use socat to create a fake TCP connection.
  • --xauth [=yes|trusted|untrusted|no] — sets up X cookie authentication, the little bouncer at the door of your display 🎀 Here's the tea on the possible arguments:
    • yes | trusted — turns on cookie authentication with trusted cookies. (This is the general x11docker default, bestie, so it's already serving 💅)
    • untrusted — untrusted cookie for untrusted apps, which limits their access to X resources. Lowkey the move if you wanna avoid MIT-SHM when you're using --hostdisplay.
    • no — disables cookie authentication entirely. Dangerous! Like, actually dangerous, not cute-dangerous 💀
  • --xtest [=yes|no] — turn the XTEST X extension on or off. Default is yes for --xpra and --xvfb, and no for every other X server. You literally need this to let xpra do keyboard and mouse control ✨

👑 Container user settings 👑

  • --group-add=GROUP — add the container user to group GROUP. Simple as that, no notes 🫶
  • --hostuser=USER — run X (and the container user) as user USER. Default is whatever $(logname) says. Heads up: x11docker must run as root for this to work.
  • --password [=WORD] — change the container user's password and then exit. If you don't hand it a WORD argument it'll ask you interactively, no judgement. It's stored encrypted in ~/.config/x11docker/passwd 🔐
  • --sudouser [=nopasswd] — allow su and sudo for the container user. Use with care, because this is a severe reduction of the default x11docker security, fr fr 😭 You can optionally get passwordless sudo with the argument nopasswd. The default password is x11docker.
  • --user=U — create container user U (where U is a name or a uid). Default is the same as the host user. U can also be an unknown user id, wild but okay. You can specify a group id by making U be user:gid. And special case, iconique behaviour incoming: --user=RETAIN keeps the image's user settings 💅

🔥 Container capabilities 🔥

In most setups x11docker sets --cap-drop=ALL and --security-opt=no-new-privileges, and it will show warnings if it's doing anything else. Custom capabilities can be added with --cap-add=CAP after -- ✨

  • --cap-default — allow the default container capabilities. This includes --newprivileges=yes.
  • --ipc [=ARG] — with no optional ARG it sets the run option --ipc=host, which is discouraged, just so you know 👀 For the other possible ARG values, go check the docker run reference.
  • --limit [=FACTOR] — caps the CPU and RAM usage of the container at currently free RAM × FACTOR and available CPUs × FACTOR. Allowed range is 0 < FACTOR <= 1. If you use --limit with no FACTOR argument, the default is 0.5 🌸
  • --newprivileges [=yes|no|auto] — sets or unsets the run option --security-opt=no-new-privileges. With no argument the default is yes. In most cases the default is no.

🧚 Container init system, elogind and DBus daemon 🧚

  • --dbus [=system] — runs the DBus user session daemon for the container command. With the argument system it also runs a DBus system daemon. (If you actually want to run a DBus system daemon, better to reach for one of --init=systemd|openrc|runit|sysvinit instead 🫶)
  • --hostdbus — connect to the DBus user session from the host.
  • --init [=tini|systemd|openrc|runit|sysvinit|s6-overlay|none] — run an init system as PID 1 in the container. This solves the zombie reaping issue, because yes, zombies are real and yes, they need dealing with 💀 By default x11docker uses tini or the similar catatonit.
  • --sharecgroup — share /sys/fs/cgroup. This allows elogind inside the container if you use it together with one of --init=openrc|runit|sysvinit.

🌈 Container special configuration: 🌈

  • --env VAR=value — set a custom environment variable.
  • --name=NAME — specify the container name NAME.
  • --no-entrypoint — disable ENTRYPOINT in the image so other commands work too.
  • --no-setup — no x11docker setup inside the running container. This disallows several other options. See also --user=RETAIN.
  • --runtime=RUNTIME — specify the container runtime. Ones x11docker knows about:
    • runc — default runtime of docker.
    • crun — default runtime of podman.
    • nvidia — runtime for nvidia/nvidia-docker images.
    • sysbox-runc — runtime for powerful root in container 👑
  • --shell=SHELL — set the preferred user shell. Example: --shell=/bin/zsh
  • --snap — enable support for Docker in snap.
  • --stdin — forward the stdin of x11docker to the container command.
  • --workdir=DIR — set the working directory to DIR.

🎀 Additional commands 🎀

You might need to move these to the background with CMD & 💅

  • --runasroot=CMD — run command CMD as root in the container.
  • --runasuser=CMD — run command CMD with user privileges in the container, before running the image command.
  • --runfromhost=CMD — run host command CMD on a new X server.

✨ Miscellaneous ✨

  • --build IMAGE — build an image from a Dockerfile from the x11docker repository. Example: x11docker --build x11docker/fvwm . This works for all repositories beginning with dockerfile at https://github.com/mviereck?tab=repositories. It only regards (only) the option --backend=BACKEND, bestie, that's the whole story.
  • --cachebasedir=DIR — custom base folder for cache files.
  • --homebasedir=DIR — custom base folder for the option --home.
  • --fallback [=yes|no] — allow or deny fallbacks when a chosen option can't be fulfilled. By default, fallbacks are allowed 🫶
  • --launcher — create an application launcher with the current options on the desktop, then exit. You can get a menu entry by moving the created *.desktop file into ~/.local/share/applications 🌸
  • --mobyvm — use MobyVM (for WSL2 only, that defaults to Linux Docker).
  • --preset=FILE — read a set of predefined options stored in file FILE. So useful for shortcutting your often-used option combos, honestly iconic 🎀

FILE is searched in the directory /etc/x11docker/preset, or in the directory ~/.config/x11docker/preset.

Multiple lines in FILE are allowed.

Comment lines must begin with # .

Local presets supersede global ones in /etc .

Special case: a preset file with the file name default will be applied automatically for all x11docker sessions 👑

💖 Output of parseable information on stdout 💖

You get output like this, for example: read xenv < <(x11docker --printenv x11docker/check) . The optional argument FILE lets you print the information into a file.

  • --printenv [=FILE] — print variables to access the new display.
  • --printid [=FILE] — print container ID.
  • --printinfofile [=FILE] — print path to internal x11docker info storage.
  • --printpid1 [=FILE] — print host PID of container PID 1.

🦋 Verbosity options 🦋

  • -D, --debug — enable rigorous error control and show some debug output.
  • --printcheck — show dependency check messages.
  • -q, --quiet — suppress x11docker terminal messages 🤫
  • -v, --verbose — be verbose. Output of x11docker.log on stderr.
  • -V — be verbose with colored output 🌈

🧼 Cleanup options (might need root permissions) 🧼

  • --cleanup — clean up orphaned containers and cache files. Those can linger around if x11docker is still running when the system shuts down, lowkey tragic. It terminates currently running x11docker containers too. It regards (only) the option --backend=BACKEND.

💅 Installation options (need root permissions) 💅

These options might not be available in packaged versions of x11docker, just so you know 🫶

  • --install — install x11docker from the current folder. Super useful for installing from an extracted zip file.
  • --update [=diff] — download and install the latest release from github.
  • --update-master [=diff] — download and install the latest master version. The optional argument diff shows the difference between the installed and new version without installing it 👀
  • --remove — remove x11docker from your system. This includes --cleanup. It preserves ~/.local/share/x11docker from the option --home.
  • --remove-oldprefix — before version 7.6.0 x11docker installed itself into /usr/bin. Now it installs into /usr/local/bin. Use --remove-oldprefix to remove /usr/bin installations.

🌸 DEPENDENCIES 🌸

Package names and further optional dependencies live at: https://github.com/mviereck/x11docker/wiki/Dependencies

🌟 Dependencies on host: 🌟

For core functionality x11docker only needs bash, an X server and one of docker, podman or nerdctl. Depending on the chosen options x11docker might need some additional tools. It checks for them on startup and shows messages if some are missing, so you won't be left guessing 💖

  • Most recommended: provide the image x11docker/xserver to run X or Wayland in the container. The image contains all X related dependencies. Obsessed, honestly.

Otherwise, provide on host:

  • Recommended to allow security and convenience:
    • X servers: some of: nxagent xpra Xephyr Xorg
    • Tools: all of: xauth xclip xrandr xhost xinit catatonit
  • Additionally for advanced GPU support: weston Xwayland xpra xdotool

🎀 Dependencies in image: 🎀

No dependencies in image except for a few feature options. The most important ones:

✨ EXIT CODES ✨

  • 0 — Success 💖
  • 64 — x11docker error
  • 130 — Terminated by ctrl-c
  • other — Exit code of command in container

🔥 EXAMPLES 🔥

FVWM window manager:

x11docker --desktop x11docker/fvwm

Xfce desktop:

x11docker --desktop x11docker/xfce

Accelerated glxspheres:

x11docker --gpu x11docker/check glxspheres64

Kodi media center with hardware acceleration, pulseaudio sound, shared Videos folder and persistant HOME:

x11docker --gpu --pulseaudio --home --share=~/Videos erichough/kodi

Firefox with shared Downloads folder and internet access:

x11docker -I --share $HOME/Downloads -- --tmpfs /dev/shm -- jess/firefox

🌈 AUTHOR 🌈

Written by Martin Viereck, Germany. Legend behaviour 🫶

💜 REPORTING BUGS 💜

Please report issues and get help at: https://github.com/mviereck/x11docker/issues

x11docker is published under the MIT licence. Check the output of x11docker --licence . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

🦋 SEE ALSO 🦋

Further documentation at:

And that's the whole page, bestie — the X11DOCKER(1) manual, sourced from the x11docker project, dated as it is, and now fully in your brain 💅✨ Go forth and containerize responsibly, no cap 🎀

📦 where this page comes from